更新记录

1.0.0（2025-10-28）

1.0.0 (2025-10-28)

新增功能

• ✅ 支持高德地图导航功能
• ✅ 从当前位置导航到目的地
• ✅ 指定起点和终点的路线规划
• ✅ 直接导航（支持途经点）
• ✅ 权限检查和自动请求
• ✅ 隐私合规自动处理
• ✅ 运行时配置 API Key
• ✅ 完整的 TypeScript 类型定义
• ✅ 详细的错误码和错误信息

技术特性

• 使用 UTS 语言开发，性能优异
• 支持 Vue 2 和 Vue 3
• 仅支持 Android 平台（iOS 版本开发中）

已知限制

• 仅支持 Android 平台
• 需要用户自行申请高德地图 API Key
• 需要配置正确的包名和 SHA1 签名

平台兼容性

uni-app(4.45)

高德地图导航插件 - 快速使用指南

5 分钟快速上手高德地图导航功能

📋 准备工作清单

• [ ] 注册高德开放平台账号
• [ ] 创建应用并获取 API Key
• [ ] 配置包名和 SHA1 签名
• [ ] 安装插件到项目
• [ ] 配置 manifest.json

🚀 三步快速开始

第一步：获取 API Key（5分钟）

1. 访问高德开放平台

打开 https://console.amap.com/，注册并登录。

2. 创建应用

• 点击 "应用管理" → "我的应用" → "创建新应用"
• 填写应用名称（如：我的导航应用）

3. 添加 Key

• 点击 "添加" 按钮
• 服务平台选择：Android 平台
• 填写配置：

4. 获取 SHA1

# 使用 keytool 查看证书 SHA1
keytool -list -v -keystore your_keystore.keystore

复制 SHA1 值（格式：AA:BB:CC:DD:...），粘贴到高德平台。

5. 复制 API Key

配置完成后，复制生成的 API Key（一串字符串）。

第二步：配置项目（2分钟）

1. 安装插件

在 HBuilderX 中，通过插件市场导入本插件。

2. 配置 manifest.json

打开 manifest.json，配置包名：

{
  "app-plus": {
    "distribute": {
      "android": {
        "packagename": "com.example.myapp"  // 与高德平台配置一致
      }
    }
  }
}

⚠️ 重要： 不要在 sdkConfigs 中配置高德地图！

// ✅ 正确
"sdkConfigs": {}

// ❌ 错误 - 会导致冲突
"sdkConfigs": {
  "maps": {
    "amap": { ... }
  }
}

第三步：编写代码（3分钟）

1. 在 App.vue 中初始化

<script>
import { initAMapServices } from '@/uni_modules/zh-gaodemap'

export default {
  onLaunch() {
    // 初始化高德地图服务
    initAMapServices({
      apiKey: "你的API Key",  // 粘贴第一步获取的 API Key
      success: (res) => {
        console.log('✅ 高德地图初始化成功')
      },
      fail: (err) => {
        console.error('❌ 初始化失败:', err.errMsg)
      }
    })
  }
}
</script>

2. 在页面中使用导航

<template>
  <view>
    <button @click="startNavigation">开始导航</button>
  </view>
</template>

<script>
import { navigationFromCurrentLocation } from '@/uni_modules/zh-gaodemap'

export default {
  methods: {
    startNavigation() {
      navigationFromCurrentLocation({
        endLat: 39.917337,      // 目的地纬度
        endLng: 116.397056,     // 目的地经度
        endName: '故宫博物院',  // 目的地名称
        success: () => {
          console.log('✅ 导航启动成功')
        },
        fail: (err) => {
          console.error('❌ 导航失败:', err.errMsg)
        }
      })
    }
  }
}
</script>

3. 打包测试

• 使用 HBuilderX 云端打包
• 安装到手机测试
• 点击按钮，开始导航！

🎯 常用功能示例

1. 从当前位置导航

import { navigationFromCurrentLocation } from '@/uni_modules/zh-gaodemap'

navigationFromCurrentLocation({
  endLat: 39.917337,
  endLng: 116.397056,
  endName: '故宫博物院'
})

2. 指定起点和终点

import { routePlanning } from '@/uni_modules/zh-gaodemap'

routePlanning({
  startLat: 39.904556,
  startLng: 116.427231,
  startName: '北京站',
  endLat: 39.917337,
  endLng: 116.397056,
  endName: '故宫博物院'
})

3. 途经点导航

import { directNavigation } from '@/uni_modules/zh-gaodemap'

directNavigation({
  endLat: 39.851891,
  endLng: 116.353634,
  endName: '新三余公园',
  wayPoints: [
    { lat: 39.900000, lng: 116.400000, name: '途经点1' }
  ]
})

❓ 常见问题速查

Q: 导航无法使用？

检查清单：

• [ ] 是否调用了 initAMapServices 并传入 API Key
• [ ] 包名是否与高德平台配置一致
• [ ] SHA1 是否配置正确
• [ ] 是否授予了位置权限

Q: 提示"MD5算路失败"？

原因： 包名或 SHA1 不匹配

解决：

1. 检查 manifest.json 的 packagename
2. 检查高德平台的 Package Name 和 SHA1
3. 重新打包测试

Q: 编译时提示依赖冲突？

原因： manifest.json 配置了高德地图

解决： 删除 sdkConfigs.maps.amap 配置