@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/04-/345/256/232/344/275/215.md

@@ -0,0 +1,784 @@
+# 豆包应用插件的端能力 API: 定位
+
+获取设备当前的地理位置信息。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [getLocation](#getlocation) | 获取设备当前的地理位置信息。 |
+| [startLocationUpdate](#startlocationupdate) | 开始接收位置更新。 |
+| [stopLocationUpdate](#stoplocationupdate) | 停止接收位置更新。 |
+| [onLocationChange](#onlocationchange) | 注册地理位置变化回调。<br><br>返回取消监听函数。 |
+| [onLocationChangeError](#onlocationchangeerror) | 注册位置更新异常回调。<br><br>返回取消监听函数。 |
+
+## API 详情
+
+<a id="getlocation"></a>
+### getLocation()
+
+# getLocation
+
+获取设备当前的地理位置信息。
+
+## 扫码预览
+![扫码预览 getLocation](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Flocation%252Fget-location%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.28`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 权限要求
+
+<table>
+<thead>
+<tr><th>类型</th><th>标识</th><th>是否必须</th><th>平台</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td>应用权限</td><td><code>scope.userLocation</code></td><td>必须</td><td>Android、iOS</td><td>需要获取位置信息授权</td></tr>
+<tr><td>系统权限</td><td>地理位置权限</td><td>必须</td><td>Android、iOS</td><td>需要开启系统定位服务并授予位置权限</td></tr>
+</tbody>
+</table>
+
+### 授权行为
+
+- **Android**：首次申请位置权限时，调用会先展示应用授权弹窗；同意后如系统定位权限未授予，会继续申请系统权限。拒绝、取消或撤销应用授权后，再次调用不会重复展示应用授权弹窗，而是直接失败；可通过 `authorize({ scope: 'scope.userLocation' })` 重新发起应用授权。系统仍允许询问时会再次申请系统权限；系统不再允许弹出权限申请时，需在系统设置中开启。
+- **iOS**：调用只检查当前的应用授权和系统定位权限，不主动申请权限。任一权限未授予时调用直接失败。调用 `authorize({ scope: 'scope.userLocation' })` 可以重新发起应用授权；系统仍允许询问时会继续申请系统权限，系统不再允许弹出权限申请时会引导用户前往系统设置。
+
+### 前置条件
+
+- 在应用权限声明中配置 `scope.userLocation`，并确保系统定位服务已开启
+- **iOS**：调用前通过 `authorize({ scope: 'scope.userLocation' })` 完成应用授权和系统定位权限申请
+
+## 使用说明
+
+定位信息属于敏感数据，仅在业务确有需要时调用并妥善处理返回结果。
+
+- 避免高频调用，仅在业务确有需要时获取和使用位置信息
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+getLocation(params?: GetLocationParams): Promise<GetLocationResponse>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>acceptLightLocation</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>仅 Android 生效，需使用 0.0.42 及以上版本的基础库</td><td>是否接受轻定位结果。轻定位会直接利用设备已有的 Wi-Fi 扫描缓存，由服务端快速计算当前位置，缩短定位耗时。</td></tr>
+<tr><td><code>mode</code></td><td><code>number</code></td><td>否</td><td><code>2</code></td><td>取值为 0、1 或 2</td><td>定位模式<br>0：低功耗<br>1：仅设备<br>2：高精度（默认）</td></tr>
+<tr><td><code>source</code></td><td><code>string</code></td><td>否</td><td><code>FlowLocation</code></td><td>1 至 64 个 ASCII 可打印字符</td><td>调用业务方</td></tr>
+<tr><td><code>timeoutMs</code></td><td><code>number</code></td><td>否</td><td><code>30000</code></td><td>正整数，单位毫秒</td><td>超时时间，单位毫秒，默认 30000</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { getLocation } from '@doubao-dev/framework/api';
+
+async function fetchLocation() {
+  try {
+    const locationData = await getLocation();
+    console.log('纬度:', locationData.latitude);
+    console.log('经度:', locationData.longitude);
+    console.log('时间戳:', locationData.timestamp);
+    console.log('行进速度:', locationData.speed);
+    console.log('定位精度:', locationData.accuracy);
+  } catch (error) {
+    console.error('获取位置失败:', error);
+    // 处理错误，例如提示用户开启定位权限
+  }
+}
+
+fetchLocation();
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>accuracy</code></td><td><code>number</code></td><td>否</td><td>定位精度，单位：米</td></tr>
+<tr><td><code>latitude</code></td><td><code>number</code></td><td>否</td><td>纬度</td></tr>
+<tr><td><code>longitude</code></td><td><code>number</code></td><td>否</td><td>经度</td></tr>
+<tr><td><code>speed</code></td><td><code>number</code></td><td>否</td><td>行进速度，单位：米/秒</td></tr>
+<tr><td><code>timestamp</code></td><td><code>string</code></td><td>否</td><td>定位时间戳，单位毫秒</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "latitude": 39.9042,
+  "longitude": 116.4074,
+  "timestamp": "1784088000000",
+  "speed": 0,
+  "accuracy": 15
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 107,
+  "errMsg": "user permission denied"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>106</code></td><td><code>system permission denied</code></td><td>Android、iOS</td><td>系统定位权限被拒绝或系统定位服务不可用</td><td>引导用户在系统设置中开启定位服务与权限后重试</td></tr>
+<tr><td><code>107</code></td><td><code>user permission denied</code></td><td>Android、iOS</td><td>用户拒绝了应用位置授权（scope.userLocation）</td><td>调用 authorize 重新发起应用授权后重试</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+<tr><td><code>116</code></td><td><code>resource not found</code></td><td>资源不存在</td><td>Android</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：用户拒绝应用授权返回 107、系统权限被拒返回 106；定位失败等其他失败统一返回 102。
+- **iOS**：应用授权或系统权限被拒返回 107/106；其他失败（含非法 scope）统一返回 102。
+- **iOS**：mode 为 1 时按高精度模式处理
+
+<a id="startlocationupdate"></a>
+### startLocationUpdate()
+
+# startLocationUpdate
+
+开始接收位置更新。
+
+## 使用限制
+
+> [!WARNING]
+> **iOS**：省略 type 时调用失败；iOS 调用方必须显式传入 type。
+
+## 支持版本
+
+前端库版本不低于 `0.0.32`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 权限要求
+
+<table>
+<thead>
+<tr><th>类型</th><th>标识</th><th>是否必须</th><th>平台</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td>应用权限</td><td><code>scope.userLocation</code></td><td>必须</td><td>Android、iOS</td><td>需要获取位置信息授权</td></tr>
+<tr><td>应用权限</td><td><code>scope.userLocationBackground</code></td><td>按条件</td><td>Android、iOS</td><td>实现会尝试申请后台定位授权，申请失败不阻断本次启动</td></tr>
+<tr><td>系统权限</td><td>地理位置权限</td><td>必须</td><td>Android、iOS</td><td>需要开启系统定位服务并授予位置权限</td></tr>
+</tbody>
+</table>
+
+### 授权行为
+
+- **Android**：调用会主动申请应用位置授权和系统定位权限，并以尽力而为方式申请后台定位授权。拒绝、取消或撤销应用授权后，再次调用直接失败；可通过 `authorize({ scope: 'scope.userLocation' })` 重新发起。后台定位授权失败不阻断启动。
+- **iOS**：调用会主动申请应用位置授权和系统定位权限，并继续尝试后台定位授权。已拒绝或撤销后再次调用直接失败；可通过 `authorize({ scope: 'scope.userLocation' })` 重新发起。后台定位授权失败不阻断启动。
+
+### 前置条件
+
+- 在应用权限声明中配置 `scope.userLocation`，并确保系统定位服务已开启
+
+## 使用说明
+
+需配对调用 stopLocationUpdate。
+
+- 建议在启动前注册 `onLocationChange` 和 `onLocationChangeError`；不再需要更新时及时调用 `stopLocationUpdate`
+- **iOS**：调用时必须显式传入 type
+- `scope.userLocationBackground` 为后台定位授权；豆包会尝试申请，申请失败不阻断本次启动
+- 定位信息属于敏感数据，仅在业务确有需要时持续获取和使用；事件回调频率不固定
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+startLocationUpdate(params?: StartLocationUpdateParams): Promise<LocationOperationResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>type</code></td><td><code>&quot;wgs84&quot; | &quot;gcj02&quot;</code></td><td>否</td><td><code>gcj02</code></td><td>wgs84 表示 WGS-84 坐标系，gcj02 表示 GCJ-02 坐标系</td><td>坐标系类型，支持 wgs84 或 gcj02。iOS：省略 type 时调用失败。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { startLocationUpdate } from '@doubao-dev/framework/api';
+
+await startLocationUpdate({ type: 'gcj02' });
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 1700001,
+  "errMsg": "location permission denied"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>当前豆包客户端未提供持续定位能力（location service 不可用）</td><td>请在支持持续定位的豆包版本中调用</td></tr>
+<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>Android、iOS</td><td>启动过程中被取消（用户取消授权，或授权返回前已调用 stopLocationUpdate）</td><td>需要时重新调用 startLocationUpdate</td></tr>
+<tr><td><code>118</code></td><td><code>already exists</code></td><td>Android、iOS</td><td>持续定位已启动，重复调用 startLocationUpdate</td><td>先调用 stopLocationUpdate 再重新启动</td></tr>
+<tr><td><code>1700001</code></td><td><code>location permission denied</code></td><td>Android、iOS</td><td>用户拒绝应用位置授权或系统定位权限被拒</td><td>调用 authorize 重新发起授权并在系统设置中开启定位权限后重试</td></tr>
+<tr><td><code>1700002</code></td><td><code>location network error</code></td><td>Android、iOS</td><td>位置授权过程中发生网络错误</td><td>检查网络连接后重试</td></tr>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>iOS</td><td>位置授权 scope 非法</td><td>检查应用权限声明中配置的 scope 后重试</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：用户拒绝授权返回 1700001、取消返回 114、授权网络失败返回 1700002；当前豆包客户端不支持持续定位时返回 103；其他失败统一返回 102。
+- **iOS**：用户拒绝授权返回 1700001、取消返回 114、授权网络失败返回 1700002、非法 scope 返回 104；当前豆包客户端不支持持续定位时返回 103；其他失败统一返回 102。
+
+<a id="stoplocationupdate"></a>
+### stopLocationUpdate()
+
+# stopLocationUpdate
+
+停止接收位置更新。
+
+## 支持版本
+
+前端库版本不低于 `0.0.32`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- 无额外前置条件；通常在 `startLocationUpdate` 成功后调用
+
+## 使用说明
+
+- 尚未启动或启动仍在授权阶段时调用会直接成功，可用于安全清理持续定位状态
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+stopLocationUpdate(): Promise<LocationOperationResult>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { stopLocationUpdate } from '@doubao-dev/framework/api';
+
+await stopLocationUpdate();
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 103,
+  "errMsg": "feature not support"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>当前豆包客户端未提供持续定位能力（location service 不可用），无法停止</td><td>请在支持持续定位的豆包版本中调用</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- 未启动或仍在授权阶段调用直接返回成功；仅在已启动后停止失败时返回错误码，其他失败统一返回 102。
+
+<a id="onlocationchange"></a>
+### onLocationChange()
+
+# onLocationChange
+
+注册地理位置变化回调。
+
+## 支持版本
+
+前端库版本不低于 `0.0.32`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+- 建议在调用 `startLocationUpdate` 前注册；不再使用时调用返回的取消函数释放当前监听
+- 定位信息属于敏感数据，仅在业务确有需要时监听和使用；事件回调频率不固定
+
+## 调用方式
+
+### 事件监听 API
+
+```typescript
+onLocationChange(callback: LocationChangeListener): () => void
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { onLocationChange } from '@doubao-dev/framework/api';
+
+const unsubscribe = onLocationChange(({ latitude, longitude }) => {
+  console.log(latitude, longitude);
+});
+
+unsubscribe();
+```
+
+## 回调参数
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>event.accuracy</code></td><td><code>number</code></td><td>否</td><td>位置精确度，单位 m</td></tr>
+<tr><td><code>event.altitude</code></td><td><code>number</code></td><td>否</td><td>高度，单位 m</td></tr>
+<tr><td><code>event.city</code></td><td><code>string</code></td><td>否</td><td>城市信息</td></tr>
+<tr><td><code>event.horizontalAccuracy</code></td><td><code>number</code></td><td>否</td><td>水平精度，单位 m。Android 固定返回 0。</td></tr>
+<tr><td><code>event.latitude</code></td><td><code>number</code></td><td>是</td><td>纬度</td></tr>
+<tr><td><code>event.longitude</code></td><td><code>number</code></td><td>是</td><td>经度</td></tr>
+<tr><td><code>event.speed</code></td><td><code>number</code></td><td>否</td><td>速度，单位 m/s</td></tr>
+<tr><td><code>event.verticalAccuracy</code></td><td><code>number</code></td><td>否</td><td>垂直精度，单位 m。Android 固定返回 0。</td></tr>
+</tbody>
+</table>
+
+## 返回值
+
+返回取消当前监听函数的函数。
+
+### 回调示例
+
+```json
+{
+  "latitude": 39.908823,
+  "longitude": 116.39747,
+  "speed": 0,
+  "accuracy": 12,
+  "altitude": 45,
+  "verticalAccuracy": 0,
+  "horizontalAccuracy": 12,
+  "city": "北京"
+}
+```
+
+## 平台差异
+
+- **Android**：verticalAccuracy 和 horizontalAccuracy 固定返回 0，不表示实际定位精度
+- **Android**：豆包以 1000 毫秒为期望间隔请求位置更新，实际回调频率仍可能受系统影响
+- **iOS**：位置更新频率由系统定位服务调度
+
+<a id="onlocationchangeerror"></a>
+### onLocationChangeError()
+
+# onLocationChangeError
+
+注册位置更新异常回调。
+
+## 支持版本
+
+前端库版本不低于 `0.0.32`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+- 建议在调用 `startLocationUpdate` 前注册；不再使用时调用返回的取消函数释放当前监听
+
+## 调用方式
+
+### 事件监听 API
+
+```typescript
+onLocationChangeError(callback: LocationChangeErrorListener): () => void
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { onLocationChangeError } from '@doubao-dev/framework/api';
+
+const unsubscribe = onLocationChangeError(({ errMsg, errCode }) => {
+  console.log(errMsg, errCode);
+});
+
+unsubscribe();
+```
+
+## 回调参数
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>event.errCode</code></td><td><code>number</code></td><td>否</td><td>错误码</td></tr>
+<tr><td><code>event.errMsg</code></td><td><code>string</code></td><td>是</td><td>错误信息</td></tr>
+</tbody>
+</table>
+
+## 返回值
+
+返回取消当前监听函数的函数。
+
+### 回调示例
+
+```json
+{
+  "errMsg": "location_timeout",
+  "errCode": 0
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errMsg": "location_timeout",
+  "errCode": 0
+}
+```
+
+### 错误码
+
+#### 事件错误码
+
+<table>
+<thead>
+<tr><th>错误字段</th><th>值</th><th>错误信息</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>event.errCode</code></td><td><code>0</code></td><td>-</td><td>Android</td><td>持续定位过程中发生异常</td><td>结合 errMsg 检查系统定位服务、权限和网络环境</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>0</code></td><td><code>location_timeout</code></td><td>iOS</td><td>系统定位超时</td><td>稍后重试，并检查定位环境</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>1</code></td><td><code>location_service_disabled</code></td><td>iOS</td><td>系统定位服务已关闭</td><td>在系统设置中开启定位服务</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>25</code></td><td><code>location_permission_denied</code></td><td>iOS</td><td>尚未完成系统定位授权</td><td>重新发起授权后重试</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>27</code></td><td><code>location_permission_denied</code></td><td>iOS</td><td>用户拒绝系统定位权限</td><td>引导用户在系统设置中开启定位权限</td></tr>
+<tr><td><code>event.errCode</code></td><td><code>29</code></td><td><code>location_permission_denied</code></td><td>iOS</td><td>系统限制定位权限</td><td>提示用户检查系统限制设置</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **iOS**：其他系统定位异常会保留原始 errCode 并返回 location_fail；位置结果无效时事件中可能不包含 errCode
+
+## 相关类型
+
+<a id="getlocationparams"></a>
+### GetLocationParams
+
+#### Properties
+
+• **source?**: `string` - 调用业务方
+• **mode?**: `number` - 定位模式 0：低功耗 1：仅设备 2：高精度（默认）
+• **acceptLightLocation?**: `boolean` - 是否接受轻定位结果。轻定位会直接利用设备已有的 Wi-Fi 扫描缓存，由服务端快速计算当前位置，缩短定位耗时
+• **timeoutMs?**: `number` - 超时时间，单位毫秒，默认 30000
+• **maxCacheMs?**: `number` - 兼容保留字段，当前不生效
+
+<a id="getlocationresponse"></a>
+### GetLocationResponse
+
+#### Properties
+
+• **latitude?**: `number` - 纬度
+• **longitude?**: `number` - 经度
+• **timestamp?**: `string` - 定位时间戳，单位毫秒
+• **speed?**: `number` - 行进速度，单位：米/秒
+• **accuracy?**: `number` - 定位精度，单位：米
+
+<a id="startlocationupdateparams"></a>
+### StartLocationUpdateParams
+
+#### Properties
+
+• **type?**: `'wgs84' | 'gcj02'` - 坐标系类型，支持 wgs84 或 gcj02
+
+<a id="locationoperationresult"></a>
+### LocationOperationResult
+
+定位操作成功时返回的空结果。 @public。
+
+#### Type
+
+`Record<string, never>`
+
+<a id="locationchangelistener"></a>
+### LocationChangeListener
+
+#### Type
+
+`(event: LocationChangeEvent) => void`
+
+<a id="locationchangeevent"></a>
+### LocationChangeEvent
+
+#### Properties
+
+• **latitude**: `number` - 纬度
+• **longitude**: `number` - 经度
+• **speed?**: `number` - 速度，单位 m/s
+• **accuracy?**: `number` - 位置精确度，单位 m
+• **altitude?**: `number` - 高度，单位 m
+• **verticalAccuracy?**: `number` - 垂直精度，单位 m。Android 固定返回 0
+• **horizontalAccuracy?**: `number` - 水平精度，单位 m。Android 固定返回 0
+• **city?**: `string` - 城市信息
+
+<a id="locationchangeerrorlistener"></a>
+### LocationChangeErrorListener
+
+#### Type
+
+`(event: LocationChangeErrorEvent) => void`
+
+<a id="locationchangeerrorevent"></a>
+### LocationChangeErrorEvent
+
+#### Properties
+
+• **errMsg**: `string` - 错误信息
+• **errCode?**: `number` - 错误码