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/startLocationUpdate.md.

startLocationUpdate

开始接收位置更新。

使用限制

WARNING

iOS:省略 type 时调用失败;iOS 调用方必须显式传入 type。

支持版本

前端库版本不低于 0.0.32。

支持平台

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

支持场景

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

接入准备

权限要求

类型标识是否必须平台说明
应用权限scope.userLocation必须Android、iOS需要获取位置信息授权
应用权限scope.userLocationBackground按条件Android、iOS实现会尝试申请后台定位授权,申请失败不阻断本次启动
系统权限地理位置权限必须Android、iOS需要开启系统定位服务并授予位置权限

授权行为

  • Android:调用会主动申请应用位置授权和系统定位权限,并以尽力而为方式申请后台定位授权。拒绝、取消或撤销应用授权后,再次调用直接失败;可通过 authorize({ scope: 'scope.userLocation' }) 重新发起。后台定位授权失败不阻断启动。
  • iOS:调用会主动申请应用位置授权和系统定位权限,并继续尝试后台定位授权。已拒绝或撤销后再次调用直接失败;可通过 authorize({ scope: 'scope.userLocation' }) 重新发起。后台定位授权失败不阻断启动。

前置条件

  • 在应用权限声明中配置 scope.userLocation,并确保系统定位服务已开启

使用说明

需配对调用 stopLocationUpdate。

  • 建议在启动前注册 onLocationChange 和 onLocationChangeError;不再需要更新时及时调用 stopLocationUpdate
  • iOS:调用时必须显式传入 type
  • scope.userLocationBackground 为后台定位授权;豆包会尝试申请,申请失败不阻断本次启动
  • 定位信息属于敏感数据,仅在业务确有需要时持续获取和使用;事件回调频率不固定

调用方式

异步 API

startLocationUpdate(params?: StartLocationUpdateParams): Promise<LocationOperationResult>

入参

名称类型必填默认值约束说明
type"wgs84" | "gcj02"否gcj02wgs84 表示 WGS-84 坐标系,gcj02 表示 GCJ-02 坐标系坐标系类型,支持 wgs84 或 gcj02。iOS:省略 type 时调用失败。

调用示例

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

await startLocationUpdate({ type: 'gcj02' });

成功返回

无返回字段。

返回示例

{}

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

{
  "errNo": 1700001,
  "errMsg": "location permission denied"
}

错误码

errNoerrMsg平台触发条件处理建议
103feature not supportAndroid、iOS当前豆包客户端未提供持续定位能力(location service 不可用)请在支持持续定位的豆包版本中调用
114operation cancelledAndroid、iOS启动过程中被取消(用户取消授权,或授权返回前已调用 stopLocationUpdate)需要时重新调用 startLocationUpdate
118already existsAndroid、iOS持续定位已启动,重复调用 startLocationUpdate先调用 stopLocationUpdate 再重新启动
1700001location permission deniedAndroid、iOS用户拒绝应用位置授权或系统定位权限被拒调用 authorize 重新发起授权并在系统设置中开启定位权限后重试
1700002location network errorAndroid、iOS位置授权过程中发生网络错误检查网络连接后重试
104invalid parameteriOS位置授权 scope 非法检查应用权限声明中配置的 scope 后重试

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS

平台差异

  • Android:用户拒绝授权返回 1700001、取消返回 114、授权网络失败返回 1700002;当前豆包客户端不支持持续定位时返回 103;其他失败统一返回 102。
  • iOS:用户拒绝授权返回 1700001、取消返回 114、授权网络失败返回 1700002、非法 scope 返回 104;当前豆包客户端不支持持续定位时返回 103;其他失败统一返回 102。