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

getLocation

获取设备当前的地理位置信息。

扫码预览

扫码预览 getLocation

支持版本

前端库版本不低于 0.0.28。

支持平台

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

支持场景

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

接入准备

权限要求

类型标识是否必须平台说明
应用权限scope.userLocation必须Android、iOS需要获取位置信息授权
系统权限地理位置权限必须Android、iOS需要开启系统定位服务并授予位置权限

授权行为

  • Android:首次申请位置权限时,调用会先展示应用授权弹窗;同意后如系统定位权限未授予,会继续申请系统权限。拒绝、取消或撤销应用授权后,再次调用不会重复展示应用授权弹窗,而是直接失败;可通过 authorize({ scope: 'scope.userLocation' }) 重新发起应用授权。系统仍允许询问时会再次申请系统权限;系统不再允许弹出权限申请时,需在系统设置中开启。
  • iOS:调用只检查当前的应用授权和系统定位权限,不主动申请权限。任一权限未授予时调用直接失败。调用 authorize({ scope: 'scope.userLocation' }) 可以重新发起应用授权;系统仍允许询问时会继续申请系统权限,系统不再允许弹出权限申请时会引导用户前往系统设置。

前置条件

  • 在应用权限声明中配置 scope.userLocation,并确保系统定位服务已开启
  • iOS:调用前通过 authorize({ scope: 'scope.userLocation' }) 完成应用授权和系统定位权限申请

使用说明

定位信息属于敏感数据,仅在业务确有需要时调用并妥善处理返回结果。

  • 避免高频调用,仅在业务确有需要时获取和使用位置信息

调用方式

异步 API

getLocation(params?: GetLocationParams): Promise<GetLocationResponse>

入参

名称类型必填默认值约束说明
acceptLightLocationboolean否false仅 Android 生效,需使用 0.0.42 及以上版本的基础库是否接受轻定位结果。轻定位会直接利用设备已有的 Wi-Fi 扫描缓存,由服务端快速计算当前位置,缩短定位耗时。
modenumber否2取值为 0、1 或 2定位模式
0:低功耗
1:仅设备
2:高精度(默认)
sourcestring否FlowLocation1 至 64 个 ASCII 可打印字符调用业务方
timeoutMsnumber否30000正整数,单位毫秒超时时间,单位毫秒,默认 30000

调用示例

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();

成功返回

名称类型必返说明
accuracynumber否定位精度,单位:米
latitudenumber否纬度
longitudenumber否经度
speednumber否行进速度,单位:米/秒
timestampstring否定位时间戳,单位毫秒

返回示例

{
  "latitude": 39.9042,
  "longitude": 116.4074,
  "timestamp": "1784088000000",
  "speed": 0,
  "accuracy": 15
}

错误处理

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

失败示例

{
  "errNo": 107,
  "errMsg": "user permission denied"
}

错误码

errNoerrMsg平台触发条件处理建议
106system permission deniedAndroid、iOS系统定位权限被拒绝或系统定位服务不可用引导用户在系统设置中开启定位服务与权限后重试
107user permission deniedAndroid、iOS用户拒绝了应用位置授权(scope.userLocation)调用 authorize 重新发起应用授权后重试

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS
116resource not found资源不存在Android

平台差异

  • Android:用户拒绝应用授权返回 107、系统权限被拒返回 106;定位失败等其他失败统一返回 102。
  • iOS:应用授权或系统权限被拒返回 107/106;其他失败(含非法 scope)统一返回 102。
  • iOS:mode 为 1 时按高精度模式处理