用途:输入 { lat, lng },输出结构化地址与用于界面展示的 formatted 字段,作为 geolocation 的补充。注意它不同于正向地理编码(地址→坐标)和 Places Details。
主要能力:支持多种提供方。Google Geocoding API 适合精度与一致性要求高、白标场景,key 放服务端;expo-location 的 reverseGeocodeAsync 在设备端快速返回,质量随操作系统而异;Apple/Android Geocoder 无需 Google 计费,结果为本地数据。建议优先使用项目已采用的提供方;在打车类场景中,后端通常以 Google 为权威来源。
输出模型:Address 包含 formatted,以及可选的 street、number、district、city、state、postalCode、country、placeId(来自 Google 时)和 lat、lng。列表展示用 formatted,需要时用各字段做分析或运费分区。持久化时保存 lat/lng、formatted,有 placeId 则一并保存。
使用方式:地图拖动 pin 时,在 onRegionChangeComplete 或 onDragEnd 触发,先做 300–500ms 防抖,再调用 reverseGeocode(center),最后更新地址标签;不要在 onRegionChange 每帧触发。初始可用当前定位做一次反向编码。
必要规则:按 geohash 或短网格(约 30–100 米)缓存,避免频繁调用 API;locale(language)与用户或租户一致;地址标签显示 loading 状态,不要把原始坐标当作最终目的地展示;遇到 ZERO_RESULTS 要有回退文案(如“地图上选定的位置”)。
限制与反模式:避免拖动每一帧都反向编码;避免把 null 字段拼接成空逗号;避免在同一 helper 中混淆正向与反向;不要为批量反向编码在客户端暴露 Google key,应走后端。完成标准:拖动 pin 后地址稳定可读,loading 与零结果已处理,缓存与防抖降低调用量,租户市场 locale 正确,结构可被 UI 与后端消费。