更新记录

1.0.9（2026-07-20）

修复

• iOS / Android：支持覆盖物点击事件 polyline_click / polygon_click / circle_click（iOS 需 isClickable + onClickedBMKOverlayView）

1.0.5（2026-07-20）

修复

• iOS：坐标转换改为本地 BMKCoordTrans（不再用 Web geoconv，SDK AK 无效）
• iOS：定位申请系统权限、坐标系设为 BD09LL、主线程回调；单次定位前停止连续定位
• iOS：startLocation / 后台定位 ByJs 回调只能执行一次，连续定位仅回传首次结果，避免「callback已释放」
• iOS：推荐上车点增加 SDK 就绪校验与更明确错误信息

1.0.1（2026-07-20）

优化

• Android API Key 从 AndroidManifest.xml 移除，改为由 BaiduMap.initSDK(apiKey) 运行时动态设置

平台兼容性

uni-app(5.0)

uni-app x(5.0)

百度地图 UTS 插件

百度地图原生插件，支持 Android、iOS、HarmonyOS 三端，提供地图显示、标注、覆盖物、搜索、路径规划、定位等功能。

功能特性

1. 地图显示与基础操作

• 地图初始化与配置
• 缩放、平移、旋转、倾斜
• 地图类型切换
• 用户位置显示
• 3D 建筑显示

2. 地图标注（Marker）

• 添加/删除/修改标注点
• 标注点样式配置（图标、缩放、拖拽、层级、透明度）
• 标注点事件监听
• 标注动画

3. 覆盖物（Overlay）

• 折线 / 多边形 / 圆形 / 矩形
• 标签（Label）
• 棱柱（Prism）
• 楼块（Building）
• 地面叠加层（Ground）
• 热力图（HeatMap）/ 六边形图（HexagonMap）
• PopView 弹窗
• 轨迹动画（TrackAnimation）
• 瓦片图层（TileLayer）
• 叠加图层管理（OverlayLayer）

4. 地图搜索

• POI 搜索（周边）
• 地理编码 / 逆地理编码
• 地点输入提示（Suggestion）
• 天气查询
• 推荐上车点
• 行政区边界查询

5. 路径规划

• 驾车 / 步行 / 公交路径规划
• 规避收费、高速、拥堵

6. 定位功能

• 持续定位（onLocationUpdate + startLocation）/ 单次定位
• 获取当前位置 / 详细地址 / 周边 POI
• 后台定位

7. 地图事件

• 点击 / 长按事件
• 标注点击事件
• 地图状态变化

8. 地图控制

• 缩放控制 / 指南针 / 比例尺
• 交通路况 / 建筑物 / 定位图层显隐
• 地图俯仰角度动画
• 经纬度与像素互转
• 坐标转换
• 距离 / 面积计算
• 多边形内点判断

9. 工具

• 地图截图
• 短链接生成
• 跳转百度地图 App

10. 地图截图

• 截取当前地图视图
• 支持自定义质量和尺寸

安装方法

1. 复制插件

将 uni_modules/d-baidu-map 目录复制到你的项目 uni_modules 目录下。

2. 配置百度地图 API Key

Android 平台

在 app-android/AndroidManifest.xml 中添加：

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

iOS 平台

在 app-ios/Info.plist 中添加：

<key>BMKMapSDKAPIKey</key>
<string>YOUR_API_KEY</string>

HarmonyOS 平台

在代码中初始化：

BaiduMap.setupSDK('YOUR_API_KEY')

3. 配置权限

Android 平台

在 AndroidManifest.xml 中添加：

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

iOS 平台

在 Info.plist 中添加：

<key>NSLocationWhenInUseUsageDescription</key>
<string>需要获取您的位置信息以提供地图服务</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>需要持续获取您的位置信息以提供导航服务</string>

HarmonyOS 平台

在 module.json5 中添加：

{
  "requestPermissions": [
    {"name": "ohos.permission.LOCATION"},
    {"name": "ohos.permission.APPROXIMATELY_LOCATION"},
    {"name": "ohos.permission.INTERNET"}
  ]
}

使用示例

1. 初始化地图

import { BaiduMap } from '@/uni_modules/d-baidu-map'

BaiduMap.setupSDK('YOUR_API_KEY')
BaiduMap.createMapView({
  center: { latitude: 39.9042, longitude: 116.4074 },
  zoom: 12
})

2. 添加标注

const markerId = BaiduMap.addMarker({
  position: { latitude: 39.9042, longitude: 116.4074 },
  title: '北京天安门',
  snippet: '中华人民共和国的象征',
  draggable: true,
  visible: true,
  zIndex: 10
})

BaiduMap.removeMarker(markerId)

3. 添加覆盖物

// 折线
BaiduMap.addPolyline({
  points: [
    { latitude: 39.9042, longitude: 116.4074 },
    { latitude: 39.9142, longitude: 116.4174 }
  ],
  color: 0xFF0000FF,
  width: 5
})

// 多边形 / 圆形 / 矩形 / 标签 / 棱柱 / 楼块 / 地面叠加层
// 热力图 / 六边形图 / PopView / 轨迹动画 / 瓦片图层

// 清除所有覆盖物
BaiduMap.clearOverlays()

4. 地图搜索

// POI 搜索
BaiduMap.searchPOI({
  keyword: '餐厅',
  location: { latitude: 39.9042, longitude: 116.4074 },
  radius: 1000
}, (result) => {
  console.log(`找到 ${result.total} 个结果`)
})

// 地理编码
BaiduMap.geocode({
  address: '北京市天安门广场',
  city: '北京'
}, (result) => {
  console.log(`坐标: ${result.location.latitude}, ${result.location.longitude}`)
})

// 逆地理编码
BaiduMap.reverseGeocode({
  location: { latitude: 39.9042, longitude: 116.4074 }
}, (result) => {
  console.log(`地址: ${result.formattedAddress}`)
})

// 地点输入提示
BaiduMap.suggestionSearch({
  keyword: '天安门',
  city: '北京'
}, (result) => {
  console.log(`找到 ${result.items.length} 个提示`)
})

// 天气查询
BaiduMap.weatherSearch({
  location: { latitude: 39.9042, longitude: 116.4074 }
}, (result) => {
  console.log(`天气: ${result.weather}, 温度: ${result.temperature}°C`)
})

// 推荐上车点
BaiduMap.recommendStopSearch({
  location: { latitude: 39.9042, longitude: 116.4074 }
}, (result) => {
  console.log(`找到 ${result.items.length} 个推荐上车点`)
})

// 行政区边界
BaiduMap.districtSearch({
  keyword: '北京市'
}, (result) => {
  console.log(`返回 ${result.districtList.length} 条数据`)
})

5. 路径规划

// 驾车
BaiduMap.drivingRoute({
  origin: { latitude: 39.9042, longitude: 116.4074 },
  destination: { latitude: 39.9142, longitude: 116.4174 },
  avoidTolls: true
}, (result) => {
  console.log(`距离: ${result.distance} 米，时间: ${result.duration} 秒`)
})

// 步行 / 公交

6. 定位功能

// 持续定位：先注册监听，再启动
BaiduMap.onLocationUpdate((result) => {
  console.log(`坐标: ${result.latitude}, ${result.longitude}`)
})
BaiduMap.startLocation({
  enableHighAccuracy: true,
  timeout: 10000
})
BaiduMap.stopLocation()

// 单次定位
BaiduMap.requestSingleLocation({}, (result) => {
  console.log(`坐标: ${result.latitude}, ${result.longitude}`)
})

// 获取当前位置（经纬度 + 详细地址 + 周边POI）
BaiduMap.getCurrentLatLng({}, (result) => { /* ... */ })
BaiduMap.getCurrentAddress({}, (result) => { /* ... */ })
BaiduMap.getLocationDescribe({}, (result) => { /* ... */ })
BaiduMap.getNearbyPoi({}, (result) => { /* ... */ })

7. 地图事件

BaiduMap.setMapEventListener('click', (event) => {
  console.log(`地图点击: ${event.latitude}, ${event.longitude}`)
})

BaiduMap.setMapEventListener('longpress', (event) => {
  console.log(`长按: ${event.latitude}, ${event.longitude}`)
})

BaiduMap.setMarkerEventListener(markerId, 'click', (event) => {
  console.log(`标注点击: ${event.markerId}`)
})

8. 工具

// 截图
BaiduMap.takeScreenshot({ quality: 80 }, (base64) => {
  console.log(`截图长度: ${base64.length}`)
})

// 短链接
BaiduMap.getShortUrl({
  latitude: 39.9042, longitude: 116.4074
}, (result) => {
  console.log(`短链接: ${result.shortUrl}`)
})

// 跳转百度地图 App
BaiduMap.openBaiduMap({
  latitude: 39.9042, longitude: 116.4074,
  name: '天安门'
}, (result) => { /* ... */ })

// 距离计算
const dist = BaiduMap.calculateDistance(39.9042, 116.4074, 39.9142, 116.4174)

// 面积计算
const area = BaiduMap.calculateArea([
  { latitude: 39.9042, longitude: 116.4074 },
  { latitude: 39.9142, longitude: 116.4174 },
  { latitude: 39.9242, longitude: 116.4274 }
])

// 点是否在多边形内
const inside = BaiduMap.isPointInPolygon(
  { latitude: 39.9042, longitude: 116.4074 },
  [ /* polygon points */ ]
)

// 坐标转换
BaiduMap.coordConvert({ latitude: 39.9042, longitude: 116.4074, fromType: 'wgs84', toType: 'bd09ll' }, (result) => { /* ... */ })

9. 地图控制

// 缩放 / 移动动画
BaiduMap.animateCamera(39.9042, 116.4074, 15, 1000)

// 经纬度 ↔ 像素
const pt = BaiduMap.ll2Pixel(39.9042, 116.4074)
const ll = BaiduMap.pixel2ll(200, 200)

// 图层显隐
BaiduMap.showTrafficLayer(true)
BaiduMap.showBuildingsLayer(true)
BaiduMap.showLocationLayer(true)

// 地图内边距
BaiduMap.setMapPadding(0, 0, 200, 0)

类型定义

完整类型定义见 utssdk/interface.uts。关键类型：

LatLng

type LatLng = {
  latitude: number
  longitude: number
}

MapOptions

type MapOptions = {
  center?: LatLng
  zoom?: number
  minZoom?: number
  maxZoom?: number
  zoomEnabled?: boolean
  scrollEnabled?: boolean
  rotateEnabled?: boolean
  overlookEnabled?: boolean
  mapType?: number
  showsUserLocation?: boolean
}

MarkerOptions / PolylineOptions / PolygonOptions / CircleOptions / RectangleOptions

标准覆盖物配置参数，支持 id、visible、zIndex、颜色等。

LabelOptions / PrismOptions / BuildingOptions / GroundOptions

• Label: position, text, fontSize, fontColor, visible, zIndex
• Prism: points: LatLng[], height, fillColor, visible, zIndex
• Building: position, height, levels, fillColor, visible
• Ground: bounds: Bounds, imageUrl, visible, zIndex

HeatMapOptions / HexagonMapOptions

• HeatMap: points: HeatMapPoint[], radius, opacity, gradient
• HexagonMap: points: HexagonMapPoint[], radius, opacity

SuggestionSearchOptions / SuggestionSearchResult

type SuggestionSearchOptions = {
  keyword: string
  city: string
  location?: string // "lat,lng"
}
type SuggestionSearchResult = {
  items: SuggestionItem[]
  errorCode: number
}

WeatherSearchOptions / WeatherResult

type WeatherSearchOptions = {
  location: LatLng
}
type WeatherResult = {
  temperature: string
  weather: string
  windDirection: string
  humidity: string
  pm25: string
  errorCode: number
}

RecommendStopOptions / RecommendStopResult

type RecommendStopOptions = {
  location: LatLng
}
type RecommendStopResult = {
  items: RecommendStopItem[]
  errorCode: number
}

DistrictSearchOptions / DistrictSearchResult

type DistrictSearchOptions = {
  keyword: string
}
type DistrictSearchResult = {
  districtList: object[]
  errorCode: number
}

定位相关

type LocationResult = {
  latitude: number; longitude: number
  altitude?: number; accuracy?: number
  heading?: number; speed?: number
  timestamp?: number; errorCode?: number; errorInfo?: string
}
type SingleLocationResult = {
  latitude: number; longitude: number
  address?: string; country?: string; province?: string; city?: string; district?: string
  poiList?: PoiItem[]
  errorCode?: number; errorInfo?: string
}

完整类型列表见 utssdk/interface.uts。

平台支持

注意事项

1. API Key 配置：使用前必须配置百度地图 API Key，请到百度地图开放平台申请。
2. 权限申请：定位功能需要申请对应平台的位置权限。
3. HarmonyOS 平台：使用 @bdmap/map、@bdmap/search、@bdmap/base SDK，版本 ≥ 2.0.6。
4. 导航 / 离线地图：暂不提供；请勿依赖相关占位 API。
5. 连续定位：须先调用 BaiduMap.onLocationUpdate(callback)，再 startLocation / enableBackgroundLocation。
6. Android 部分覆盖物：Prism/Building/PopView/HexagonMap/TrackAnimation 使用 SDK 近似实现，效果可能与原生有差异。

更新日志

见 changelog.md。

许可证

MIT License