Capacitor Baidu Location Plugin

一个支持 Capacitor 7 的百度地图定位插件，提供全平台百度定位的功能。

功能特性

• ✅ 支持单次定位, 可通过配置获取地址信息和位置描述
• ✅ 直接配置或动态设置 API Key
• ✅ 定位权限检查和请求
• ✅ 支持坐标类型设置和获取
• ✅ 基于 Capacitor 7

安装

npm install capacitor-baidu-location
npx cap sync

开发依赖

Android 开发依赖

• Java版本 : 21
• Kotlin版本 : 1.9.25
• Gradle版本 : 8.7.2
• gradle wrapper : 8.11.1
• 第三方库 : OkHttp3 3.14.9

iOS 开发依赖

• Xcode 16 +
• Swift 5.9 +
• iOS 14 +

Capacitor

• TypeScript 5.1+
• Capacitor 7.+
• NodeJS 20+

配置

配置文件设置（推荐）

插件支持读取配置，这是推荐的配置方式，便于集中管理和构建时配置。web端则直接通过api设置，因为无法在web端读取capacitor配置的内容。

capacitor.config.ts

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CPBaiduLocation: {
      iOSAK: 'your-ios-api-key',
      androidAK: 'your-android-api-key',
    }
  }
};

export default config;

Android 配置

1. API Key 配置
   • 百度地图 API Key 可以通过2种方式配置（优先级从高到低）：
     • 方式一：动态设置：在应用代码中调用 setAK 方法，通过参数设置;
     • 方式二：配置文件设置：在 capacitor.config.ts 中配置 androidAK ，之后一样要调用 setAK 方法，只是不需要传参.

注意：AndroidManifest.xml 需要配置占位值：

<application>
    <meta-data
        android:name="com.baidu.lbsapi.API_KEY"
        android:value="" />
</application>

2. 权限配置 使用定位SDK，需在AndroidManifest.xml文件中Application标签中声明service组件，每个App拥有自己单独的定位service，代码如下：

<application>
    <service android:name="com.baidu.location.f"
        android:enabled="true"
        android:process=":remote" />
</application>

除添加service组件外，使用定位SDK还需添加如下权限：

<!-- 这个权限用于进行网络定位-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"></uses-permission>
<!-- 这个权限用于访问系统接口提供的卫星定位信息-->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"></uses-permission>
<!-- 用于访问wifi网络信息，wifi信息会用于进行网络定位-->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission>
<!-- 获取运营商信息，用于支持提供运营商信息相关的接口-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>
<!-- 这个权限用于获取wifi的获取权限，wifi信息会用来进行网络定位-->
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission>
<!-- 写入扩展存储，向扩展卡写入数据，用于写入离线定位数据-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"></uses-permission>
<!-- 访问网络，网络定位需要上网-->
<uses-permission android:name="android.permission.INTERNET"></uses-permission>

iOS 配置

1. API Key 配置

   • 百度地图 API Key 可以通过2种方式配置（优先级从高到低）：
     • 方式一：动态设置：在应用代码中调用 setAK 方法设置
     • 方式二：配置文件设置：在 capacitor.config.ts 中配置 iOSAK ，之后一样要调用 setAK 方法，只是不需要传参.

2. 权限配置 在 Info.plist 文件中添加以下权限描述：

<key>NSLocationWhenInUseUsageDescription</key>
<string>需要获取您的位置信息</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>需要获取您的位置信息</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>需要获取您的位置信息</string>

Web 配置

仅支持 setAK 方法传参，web端使用百度的 JavaScript API GL ， 如果没传AK，默认使用浏览器内置的地理定位 API。

API

setAK(options)

设置百度地图 API Key。可以覆盖配置文件中的设置，优先级最高。

参数 | 参数 | 类型 | 描述 | |------|------|------| | ak | string | 百度定位的各平台 API Key |

返回值 | 字段 | 类型 | 描述 | |------|------|------| | success | boolean | 设置是否成功 | | errorMessage | string | 错误信息（如果失败） |

说明

• 调用此方法会覆盖配置文件中的 AK 设置
• 可以在应用运行时动态切换 AK

checkAKValidation()

检查 API Key 验证状态。

返回值 | 字段 | 类型 | 描述 | |------|------|------| | valid | boolean | AK 是否有效 | | errorMessage | string | 错误信息（如果无效） |

checkPermission()

检查定位权限状态。

返回值 | 字段 | 类型 | 描述 | |------|------|------| | granted | boolean | 权限是否已授予 |

requestPermission()

请求定位权限。

返回值 | 字段 | 类型 | 描述 | |------|------|------| | granted | boolean | 权限是否已授予 |

setCoordinateType(options)

设置坐标类型。

参数 | 参数 | 类型 | 描述 | |------|------|------| | type | CoordinateType | 坐标类型 |

返回值 | 字段 | 类型 | 描述 | |------|------|------| | success | boolean | 设置是否成功 |

getCoordinateType()

获取当前坐标类型。

返回值 | 字段 | 类型 | 描述 | |------|------|------| | type | CoordinateType | 当前坐标类型 |

getCurrentPosition(options?)

获取当前位置信息。

参数 | 参数 | 类型 | 描述 | 默认值 | |------|------|------|--------| | needAddress | boolean | 是否获取地址信息 | false | | needLocationDescribe | boolean | 是否获取位置描述 | false |

返回值 | 字段 | 类型 | 描述 | |------|------|------| | latitude | number | 纬度 | | longitude | number | 经度 | | accuracy | number | 定位精度（米） | | address | string | 完整地址 | | country | string | 国家 | | province | string | 省份 | | city | string | 城市 | | district | string | 区县 | | street | string | 街道 | | adcode | string | 行政区划代码 | | town | string | 乡镇 | | locationDescribe | string | 位置描述 | | errorCode | number | 错误码 | | errorMessage | string | 错误信息 |

CoordinateType 枚举

| 枚举值 | 描述 | |--------|------| | BD09LL | 百度经纬度坐标 | | BD09MC | 百度墨卡托米制坐标 | | GCJ02 | 国测局坐标 | | WGS84 | WGS84坐标 |

使用示例

基本使用流程

import { CPBaiduLocation, CoordinateType } from 'capacitor-baidu-location';

// 1. 初始化 - 设置 API Key
const initLocation = async () => {
  const result = await CPBaiduLocation.setAK({
    ak: '你的百度地图 API Key'
  });
  
  if (result.success) {
    console.log('API Key 设置成功');
  } else {
    console.error('API Key 设置失败:', result.errorMessage);
  }
};

// 2. 检查并请求权限
const checkAndRequestPermission = async () => {
  const permissionStatus = await CPBaiduLocation.checkPermission();
  
  if (!permissionStatus.granted) {
    const requestResult = await CPBaiduLocation.requestPermission();
    if (!requestResult.granted) {
      console.error('定位权限被拒绝');
      return false;
    }
  }
  
  return true;
};

// 3. （可选）设置坐标类型
const setCoordinateType = async () => {
  await CPBaiduLocation.setCoordinateType({
    type: CoordinateType.BD09LL
  });
};

// 4. 获取当前位置
const getLocation = async () => {
  const hasPermission = await checkAndRequestPermission();
  
  if (!hasPermission) {
    return;
  }
  
  try {
    const result = await CPBaiduLocation.getCurrentPosition({
      needAddress: true,
      needLocationDescribe: true
    });
    
    if (result.errorCode) {
      console.error('定位失败:', result.errorCode, result.errorMessage);
    } else {
      console.log('定位成功:', result);
    }
  } catch (error) {
    console.error('定位异常:', error);
  }
};

// 组合使用
const fullExample = async () => {
  await initLocation();
  await setCoordinateType();
  await getLocation();
};

其他使用示例

// 检查 AK 验证状态
const checkAK = async () => {
  const result = await CPBaiduLocation.checkAKValidation();
  console.log('AK 验证状态:', result.valid ? '有效' : '无效');
};

// 获取当前坐标类型
const getCurrentCoordinateType = async () => {
  const result = await CPBaiduLocation.getCoordinateType();
  console.log('当前坐标类型:', result.type);
};

注意事项

1. API Key 申请：

   • 请确保在 百度地图开放平台 申请了正确的 API Key
   • Android、iOS、web 端需要分别申请不同的 API Key
   • 确保 API Key 已启用定位服务

2. 权限管理：

   • 定位功能需要用户授权
   • 请在适当的时机检查和请求权限

3. 网络连接：

   • 获取地址信息和位置描述需要网络连接
   • 基础定位功能可以在离线状态下使用

错误码说明

Android 错误码

iOS 错误码

版本更新

参考 CHANGELOG.md

故障排除

API Key 设置失败

问题：调用 setAK 方法返回失败 解决方案：

• 检查 API Key 是否正确
• 检查网络连接是否正常
• 确保 API Key 已在百度地图开放平台启用

权限请求失败

问题：用户拒绝了定位权限 解决方案：

• 提示用户定位权限的重要性
• 引导用户在系统设置中手动开启权限
• 优雅处理无权限的情况

相关文档

• 百度地图开放平台
• 百度地图 Android 定位 SDK 文档
• 百度地图 iOS 定位 SDK 文档
• Capacitor 插件开发指南