更新记录

1.0.2（2026-08-27）

初始化

1.0.0（2024-12-10）

初始化，具体功能用法 ，请参考附带demo

平台兼容性

uni-app(4.52)

uni-app x(4.82)

xtf-baidumapview

百度地图 UTS 组件，提供 uni-app x uvue 标准模式组件和传统 uni-app nvue 兼容模式组件。

nvue 组件不支持鸿蒙，也不能用于 uni-app x Vapor 模式。由于 Weex 引擎限制，nvue 的公开命令无同步返回值，所有结果必须监听事件。

目录

1. 配置百度地图 Key
2. uvue 快速开始
3. uvue 参数
4. uvue 事件
5. uvue 方法
6. nvue 快速开始
7. nvue 参数、事件和方法
8. 平台差异和限制

配置百度地图 Key

先在百度地图开放平台为每个 App 平台创建对应类型的 Key。Android Key 必须匹配最终包名和签名 SHA1；iOS Key 必须匹配 Bundle ID；鸿蒙 Key 必须匹配鸿蒙应用配置。不要在不同平台共用不匹配的 Key。

uvue 配置

推荐在 apiKeys 传入各平台 Key。组件按当前运行平台自动选择对应字段：Android 读取 android，iOS 读取 ios，鸿蒙读取 harmony，对应字段为空才读取 defaultKey。

<xtf-baidumapview
  class="map-view"
  :api-keys="{
    defaultKey: null,
    android: 'Android 百度地图 AK',
    ios: 'iOS 百度地图 AK',
    harmony: 'Harmony 百度地图 AK'
  }"
/>

也可以为单个平台传入 apiKey：

<xtf-baidumapview class="map-view" api-key="当前平台的百度地图 AK" />

Key 解析优先级为：apiKey、apikey、apiKeys.当前平台、apiKeys.defaultKey、options.apiKey、options.apiKeys.当前平台、options.apiKeys.defaultKey。Android 在创建地图前会显式完成隐私同意和 SDK 初始化；缺少 Key 会触发 error，code 为 xtf-baidumapview:sdk-not-configured。

nvue 配置

nvue 的 Android 和 iOS 都应在组件创建时传入 api-key，Android 需要使用该 Key 初始化 SDK：

<xtf-baidumapview-nvue class="map-view" api-key="Android 或 iOS 的百度地图 AK" />

在 App.uvue 全局初始化

如果项目只使用组件 apiKey/apiKeys，不必在 App.uvue 重复配置。需要在应用启动阶段提前校验、记录或初始化 Key 时，可采用下列方式。Android 必须在用户同意隐私协议后再调用初始化；组件自身也会执行一次幂等初始化。

<script setup lang="uts">
// #ifdef APP-ANDROID
import { configureXtfBaiduMapSdk } from '@/uni_modules/xtf-baidumapview'
// #endif
// #ifdef APP-IOS
import { setXtfBaiduMapApiKey } from '@/uni_modules/xtf-baidumapview/utssdk/app-ios/config.uts'
// #endif
import { demoMapApiKeys } from '@/pages/demo/shared/demo-data.uts'

function initializeBaiduMapInApp() {
  // #ifdef APP-ANDROID
  const androidKey = demoMapApiKeys.android
  if (androidKey != null && androidKey.length > 0) {
    const status = configureXtfBaiduMapSdk(androidKey, true, 'BD09LL')
    console.log('[xtf-baidumapview] Android SDK state=' + (status['state'] as string))
  }
  // #endif

  // #ifdef APP-IOS
  setXtfBaiduMapApiKey(demoMapApiKeys.ios)
  // #endif

  // #ifdef APP-HARMONY
  // 鸿蒙没有全局 Key 初始化 API。请在每个 xtf-baidumapview 组件上
  // 传入 api-key 或 api-keys.harmony，组件创建时会调用 HAR 的 setApiKey。
  // #endif
}

onLaunch(() => {
  // Android: 放在用户已同意隐私协议后的回调中执行。
  initializeBaiduMapInApp()
})
</script>

示例中的 demoMapApiKeys 可替换为项目自己的配置文件。建议只在该配置文件保存 Key，页面组件统一传 :api-keys="mapApiKeys"：

export const mapApiKeys : XtfBaiduMapApiKeys = {
  defaultKey: null,
  android: 'Android AK',
  ios: 'iOS AK',
  harmony: 'Harmony AK'
}

uvue 快速开始

<template>
  <view class="page-root">
    <xtf-baidumapview
      ref="mapRef"
      class="map-view"
      :api-keys="apiKeys"
      :options="mapOptions"
      :markers="markers"
      @load="onLoad"
      @error="onError"
      @markerclick="onMarkerClick"
      @poichange="onPoiChange"
      @routechange="onRouteChange"
    />
  </view>
</template>

<script setup lang="uts">
import { XtfBaiduMapApiKeys, XtfBaiduMapInitOptions, XtfBaiduMarker } from '@/uni_modules/xtf-baidumapview/utssdk/interface.uts'

const apiKeys : XtfBaiduMapApiKeys = {
  defaultKey: null,
  android: 'Android AK',
  ios: 'iOS AK',
  harmony: 'Harmony AK'
}
const mapOptions : XtfBaiduMapInitOptions = {
  apiKey: null, apiKeys: null, center: { latitude: 39.914935, longitude: 116.403119 },
  zoom: 12, minZoom: 3, maxZoom: 21, overlook: 0, rotation: 0, mapType: 'normal',
  trafficEnabled: false, buidingEnabled: true, heatMapEnabled: false, indoorEnabled: false,
  indoorPoiEnabled: false, showScaleControl: true, showZoomControl: true, showCompass: false,
  showBuildings: true, locationEnabled: false, locationFollowMode: 'normal', logoPosition: 'left-bottom',
  mapLanguage: 'zh', customMapStylePath: null, customMapStyleId: null, padding: null,
  limitBounds: null, clusterEnabled: false, clusterGridSize: 60, gestures: null, locationOptions: null
}
const markers = ref<Array<XtfBaiduMarker>>([])
const mapRef = ref<XtfBaidumapviewComponentPublicInstance | null>(null)

function onLoad() { mapRef.value?.moveToLocation(39.914935, 116.403119, 14) }
function onError(detail : UTSJSONObject) { console.error(detail['code'], detail['message']) }
function onMarkerClick(detail : UTSJSONObject) { console.log(detail['markerId']) }
function onPoiChange(detail : UTSJSONObject) { console.log(detail) }
function onRouteChange(detail : UTSJSONObject) { console.log(detail) }
</script>

<style>
.page-root { flex: 1; display: flex; flex-direction: column; }
.map-view { flex: 1; }
</style>

所有公开方法应在 load 后通过 mapRef.value 调用。

uvue 参数

常用类型参数

const point : XtfBaiduPoint = { latitude: 39.914935, longitude: 116.403119 }
const bounds : XtfBaiduBounds = {
  southwest: { latitude: 39.8, longitude: 116.2 },
  northeast: { latitude: 40.0, longitude: 116.5 }
}
const marker : XtfBaiduMarker = {
  id: 'tiananmen', position: point, title: '天安门', snippet: '北京', iconPath: null,
  anchorX: 0.5, anchorY: 1, rotation: 0, alpha: 1, zIndex: 1, draggable: false,
  flat: false, perspective: false, animateType: null, joinCollision: false,
  collision: false, fixedScreenPosition: null
}

XtfBaiduMapInitOptions 的主要字段：center、zoom、minZoom、maxZoom、overlook、rotation、mapType、trafficEnabled、buidingEnabled、heatMapEnabled、indoorEnabled、indoorPoiEnabled、showScaleControl、showZoomControl、showCompass、locationEnabled、locationFollowMode、logoPosition、mapLanguage、padding、limitBounds、clusterEnabled、clusterGridSize、gestures、locationOptions。注意字段名是 buidingEnabled，这是现有接口的固定拼写。

XtfBaiduGestureOptions 包含：scrollEnabled、overlookEnabled、zoomEnabled、rotateEnabled、doubleClickZoomEnabled、twoTouchClickZoomEnabled、enlargeCenterWithDoubleClickEnabled、flingEnabled，全部为 boolean。

uvue 事件

事件参数均为 UTSJSONObject。所有原生事件会先发出 nativeevent，然后根据 detail['type'] 发出具体事件。

uvue 方法

下列示例中 map 表示 mapRef.value!，p1/p2/p3 表示 XtfBaiduPoint。

地图配置与视野

覆盖物

定位、路线和轨迹动画

检索服务

统一检索 type 支持：geocode、reverse-geocode、city-poi、nearby-poi、bounds-poi、poi-detail、suggestion、aoi、district、indoor-poi、bus-line、recommend-stop、weather、building。结果字段固定为 requestId/type/status/code/message/payload。

离线、导航、工具和释放

nvue 快速开始

<template>
  <div class="page-root">
    <xtf-baidumapview-nvue
      ref="map"
      class="map-view"
      api-key="当前平台 AK"
      :location-enabled="true"
      :markers="markers"
      @load="onLoad"
      @error="onError"
      @locationchange="onLocationChange"
      @poichange="onPoiChange"
      @routechange="onRouteChange"
    />
  </div>
</template>

<script>
export default {
  data() {
    return { markers: [{ id: 'home', latitude: 39.914935, longitude: 116.403119, draggable: false, visible: true }] }
  },
  methods: {
    onLoad() { this.$refs.map.startLocation() },
    onError(event) { console.error(event) },
    onLocationChange(event) { console.log(event) },
    onPoiChange(event) { console.log(event) },
    onRouteChange(event) { console.log(event) },
    search() { this.$refs.map.searchPoiInCity({ city:'北京', keyword:'医院', pageNum:0, cityLimit:false }) },
    route() { this.$refs.map.searchRoute({ mode:'driving', start:{ point:{ latitude:39.9, longitude:116.4 } }, end:{ point:{ latitude:39.91, longitude:116.41 } }, showPolyline:true, zoomToSpan:true, drivingPolicy:null, trafficPolicy:null }) }
  }
}
</script>

<style>
.page-root { flex: 1; }
.map-view { width: 750rpx; height: 600rpx; }
</style>

nvue 参数、事件和方法

nvue Android 事件参数是 Map<string, any>；iOS 页面建议以 UniEvent 接收。两端均先触发 nativeevent，再触发具体事件。不要期待 nvue 方法返回数组、布尔值、请求 ID 或 Promise。

平台差异和限制

使用前请在真机验证 Key、包名、签名、定位权限和 SDK 服务权限。对于未支持能力，组件会通过 error 事件返回 xtf-baidumapview:not-supported 或对应错误码；不要把空数组、false、-1 误判为业务成功。

开发参考

• UTS 语法
• UTS API 插件
• UTS uni-app 兼容模式组件
• UTS 标准模式组件