更新记录

2.0.0（2026-05-17） 下载此版本

初次提交

平台兼容性

uni-app

uni-app x(4.87)

其他

laoqianjunzi-amap

面向 uni-app x 的高德地图运行时插件。插件采用“运行时引导 + 组件画布 + 会话式 API”的组织方式，覆盖地图渲染、定位、检索、路径规划、导航、离线地图、轨迹、围栏、签到、通勤卡片和语音播报等场景。

当前仓库内已包含完整示例中心，适合两类场景：

• 作为业务项目中的高德地图基础设施，直接接入地图、定位与规划能力。
• 作为二次开发底座，沿着现有 utssdk、组件层和示例页继续扩展业务能力。

1. 插件特点

• 运行时统一入口：通过 bootAmapRuntime 一次性注入各平台 Key。
• 组件层直连地图画布：提供 amap-map、amap-journey、amap-offline 三个组件入口。
• 会话式领域 API：按能力拆分为定位、检索、轨迹、围栏、签到、导航、通勤等多个 Session。
• 多端实现分层清晰：app-android、app-ios、app-harmony、web、mp-weixin 分平台组织。
• 示例页可直接运行：插件内置完整 demo 页面，便于快速验证 Key、权限、交互和地图效果。

2. 能力总览

插件源码当前已覆盖以下能力：

更完整的“高德官方示例与本插件实现状态”对照请查看同目录下的 doc.md。

3. 目录结构

uni_modules/laoqianjunzi-amap/
├─ components/
│  ├─ amap-map/             地图画布组件
│  ├─ amap-journey/         导航画布组件
│  ├─ amap-offline/         离线地图面板组件
│  └─ amap-scenario/        综合示例场景组件
├─ pages/demo/              示例页入口
├─ utssdk/
│  ├─ public.uts            对外公开 API
│  ├─ interface.uts         类型定义
│  ├─ runtime.uts           运行时状态与桥接
│  ├─ app-android/          Android 平台实现
│  ├─ app-ios/              iOS 平台实现
│  ├─ app-harmony/          Harmony 平台实现
│  ├─ web/                  Web 平台实现
│  └─ mp-weixin/            微信小程序适配层
├─ demo-keys.uts            示例 Key 存取工具
├─ doc.md                   能力对照文档
└─ readme.md                当前说明文档

4. 环境要求

• HBuilderX：建议 5.07 及以上。
• uni-app x：建议 4.87 及以上。
• Android：minSdkVersion 21。
• iOS：deploymentTarget 12。
• Harmony：插件已包含 @amap/amap_lbs_* 相关依赖声明。

5. 接入前必读

5.1 隐私合规

地图、定位、导航属于敏感能力，接入前请先处理隐私合规：

• 在向用户展示隐私协议时调用 markAmapPrivacyVisible()。
• 在用户明确同意隐私协议后再调用 markAmapPrivacyAccepted()。
• 在用户同意隐私协议前，不要发起定位、导航、周边检索等依赖敏感权限的调用。

推荐在应用启动阶段完成隐私状态标记，再执行运行时初始化。

5.2 Key 配置

插件支持在运行时传入多平台 Key：

• android：Android 原生 SDK Key。
• ios：iOS 原生 SDK Key。
• harmony：Harmony 原生 SDK Key。
• web：高德 Web 服务 Key，公交换乘、多路径、货车路径等 REST 能力建议优先配置该值。

5.3 原生能力说明

本插件包含 Android、iOS、Harmony 原生 SDK 依赖：

• Android 依赖：com.amap.api:navi-3dmap-location-search:10.0.700_3dmap10.0.700_loc6.4.5_sea9.7.2
• iOS Pods：AMapNavi 10.1.600、AMapLocation 2.11.0、AMapSearch 9.7.4
• Harmony 依赖：@amap/amap_lbs_common、@amap/amap_lbs_location、@amap/amap_lbs_navi、@amap/amap_lbs_map3d、@amap/amap_lbs_search

如果你在真机调试 App 端原生能力，请优先使用支持原生插件的调试方式，并确保本地环境已正确集成原生依赖。

6. 运行时初始化

最小可用初始化流程如下：

import {
    bootAmapRuntime,
    markAmapPrivacyAccepted,
    markAmapPrivacyVisible
} from "@/uni_modules/laoqianjunzi-amap"

function setupAmapRuntime() {
    markAmapPrivacyVisible()
    markAmapPrivacyAccepted()
    bootAmapRuntime({
        android: "你的 Android Key",
        ios: "你的 iOS Key",
        harmony: "你的 Harmony Key",
        web: "你的 Web 服务 Key"
    })
}

建议：

• 在应用启动后尽早调用 bootAmapRuntime。
• 如果你的 Key 需要持久化，可参考插件内 pages/demo/demo.uvue 与 demo-keys.uts 的做法。
• 若只使用 App 原生地图，也建议保留 web Key，便于直接启用公交换乘、多路径和货车路径 REST 能力。

7. 快速开始

7.1 页面中放置地图组件

<template>
    <view class="page-shell">
        <amap-map ref="mapRef" class="map-stage" @load="onMapReady"></amap-map>
    </view>
</template>

<script setup lang="uts">
    const mapRef = ref<ComponentPublicInstance | null>(null)

    function onMapReady() {
        mapRef.value?.$callMethod("patchViewport", JSON.stringify({
            lat: 39.917839,
            lon: 116.397029,
            zoom: 14
        }))

        mapRef.value?.$callMethod("renderScene", JSON.stringify({
            markers: [
                { id: "campus_gate", lat: 39.917839, lon: 116.397029, title: "校门", anchor: "bottomCenter" }
            ]
        }))
    }
</script>

<style>
    .page-shell {
        flex: 1;
    }

    .map-stage {
        width: 100%;
        height: 420px;
    }
</style>

7.2 调用定位会话

import { createLocateSession } from "@/uni_modules/laoqianjunzi-amap"

const locateSession = createLocateSession()

function locateOnce() {
    locateSession.capture({ needAddress: true }, (packet) => {
        if ((packet.getNumber("code") ?? -1) != 0) {
            console.log("定位失败", packet)
            return
        }
        console.log("定位成功", packet.getNumber("lat"), packet.getNumber("lon"), packet.getString("address"))
    })
}

7.3 调用检索与路线规划

import { createSearchSession } from "@/uni_modules/laoqianjunzi-amap"

const searchSession = createSearchSession()

function planDriveDemo() {
    searchSession.planDriveAlternatives(39.917839, 116.397029, 39.920210, 116.401480, 10, (packet) => {
        if ((packet.getNumber("code") ?? -1) != 0) {
            console.log("规划失败", packet)
            return
        }
        let paths = packet.getArray("paths") as UTSJSONObject[] | null
        console.log("候选路线数量", paths?.length ?? 0)
    })
}

8. 组件说明

8.1 amap-map

地图主组件，适合承载地图、覆盖物、轨迹、聚合、截图等能力。

已暴露的方法如下：

常用事件：

• load
• mapLoaded
• mapRendered
• markerClick
• markerDrag
• cameraChange
• cameraChangeStart
• denseTap
• mapTap
• mapLongPress
• snapshotReady

8.2 amap-journey

导航画布组件，主要用于导航路线预置与导航启动。

已暴露的方法如下：

组件会通过 journeyEvent 向外转发导航回调。

8.3 amap-offline

离线地图面板组件，适合放入离线地图管理页面。非 App 平台下会退化为空壳视图。

9. Session API 说明

插件把业务能力拆成多个 Session，便于按需创建、按需使用：

9.1 定位 Session 常用方法

options 常见字段：

• needAddress：是否需要地址信息。
• interval：连续定位间隔。
• background：是否后台定位。
• noticeTitle：后台定位通知标题。
• desiredAccuracy：期望精度。

9.2 检索 Session 常用方法

9.3 轨迹 Session 常用方法

10. 全局辅助 API

11. 示例页入口

插件已内置示例中心，建议先跑通 demo 再接入业务页面。

主入口：

• pages/demo/demo.uvue

已提供的独立示例页：

12. 平台差异说明

• App 端是核心能力载体，地图画布、导航、离线面板等能力优先以 App 侧为准。
• amap-journey 与 amap-offline 在非 App 平台下会退化为空壳视图，不应按完整导航能力预期使用。
• Web 侧存在运行时实现，适合做部分地图与服务能力接入；但导航、离线等原生能力不建议按 App 同等级能力理解。
• 源码中包含 mp-weixin 目录，说明存在小程序适配层；如在小程序中使用，请先针对实际业务能力逐项验证。

13. 权限与配置说明

13.1 Android

插件内已声明以下关键权限与组件：

• INTERNET
• ACCESS_FINE_LOCATION
• ACCESS_COARSE_LOCATION
• ACCESS_BACKGROUND_LOCATION
• POST_NOTIFICATIONS
• FOREGROUND_SERVICE
• REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
• WAKE_LOCK
• 高德定位服务与导航、离线地图相关 Activity

如果你的业务不需要后台定位、通知或电池优化处理，请在最终发版前结合业务合规要求再次核对权限清单。

13.2 iOS

插件内已包含以下关键声明：

• NSLocationWhenInUseUsageDescription
• NSLocationAlwaysUsageDescription
• NSLocationAlwaysAndWhenInUseUsageDescription
• NSMotionUsageDescription
• UIBackgroundModes 中的 location、audio

请根据你的实际业务文案，把权限描述修改为能准确说明用途的正式文本。

14. 常见问题

14.1 返回 code = -9，提示“运行时尚未注册”

说明你在调用 Session 或地图组件之前，没有完成运行时初始化。请先确认：

• 已调用 bootAmapRuntime(...)
• 地图组件已触发 load 或 ready
• 页面内通过 ref 拿到组件实例后再调用 $callMethod

14.2 公交换乘、多路径或货车路径失败

这类能力依赖高德 Web 服务接口，请重点检查：

• bootAmapRuntime 是否配置了可用的 web Key
• Key 是否已开通对应服务权限
• 真机网络是否正常

14.3 定位无结果或一直失败

请依次排查：

• 用户是否已同意隐私协议
• 是否已调用 markAmapPrivacyVisible() 和 markAmapPrivacyAccepted()
• 是否已授予前台定位权限
• 是否错误地在非 App 平台期待原生定位或后台定位效果

14.4 导航与离线地图在 Web 不可用

这是预期行为。导航画布和离线面板主要面向 App 原生能力，Web 侧不应按完整原生能力使用。

15. 推荐接入顺序

如果你是第一次集成本插件，推荐按以下顺序推进：

1. 先在 pages/demo/demo.uvue 中填入各平台 Key，确认示例中心能启动。
2. 先打通 createLocateSession() 的权限申请和单次定位。
3. 再接入 amap-map，完成基础地图与 marker 渲染。
4. 最后按业务选择接入检索、路线规划、导航、签到、围栏、轨迹等高级能力。

16. 参考文件

• uni_modules/laoqianjunzi-amap/doc.md：官方示例与插件能力对照。
• uni_modules/laoqianjunzi-amap/pages/demo/demo.uvue：运行时初始化、Key 存储、示例入口。
• uni_modules/laoqianjunzi-amap/components/amap-scenario/amap-scenario.uvue：综合示例的实际调用方式。
• uni_modules/laoqianjunzi-amap/utssdk/public.uts：公开 API 与 Session 实现。
• uni_modules/laoqianjunzi-amap/utssdk/interface.uts：公开类型定义。

如果你准备继续完善插件，建议先从示例页反推 API 使用方式，再回到 utssdk/public.uts 和各平台实现层逐步扩展。