尧图网页设计 
Actual Budget 收款人位置Payee Locations功能完全指南移动端就近记一笔【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual导读Payee Locations 是 Actual Budget 提供的一项基于地理位置的智能记账辅助能力为常用收款人Payee保存一次位置后下次在同一地点记账时Actual 会在收款人自动补全列表中提示附近的收款人甚至一键填入最近的收款人。本文以官方文档 payee-locations.md 为主体结合桌面客户端与核心库loot-core的源码实现完整讲解权限申请、位置保存、就近匹配、位置遗忘与权限故障排查帮助你彻底掌握这一移动端专属功能。一、功能概览让 Actual 记住你在哪购物Payee Locations 的核心思路非常简单让 Actual 记住你常去的消费地点。为某个收款人保存一次位置之后当你再次在该地点记录交易时Actual 会在收款人自动补全payee autocomplete中提示附近的收款人并支持一键填入最近的那个。对于经常光顾的地点——例如楼下便利店、常去的咖啡馆——这可以显著减少记账时的输入成本。从数据模型来看一条收款人位置记录对应 PayeeLocationEntityexport type PayeeLocationEntity { id: string; payee_id: string; // 关联的收款人 latitude: number; // 纬度 longitude: number; // 经度 created_at: number; // 创建时间 distance?: number; // 查询时由服务端计算的距离米 };而附近收款人的返回结果则是 NearbyPayeeEntity把匹配到的收款人实体与其位置记录成对返回export type NearbyPayeeEntity { payee: PayeeEntity; location: PayeeLocationEntity; };重要限制仅移动端交易界面可用Payee Locations只在移动端交易录入界面mobile transaction screen生效不适用于大屏幕/桌面端使用的表格型账本table-based ledger。也就是说这一功能的设计目标是外出途中用手机快速记一笔而非桌面端的日常批量录入场景。二、请求位置权限第一步必须做的事在使用任何与位置相关的功能之前需要先让浏览器获得你的位置访问权。操作路径开始录入一笔新交易Begin entering a new transaction点击收款人字段中的Request Location按钮浏览器会弹出位置授权提示点击允许即可。源码视角浏览器地理定位的底层参数桌面客户端通过 location-adapters.ts 中的BrowserGeolocationAdapter封装了 Web Geolocation API其默认调用参数值得关注const defaultOptions: PositionOptions { enableHighAccuracy: true, // 启用高精度定位 timeout: 15000, // 15 秒超时 maximumAge: 60000, // 接受 1 分钟内的缓存位置 };enableHighAccuracy: true表示尽量使用 GPS 等更精准的定位源timeout: 15000表示若 15 秒内拿不到位置即报错maximumAge: 60000允许复用 1 分钟内的缓存定位结果避免频繁请求。如果浏览器本身不支持地理定位如某些内嵌 WebView适配器会抛出Geolocation is not supported by this browser的错误。谨慎提醒拒绝后无法再次弹窗:::caution 如果在授权弹窗中点击了拒绝Actual 无法再次主动弹出授权请求。你需要在浏览器设置中手动更新该站点的位置权限具体入口因浏览器而异。 :::另外浏览器只会在**安全上下文secure context**中开放地理位置这类敏感 API具体见下文故障排查一节的说明。三、保存收款人位置为常用地点建档保存一个收款人位置的完整流程开始录入一笔新交易输入或选择一个收款人点击收款人字段中出现的Save地理定位按钮继续录入其余交易明细保存交易。500 米阈值Save 按钮何时出现Save 按钮仅在该收款人 500 米内不存在已保存位置时出现。因此如果没看到 Save 按钮说明附近可能已经保存过该收款人的位置。你还可以为同一个收款人保存多个位置——这对于拥有多个分店的商家非常实用例如你在城市不同区域都会光顾的连锁咖啡店每个分店都可保存一条独立记录。源码视角位置如何落库点击 Save 后前端通过SendApiLocationClient.saveLocation调用核心 APIpayee-location-createlocation-adapters.tsasync saveLocation(payeeId: string, coordinates: LocationCoordinates): Promisestring { return await send(payee-location-create, { payeeId, latitude: coordinates.latitude, longitude: coordinates.longitude, }); }位置记录以payee_id latitude longitude created_at的形式持久化到预算文件中前端同时提供payee-locations-get查询某收款人的所有位置与payee-location-delete删除指定位置两个 API对应getLocations与deleteLocation。隐私说明位置数据只属于你的预算你的位置只有在主动点击 Save 时才会被捕获。它和预算中的其他数据一样存储因此如果你使用了自建同步服务器位置数据会在你的各台设备之间同步它绝不会被发送给任何第三方。四、使用最近的收款人就近一键记账保存过一个或多个收款人位置后Actual 就能在你录入交易时推荐最近的收款人或者一键填入。操作流程开始录入一笔新交易如果你的当前位置 500 米内有已保存的收款人收款人自动补全列表会出现Nearby Payees分区同时收款人字段会出现Nearby地理定位按钮二选一从Nearby Payees分区中点选收款人或直接点击Nearby按钮自动填入最近的匹配收款人继续录入其余交易明细保存交易。源码视角就近匹配的 Haversine 计算500 米内有哪些收款人这一判断由核心库的服务端实现入口是 server/payees/app.ts 中的getNearbyPayees它通过 SQL 完成一次性的距离计算与排序使用Haversine 公式计算当前坐标与每个已保存位置之间的球面距离米与前端共享工具库 location-utils.ts 中的calculateDistance是同一套算法对每个收款人的多个位置先计算距离再用ROW_NUMBER/rank 只保留每个收款人距离最近的那条位置distance_rank 1按距离升序排序后返回结果前端拿到 NearbyPayeeEntity 数组渲染出 Nearby Payees 分区maxDistance参数由前端传入即文档中的 500 米阈值。在 location-utils.ts 中距离还会被格式化为人类可读的文本同时给出英制与公制export function formatDistance(meters: number): string { const distanceImperial ${Math.round(meters * metersToFeet)}ft; const distanceMetric ${Math.round(meters)}m; return ${distanceImperial} | ${distanceMetric}; }五、忘记一个位置就地删除Actual没有专门管理全部已保存位置的管理界面。删除位置需要在你正位于或接近该位置时进行在你想要移除的那个收款人位置现场开始录入一笔新交易点击收款人字段打开收款人自动补全点击收款人条目旁的Forget选项见上文自动补全截图。Forget 操作对应前端的deleteLocation调用最终通过payee-location-deleteAPI 删除该条位置记录。六、故障排查位置权限提示为何不出现如果授权提示始终不出现最常见的原因是连接不被浏览器视为安全上下文secure context。浏览器只允许在安全上下文中使用地理位置这类敏感 API。典型场景当你通过 IP 地址例如http://192.168.x.x访问 Actual 服务器时连接是明文 HTTP 而非 HTTPS浏览器会静默拒绝——连授权提示都不会弹出。解决方案是为 Actual 服务器配置 HTTPS。说明出于安全考虑本文不展开外部链接关于 secure context 的具体判定规则可在浏览器开发者文档中检索 Secure Contexts 了解详情。七、总结与延伸阅读Payee Locations 是 Actual 移动端体验中少敲几个字的典型设计一次 Save 建档之后 Nearby 一键填入。其完整链路为浏览器定位BrowserGeolocationAdapter→ 前端 API 客户端SendApiLocationClient→ 核心库服务端payees-get-nearbySQL Haversine 距离计算→ 移动端自动补全 UI。继续深入阅读功能官方文档payee-locations.md收款人管理总览payees.md 与 tour/payees.md前端适配层源码location-adapters.ts距离算法工具location-utils.ts服务端 API 实现server/payees/app.ts数据模型payee-location.ts 与 nearby-payee.ts。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Actual Budget 收款人位置（Payee Locations）功能完全指南：移动端就近记一笔
Actual Budget 收款人位置Payee Locations功能完全指南移动端就近记一笔【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual导读Payee Locations 是 Actual Budget 提供的一项基于地理位置的智能记账辅助能力为常用收款人Payee保存一次位置后下次在同一地点记账时Actual 会在收款人自动补全列表中提示附近的收款人甚至一键填入最近的收款人。本文以官方文档 payee-locations.md 为主体结合桌面客户端与核心库loot-core的源码实现完整讲解权限申请、位置保存、就近匹配、位置遗忘与权限故障排查帮助你彻底掌握这一移动端专属功能。一、功能概览让 Actual 记住你在哪购物Payee Locations 的核心思路非常简单让 Actual 记住你常去的消费地点。为某个收款人保存一次位置之后当你再次在该地点记录交易时Actual 会在收款人自动补全payee autocomplete中提示附近的收款人并支持一键填入最近的那个。对于经常光顾的地点——例如楼下便利店、常去的咖啡馆——这可以显著减少记账时的输入成本。从数据模型来看一条收款人位置记录对应 PayeeLocationEntityexport type PayeeLocationEntity { id: string; payee_id: string; // 关联的收款人 latitude: number; // 纬度 longitude: number; // 经度 created_at: number; // 创建时间 distance?: number; // 查询时由服务端计算的距离米 };而附近收款人的返回结果则是 NearbyPayeeEntity把匹配到的收款人实体与其位置记录成对返回export type NearbyPayeeEntity { payee: PayeeEntity; location: PayeeLocationEntity; };重要限制仅移动端交易界面可用Payee Locations只在移动端交易录入界面mobile transaction screen生效不适用于大屏幕/桌面端使用的表格型账本table-based ledger。也就是说这一功能的设计目标是外出途中用手机快速记一笔而非桌面端的日常批量录入场景。二、请求位置权限第一步必须做的事在使用任何与位置相关的功能之前需要先让浏览器获得你的位置访问权。操作路径开始录入一笔新交易Begin entering a new transaction点击收款人字段中的Request Location按钮浏览器会弹出位置授权提示点击允许即可。源码视角浏览器地理定位的底层参数桌面客户端通过 location-adapters.ts 中的BrowserGeolocationAdapter封装了 Web Geolocation API其默认调用参数值得关注const defaultOptions: PositionOptions { enableHighAccuracy: true, // 启用高精度定位 timeout: 15000, // 15 秒超时 maximumAge: 60000, // 接受 1 分钟内的缓存位置 };enableHighAccuracy: true表示尽量使用 GPS 等更精准的定位源timeout: 15000表示若 15 秒内拿不到位置即报错maximumAge: 60000允许复用 1 分钟内的缓存定位结果避免频繁请求。如果浏览器本身不支持地理定位如某些内嵌 WebView适配器会抛出Geolocation is not supported by this browser的错误。谨慎提醒拒绝后无法再次弹窗:::caution 如果在授权弹窗中点击了拒绝Actual 无法再次主动弹出授权请求。你需要在浏览器设置中手动更新该站点的位置权限具体入口因浏览器而异。 :::另外浏览器只会在**安全上下文secure context**中开放地理位置这类敏感 API具体见下文故障排查一节的说明。三、保存收款人位置为常用地点建档保存一个收款人位置的完整流程开始录入一笔新交易输入或选择一个收款人点击收款人字段中出现的Save地理定位按钮继续录入其余交易明细保存交易。500 米阈值Save 按钮何时出现Save 按钮仅在该收款人 500 米内不存在已保存位置时出现。因此如果没看到 Save 按钮说明附近可能已经保存过该收款人的位置。你还可以为同一个收款人保存多个位置——这对于拥有多个分店的商家非常实用例如你在城市不同区域都会光顾的连锁咖啡店每个分店都可保存一条独立记录。源码视角位置如何落库点击 Save 后前端通过SendApiLocationClient.saveLocation调用核心 APIpayee-location-createlocation-adapters.tsasync saveLocation(payeeId: string, coordinates: LocationCoordinates): Promisestring { return await send(payee-location-create, { payeeId, latitude: coordinates.latitude, longitude: coordinates.longitude, }); }位置记录以payee_id latitude longitude created_at的形式持久化到预算文件中前端同时提供payee-locations-get查询某收款人的所有位置与payee-location-delete删除指定位置两个 API对应getLocations与deleteLocation。隐私说明位置数据只属于你的预算你的位置只有在主动点击 Save 时才会被捕获。它和预算中的其他数据一样存储因此如果你使用了自建同步服务器位置数据会在你的各台设备之间同步它绝不会被发送给任何第三方。四、使用最近的收款人就近一键记账保存过一个或多个收款人位置后Actual 就能在你录入交易时推荐最近的收款人或者一键填入。操作流程开始录入一笔新交易如果你的当前位置 500 米内有已保存的收款人收款人自动补全列表会出现Nearby Payees分区同时收款人字段会出现Nearby地理定位按钮二选一从Nearby Payees分区中点选收款人或直接点击Nearby按钮自动填入最近的匹配收款人继续录入其余交易明细保存交易。源码视角就近匹配的 Haversine 计算500 米内有哪些收款人这一判断由核心库的服务端实现入口是 server/payees/app.ts 中的getNearbyPayees它通过 SQL 完成一次性的距离计算与排序使用Haversine 公式计算当前坐标与每个已保存位置之间的球面距离米与前端共享工具库 location-utils.ts 中的calculateDistance是同一套算法对每个收款人的多个位置先计算距离再用ROW_NUMBER/rank 只保留每个收款人距离最近的那条位置distance_rank 1按距离升序排序后返回结果前端拿到 NearbyPayeeEntity 数组渲染出 Nearby Payees 分区maxDistance参数由前端传入即文档中的 500 米阈值。在 location-utils.ts 中距离还会被格式化为人类可读的文本同时给出英制与公制export function formatDistance(meters: number): string { const distanceImperial ${Math.round(meters * metersToFeet)}ft; const distanceMetric ${Math.round(meters)}m; return ${distanceImperial} | ${distanceMetric}; }五、忘记一个位置就地删除Actual没有专门管理全部已保存位置的管理界面。删除位置需要在你正位于或接近该位置时进行在你想要移除的那个收款人位置现场开始录入一笔新交易点击收款人字段打开收款人自动补全点击收款人条目旁的Forget选项见上文自动补全截图。Forget 操作对应前端的deleteLocation调用最终通过payee-location-deleteAPI 删除该条位置记录。六、故障排查位置权限提示为何不出现如果授权提示始终不出现最常见的原因是连接不被浏览器视为安全上下文secure context。浏览器只允许在安全上下文中使用地理位置这类敏感 API。典型场景当你通过 IP 地址例如http://192.168.x.x访问 Actual 服务器时连接是明文 HTTP 而非 HTTPS浏览器会静默拒绝——连授权提示都不会弹出。解决方案是为 Actual 服务器配置 HTTPS。说明出于安全考虑本文不展开外部链接关于 secure context 的具体判定规则可在浏览器开发者文档中检索 Secure Contexts 了解详情。七、总结与延伸阅读Payee Locations 是 Actual 移动端体验中少敲几个字的典型设计一次 Save 建档之后 Nearby 一键填入。其完整链路为浏览器定位BrowserGeolocationAdapter→ 前端 API 客户端SendApiLocationClient→ 核心库服务端payees-get-nearbySQL Haversine 距离计算→ 移动端自动补全 UI。继续深入阅读功能官方文档payee-locations.md收款人管理总览payees.md 与 tour/payees.md前端适配层源码location-adapters.ts距离算法工具location-utils.ts服务端 API 实现server/payees/app.ts数据模型payee-location.ts 与 nearby-payee.ts。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考