更新记录

1.0.0（2026-11-07）

• 新版发布

平台兼容性

uni-app x(5.25)

其他

yt-bdmapkit 使用说明

iOS、安卓、鸿蒙的百度地图、定位/后台定位、鹰眼轨迹、驾车及步骑行导航插件。

特别提醒

• 购买本插件前，请先试用、并充分自测后再购买，购买后无法退款；
• 如有使用上的疑问、bug，可以进交流群联系作者；
• 结合文档和示例代码集成使用；
• 试用必须先打基座、试用必须先打基座、试用必须先打基座重要事情说三遍；
• 本插件仅支持uniapp-x项目
• 右侧是简易的示例工程，详细的示例工程(包含所有的功能的调用示例)在简易示例工程的static/BDMapDemo.zip
• 请结合插件中 /uni_modules/yt-bdmapkit/API.md 文档和详细的示例工程了解插件的所有功能
• Android手机型号太多，各品牌对手机的限制不尽相同，需要保活而进行的设置也不一样。随着Android系统的更新迭代，保活的难度也在不断加大。最有效的保活方式还是联系厂家添加白名单以实现进程保活。
• uniappX使用本插件保活、后台定位、后台导航功能iOS需在manifest.json/ios App设置中后台运行能力配置audio,location

功能介绍

• 地图显示：支持通过组件展示普通地图、卫星地图及空白底图，切换实时路况、三维楼块、地形及室内地图，并配置自定义地图样式。
• 地图交互：支持移动、缩放、旋转、调整地图倾斜角度、控制各类手势和指南针、比例尺等控件，获取地图点击坐标、当前视角及地图截图。
• 点标记与气泡：支持普通点标记、自定义图片标记、文字标记、更新图标、拖动标记、显示与隐藏气泡，并接收标记及气泡点击事件。
• 图形绘制：支持折线、大地线、分段颜色线、渐变线、圆、多边形、弧线、文字及沿线文字，提供覆盖物更新、显隐、层级调整和删除操作。
• 图片与三维绘制：支持地面图片覆盖物、图片瓦片图层、棱柱、建筑和三维模型等绘制能力；各类材质、模型格式及高级参数按本端支持范围使用。
• 平滑移动与动画：支持图标沿指定轨迹平滑移动，使用自定义小车等图标，按轨迹方向调整朝向，并提供轨迹暂停、继续、重置及进度、结束事件；另提供标记移动、旋转、缩放和透明度等动画。
• 海量点与点聚合：支持海量点图层，以及随地图缩放自动聚合、拆分点标记；支持自定义单点图标、聚合数量样式和聚合点击事件，并提供点数据更新及图层管理。
• 热力图：支持坐标点热力图、权重数据、渐变颜色、透明度、动态更新及显示状态控制，提供蜂窝热力和多帧热力等扩展能力；普通多帧热力及播放控制支持 iOS、鸿蒙，Android 当前仅支持单帧。
• 粒子效果：提供雪花、烟花等地图粒子效果及相关参数配置，实际效果与可用参数受各端 SDK 支持范围限制。
• 定位与后台定位：支持单次定位、连续定位、独立后台定位、地址信息和方向回调；支持后台定位回调重新订阅及缓存读取，并可配合地图显示定位蓝点、自定义定位样式和回到当前位置。
• 地点与地址查询：支持城市关键词、周边、范围内及室内地点检索、输入提示、地点详情、地址转坐标、坐标转地址，以及公交线路、行政区划、天气等查询。
• 出行路线规划：支持驾车、步行、骑行、公交、跨城公交及室内路线查询，获取候选方案、距离、时长和路线坐标，按需在地图上绘制结果；各路线类型按本端支持范围使用。
• 实时导航：支持驾车、步行、骑行的模拟导航和真实 GPS 导航，提供导航算路、路线选择、策略配置、语音播报及后台导航能力；货车、摩托车等高级车型依平台和服务授权使用。步骑行可通过组件内嵌显示，驾车采用原生全屏导航界面。
• 百度鹰眼轨迹（iOS、Android、鸿蒙）：支持实体管理、位置采集与上报、采集和上传间隔配置、手工点上传、缓存管理，以及最新位置、历史轨迹、里程、停留和驾驶行为等查询分析；轨迹纠偏及高级查询参数存在平台差异。
• 离线地图管理：提供城市列表、热门城市和下载记录查询，支持离线地图下载、暂停、更新、删除及状态回调，实际可用范围受各端 SDK 和服务授权限制。
• 收藏与地理工具：支持地点收藏的添加、查询、更新和删除，提供坐标转换、屏幕坐标与经纬度互转、两点距离、区域面积、圆形或多边形内判断、线上最近点、坐标投影、地图测距及调起百度地图等功能。

各端功能并非完全一致，详细参数、支持范围及服务授权要求见插件中/uni_modules/yt-bdmapkit/API.md 。鸿蒙步骑行顶部引导与底部剩余信息仍有已知问题，接入前使用业务 AK 实测。

HarmonyOS 后台功能配置步骤

1. 点击运行->运行到手机/模拟器->运行到鸿蒙
2. 运行成功会在项目根目录下生成unpackage文件夹，找到unpackage/dist/dev/app-harmony/entry,将该文件夹复制到项目根目录下的harmony-configs文件夹下
3. 在 harmony-configs/entry/src/main/module.json5 的已有 entry Ability 中合并下方字段。这是片段，不可替换完整文件；保留 module.type:"entry"、name、mainElement、pages、其他 abilities 等原字段，避免 00303196。

// 合并到完整 module.json5；以下省略其他已有字段
{
    "module": {
        "abilities": [
            {
                // 保留其他已有字段
                "backgroundModes": [
                    "location",
                    "audioPlayback"
                ],
                "continuable": true
            }
        }
    }
}

配置 Key 与初始化

使用 HBuilderX 5.25+。将 uni_modules/yt-bdmapkit 导入项目，使用包含本插件的运行包或自定义基座。最低系统版本：iOS 13、Android 6.0；鸿蒙示例使用 API 20。

在百度开放平台为每个平台申请自己的 AK，并核对应用身份：

示例工程在 pages/index/demo-config.uts 中统一设置三端 AK。AK、鹰眼 serviceId 和 entityName 是不同参数。

import { initialize, BDMapResult } from '@/uni_modules/yt-bdmapkit'

function record(res: BDMapResult) {
  console.log(res.event, res.code, res.message, res.dataJson)
}
let apiKey = ''
// #ifdef APP-IOS
apiKey = '你的iOS AK'
// #endif
// #ifdef APP-ANDROID
apiKey = '你的Android AK'
// #endif
// #ifdef APP-HARMONY
apiKey = '你的鸿蒙AK'
// #endif

// 必须在用户已阅读并同意隐私说明之后调用。
const result = initialize({
  apiKey: apiKey, privacyShown: true, privacyAgreed: true, onEvent: record
})

initialize 是 App 级初始化，不需要 owner，正常情况下只调用一次。检查返回值及鉴权事件；鸿蒙还需等待 initialized 回调且 code=0，再调用业务方法。驾车、步骑行和鹰眼仍按各自顺序配置。

Android 的地图、定位、鹰眼和导航统一使用 initialize.apiKey 传入的 AK，无需在 AndroidManifest.xml 中重复配置。请先完成 initialize，再调用各模块方法。

定位、真实导航及鹰眼采集会在插件内申请必要权限，业务无需提前调用 uni.authorize。后台使用还需要保留以下安装配置：

系统拒绝且不再弹窗时，需引导用户到系统设置开启。迁移鸿蒙示例配置时，合并到宿主自己的配置中，并将应用标识改为实际值。

调用约定

• 所有方法从 @/uni_modules/yt-bdmapkit 导入。完整参数与返回值见 API.md。
• 页面设置唯一的 owner，退出时调用 releaseOwner({owner:'页面标识'})。独立后台定位和鹰眼采集需另行停止。
• 地图操作传组件对应的 mapId，并等待组件 ready。覆盖物 id 用于后续更新、点击匹配和删除。
• 经纬度默认 BD09LL；距离通常为米。定位 timestamp 为毫秒，鹰眼查询时间为秒；各方法的时长单位见参数说明。
• 图片使用 /static/... 或可读本地文件路径，不能传电脑上的绝对路径。

方法同步返回 BDMapResult，异步结果通过 onEvent 或组件事件返回：

// dataJson 是 JSON 字符串，也可能是 'null'。
{ event: 'location', code: 0, message: 'ok', dataJson: '{"latitude":39.915,"longitude":116.404}' }

code=0 可能只表示请求已受理。初始化、定位、算路、采集等操作必须等待对应成功事件，再执行下一步；非 0 时读取 message 和 dataJson。各事件及载荷见 回调说明。

各模块调用顺序

以下操作均在全局初始化成功后使用。代码中的 record 沿用上方的日志函数。

定位

import { locationStart, locationStop } from '@/uni_modules/yt-bdmapkit'

locationStart({owner:'location-page', once:true, needAddress:true, onEvent:record})
// 连续定位改为 once:false，可设置 interval:2（秒）。
// 结束连续定位：locationStop({owner:'location-page'})

地图与标记

<template>
  <yt-bdmapkit map-id="demo-map" owner="map-page" style="height:360px"
    @ready="onMapReady" @event="onMapEvent" @error="onMapEvent" />
</template>
<script setup lang="uts">
import { onUnload } from '@dcloudio/uni-app'
import { mapCamera, mapAddMarker, releaseOwner, BDMapResult } from '@/uni_modules/yt-bdmapkit'
function onMapEvent(res: BDMapResult) { console.log(res.event, res.code, res.dataJson) }
function onMapReady(res: BDMapResult) {
  if (res.code != 0) return
  mapCamera({mapId:'demo-map', latitude:39.915, longitude:116.404, zoom:16})
  mapAddMarker({mapId:'demo-map', id:'destination', latitude:39.915, longitude:116.404,
    title:'终点', icon:'/static/icon_annotation.png', callout:true})
}
onUnload(() => { releaseOwner({owner:'map-page'}) })
</script>

绘制线、面、文字、海量点和轨迹使用 mapAddOverlay；热力使用 mapHeatmap，聚合使用 mapCluster。各功能的参数组合见 地图方法 与 地图功能索引。

鹰眼

traceConfigure 填写自己的 serviceId、gatherInterval、packInterval 和 onEvent；traceStart 填写 entityName，gather:true 表示自动开始采集。等待 traceServiceStarted、traceGatherStarted 成功后使用采集状态。

查询调用 traceQuery，历史轨迹传 kind:'history'、相同的 entityName 及秒单位的 startTime/endTime。iOS 还需等待 traceAuth 成功。采集间隔与上传间隔为 2..300 秒，上传间隔须为采集间隔的整数倍。结束行程调用 traceStop 并等待停止成功；页面退出的 releaseOwner 不会停止鹰眼后台采集。

驾车导航

三端驾车导航均由插件显示完整导航界面，无需挂载 <yt-bdnavigation>。完整调用流程参考示例的 navigation-map.uvue。

import { navigationInitialize, navigationNavigate, BDMapResult } from '@/uni_modules/yt-bdmapkit'

function onDriveEvent(res: BDMapResult) {
  record(res)
  if (res.event == 'navigationInitialized' && res.code == 0) {
    // 真实导航自动取得本次当前位置作为起点，终点替换为用户选择的位置。
    navigationNavigate({owner:'drive-page',
      to:{latitude:30.45, longitude:120.27}, simulated:false})
  }
}
navigationInitialize({owner:'drive-page', onEvent:onDriveEvent})

模拟导航在初始化后调用 navigationNavigate({owner,from,to,simulated:true})，必须提供起点。需要分别控制算路和启动时，使用 navigationCalculate → 等待 navigationRoute(code=0) → navigationStart；navigationStart 默认模拟，真实导航必须显式传 simulated:false。

停止用 navigationStop，结束页面用 navigationDestroy 或 releaseOwner。切换到步骑行前先结束驾车导航。

步行、骑行与电动车导航

1. walkInitialize({owner,kind,onEvent})，kind 为 walking、riding 或 electric；等待 walkInitialized(code=0)。
2. 真实导航先用 locationStart({once:true}) 取得起点，再 walkCalculate({owner,from,to})；模拟导航自行提供有效起终点。
3. 等待 walkRoute(code=0)，再 walkStart({owner,simulated:false})；模拟传 true。walkStart 默认模拟，建议始终显式传值。
4. 结束调用 walkStop、walkDestroy；切换方式前先结束旧导航。

鸿蒙步骑行需先挂载 <yt-bdnavigation> 并等待组件 ready，再执行上述初始化流程。iOS、Android 使用内嵌方式时先初始化、算路，收到 walkRoute(code=0) 后挂载组件并等待 ready，再以 noUI:true 启动。导航示例已分成 pages/index/navigation.uvue（选择起终点）和 pages/index/navigation-map.uvue（导航地图及完整启动流程），可直接参照调用。

鸿蒙已知问题： 当前测试中，步骑行可算路并显示路线，但顶部引导文字及底部剩余信息仍可能为空或停在“准备出发”，尚未解决。接入前请用业务 AK 实测，详见现象与处理方式。

导航展示方式与内嵌范围

以下是当前插件已开放的能力。全屏导航与标签内嵌是两种展示方式；进入示例的 navigation-map.uvue 不代表一定使用标签显示。

三端均未开放驾车导航的标签内嵌显示。 当前 <yt-bdnavigation> 和 mountNavigationView 只绑定步骑行视图；不能通过修改标签高度或传 navigationStart({noUI:true}) 得到半屏驾车导航。鸿蒙的真实无 UI 驾车导航也不提供标签内的驾车地图。

步骑行内嵌时，组件与父容器均需明确宽高，可设置为半屏或固定高度。mode='map' 为主导航地图；iOS 的 multi/background 属于其他视图能力并受授权限制，Android、鸿蒙当前仅支持 map。noUI:true 不等于三端控件完全一致，Android 内嵌视图仍保留 SDK 自带控件。退出时卸载组件，并调用 walkStop / walkDestroy 或 releaseOwner 结束本页会话。

现有示例入口：选择步行或骑行后点击“内嵌导航”，进入 navigation-map.uvue 的标签显示流程；该示例的标签容器目前仍铺满页面，尚无独立的半屏导航示例。参数及绑定顺序见 walkStart 和 mountNavigationView。

全部方法与参数

每个方法的作用、必需参数、返回值、回调以及完整字段表统一见 API.md。三端支持范围见 平台差异；返回 1405 表示当前平台或调用方式不支持。routeCalculate 只查询路线，不会进入导航页面。

导航语音与自定义 TTS

驾车播报开关使用 navigationVoice({owner,enabled:true/false})，步骑行使用 walkVoice({owner,enabled:true/false})。当前接入方式无需业务另配百度语音合成 Key；Android 需要设备安装支持中文的系统语音引擎和语音数据。

当前版本没有对外开放自定义 TTS 引擎接口。 用户已有的 TTS 插件或云端语音服务，暂时不能直接替换本插件播报。现有语音事件也不是三端统一的外部播报接口；不能只关闭语音后监听文本，部分平台会同时停止文本回调。

如需使用自己的 TTS，需要另行适配插件的外部播报接口。当前没有可直接传入第三方引擎、云服务地址或自定义播报回调的方法、参数。

常见问题

地图不出现、一直等待 ready

先检查初始化、隐私同意和 AK 鉴权；鸿蒙等待 initialized 成功。组件及父容器需要明确高度，mapId 需唯一。1403 时先按 message 补齐初始化或授权；不要在 ready 前操作地图。

鸿蒙步骑行有路线，但顶部引导为空、底部剩余信息异常

此问题尚未解决。当前使用的 @bdmap/walk:2.0.7 在测试 AK 环境下，模拟步行、模拟骑行均已真机复现：初始化、算路和启动成功，地图、路线及模拟位置可显示，但顶部路口引导为空，底部距离、时间不更新或停在“准备出发”。是否出现需用业务 AK 实测；算路或启动返回成功不能代表实时引导信息可用。

排查已收敛到百度 SDK 的引导信息权限处理：SDK 返回 WALKING_RIDING_GUIDE_INFO=false，刷新权限返回 AuthenticationTimeoutError。这是 SDK 功能授权，与系统定位权限不同；已授予位置权限仍可出现。目前需要百度确认 AK 权限下发或 SDK 默认界面处理，尚不能认定用户缺少控制台配置或必须购买商业授权。

遇到此现象，请通过百度技术工单提供 SDK 版本、AK、应用标识、初始化/算路/启动事件日志及截图，请其核对上述引导权限和默认界面行为。完整 AK 通过私人工单提供。控制台找不到权限开关时，也使用此渠道咨询。

目前没有已验证的插件侧解决办法。重新打自定义基座、调整布局或切换 noUI 均不能保证恢复缺失的引导数据；walkLicense 未接入鸿蒙对应授权接口，不能用其 iOS 授权参数处理此问题。百度修复或权限恢复后，仍需重新验证顶部引导、剩余信息、语音及真实移动导航。

iOS 第二次进入驾车导航报初始化/鉴权超时 1408

更新当前插件源码后，在 HBuilderX 本地重新编译并运行，单独刷新页面不能更新原生修复。旧版在退出后再次进入驾车时可能出现此问题；页面仍按 navigationInitialize → 等待 navigationInitialized(code=0) → navigationNavigate 调用，退出时使用 navigationDestroy 或 releaseOwner。本项修复不需要修改 AK 或重新云打自定义基座。首次进入也超时时，再检查网络、AK 和完整事件日志。

导航没有声音

开启 navigationVoice / walkVoice，检查媒体音量、静音、蓝牙输出及后台音频配置。Android 还需检查中文语音引擎、语音数据及 Manifest 的 TTS_SERVICE 查询声明。各端使用的引擎及自定义 TTS 限制见导航语音。

Android“更多”按钮空白，或退出轨迹页提示内存泄漏

更新到当前插件版本，在 HBuilderX 本地重新编译并运行。页面退出时正常卸载地图、调用 releaseOwner；手动创建的地图应配对调用 mapDestroy。这两项源码修复本身不需要重新云打自定义基座。

鹰眼 14004、查不到轨迹

核对 AK 已开通鹰眼，serviceId 与 AK 同账号，最终包名/签名或应用标识正确。采集和查询使用相同 entityName；查询时间为秒，检查查询结果内部的业务状态。控制台权限配置修改通常不需要重打基座。

标记气泡空白、自定义图标或聚合不符合预期

标记填写 title/subtitle/bubble 并开启 callout。普通点、海量点、聚合展开单点可传本地图标；聚合多个点显示数量圆标。二维轨迹小车使用 pointMove:true 和 icon，示例 car.png 的车头朝右。不同图标的海量点应分层添加。

热力、棱柱、三维模型看不见，或多帧热力报错

普通热力 radius 为 10..50；蜂窝使用 hexagon:true，radius 为米，例如 200。多帧先添加非空 frames，再播放/停止/切帧；索引从 0 开始，Android 当前仅支持单帧。三维绘制需将相机移到覆盖物附近、放大并倾斜；模型文件及贴图路径应完整可读。

天气、建筑、公交、室内检索失败

使用有效区县编码、uid、建筑 ID 和楼层，并核对服务权限；天气基础查询不能用省级编码代替区县编码。记录 requestId、nativeCode 和 message 以定位失败原因。

是否每次都需要重新打自定义基座

不需要。页面修改按 HBuilderX 的热更新能力运行；原生插件源码修改需本地重新编译部署；SDK、原生库、权限或安装配置变化需更新对应运行包。只修改百度控制台权限通常无需重新打包。