> 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.

# 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
}
```

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/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 时按高精度模式处理
