For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/location/onLocationChange.md.

onLocationChange

注册地理位置变化回调。

支持版本

前端库版本不低于 0.0.32。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片不支持

使用说明

  • 建议在调用 startLocationUpdate 前注册;不再使用时调用返回的取消函数释放当前监听
  • 定位信息属于敏感数据,仅在业务确有需要时监听和使用;事件回调频率不固定

调用方式

事件监听 API

onLocationChange(callback: LocationChangeListener): () => void

入参

无。

调用示例

import { onLocationChange } from '@doubao-dev/framework/api';

const unsubscribe = onLocationChange(({ latitude, longitude }) => {
  console.log(latitude, longitude);
});

unsubscribe();

回调参数

名称类型必返说明
event.accuracynumber否位置精确度,单位 m
event.altitudenumber否高度,单位 m
event.citystring否城市信息
event.horizontalAccuracynumber否水平精度,单位 m。Android 固定返回 0。
event.latitudenumber是纬度
event.longitudenumber是经度
event.speednumber否速度,单位 m/s
event.verticalAccuracynumber否垂直精度,单位 m。Android 固定返回 0。

返回值

返回取消当前监听函数的函数。

回调示例

{
  "latitude": 39.908823,
  "longitude": 116.39747,
  "speed": 0,
  "accuracy": 12,
  "altitude": 45,
  "verticalAccuracy": 0,
  "horizontalAccuracy": 12,
  "city": "北京"
}

平台差异

  • Android:verticalAccuracy 和 horizontalAccuracy 固定返回 0,不表示实际定位精度
  • Android:豆包以 1000 毫秒为期望间隔请求位置更新,实际回调频率仍可能受系统影响
  • iOS:位置更新频率由系统定位服务调度