更新记录

3.3.0（2026-10-14）

• 修复到达途经点后不再继续导航的问题：两端统一为「移除当前目的地 + 保持引导」续行到下一站
• iOS 关闭 stopGuidanceAtArrival（默认 YES 会在途经点处中止引导），并在到达回调中 continueToNextDestination() + 恢复 isGuidanceActive
• Android 在到达回调中对非最终点 continueToNextDestination() + startGuidance()
• 续行后补发一次 onRouteChanged（含新路线 polyline 与剩余距离/时间）；iOS 目的地判定改为按已到达计数，不再依赖 60 米坐标近似

3.2.0（2026-10-13）

• • 界面文案默认改为简体中文，并支持多语言：locale 支持 zh-CN / zh-TW / en，不传时跟随系统语言、兜底简体中文
  • 新增 UTS 层共享文案表 utssdk/i18n.uts；原生导航页与同步返回提示统一走多语言表
  • 条款弹窗公司名改为默认自动取当前 App 的应用名称

平台兼容性

uni-app(4.87)

其他

Google Navigation（应用内 Google 逐向导航）

基于 Google Navigation SDK 的 uni-app UTS 插件（Android 使用 Kotlin、iOS 使用 Swift 原生混编）， 在 App 内直接拉起原生导航页面：先展示路线预览（含 SDK 备选路线），点「开始导航」后进入逐向引导， 全程通过事件回调把位置、剩余距离/时间、偏航重算、到达等数据上报给 JS 业务层。

与「跳转外部 Google Maps App」或「普通地图 + Directions 路线规划」不同，本插件使用的是 Google Navigation SDK 自带导航引擎与导航 UI，可实现真正的应用内逐向导航。

功能特性

导航能力

• 应用内全屏原生导航页，不跳转外部地图 App
• 路线预览 + 备选路线：规划完成后先展示全程概览，点地图上的备选路线即可切换，点「开始导航」才进入逐向引导
• 多途经点顺序导航：waypoints 按数组顺序依次到达，最后一站为最终目的地
• 到达途经点后自动续行到下一站（两端统一：移除当前目的地并保持引导），无需重新规划；到达后同步上报一次 onRouteChanged（含新路线折线、剩余距离/时间）
• 偏航自动重算：偏离路线自动重新规划，并回传重算后的最新路线折线
• 到达识别：区分「途经点」与「最终目的地」，只上报事实，不自动完成业务订单
• Android 端使用 SDK 内置导航 UI（导航头部、ETA 卡片、限速图标、路况提示、行程进度条、重新居中按钮等）

实时数据上报（事件回调）

• 道路吸附（road-snapped）实时位置：经纬度、朝向 bearing、速度 speed
• 剩余距离、剩余时间、预计到达时刻（ETA 时间戳）
• 路线折线：Google 标准编码 polyline，可解码后用于业务侧地图展示
• 路线变化通知（含偏航重算完成后）
• 共 10 类事件，覆盖打开、规划、开始、进度、偏航、位置、到达、错误、关闭全流程

界面与交互

• 竖屏锁定；导航期间屏幕常亮（FLAG_KEEP_SCREEN_ON）
• 页面内自定义「开始导航 / 结束导航」按钮与状态提示；系统返回键与结束按钮都会安全收尾并回调 onClosed
• 语音播报开关（audioGuidance，默认开启）
• 界面文案多语言：简体中文（默认）/ 繁體中文 / English，可用 locale 指定，不传时跟随系统语言
• 首次进入弹出 Google 导航服务条款弹窗，公司名可自行配置

调试与工程化

• 模拟行驶调试：simulate + simulateSpeedMultiplier，无车也能完整调通逐向引导流程
• 一套 JS API 同时支持 Android / iOS，非 App 平台安全降级（返回 success:false）
• 事件统一以 JSON 字符串回调，规避跨语言类型强转问题，JS 侧 JSON.parse 即可使用
• 长驻回调（@UTSJS.keepAlive），导航页存活期间可持续接收事件
• 完整错误码体系：参数、权限、条款、路线规划、初始化失败均有明确错误码与文案

平台兼容性

插件包含原生代码，必须使用自定义基座或云打包运行；标准基座不包含本插件，调用会失败。

安装

1. 在插件市场点击「导入到 HBuilderX」，插件会落到项目的 uni_modules/google-navigation 目录； 手动安装时把整个 google-navigation 目录复制到项目 uni_modules 下即可。
2. 按下方「前置准备」配置自己的 Google API Key 与权限。
3. 使用自定义基座运行，或直接云打包正式包（标准基座不含插件，无法调用）。

前置准备

1. Google Cloud 配置

• 在 Google Cloud 项目中启用 Navigation SDK（需开通结算账号），并按需启用 Maps / Places 等服务。
• 申请 API Key，并建议做来源限制：
  • Android：绑定应用包名 + 签名证书 SHA-1；
  • iOS：绑定 Bundle ID。

2. 配置 API Key（重要：插件不内置 Key）

插件源码中不包含任何 API Key，Key 由宿主 App 工程提供（Navigation SDK 的计费与配额绑定在 Key 上，必须使用你自己的 Key）。

Android：在项目根目录创建 AndroidManifest.xml（HBuilderX 3.6+ 支持，云端打包时合并到应用清单）：

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="你的Android包名">
    <application>
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="你的 Android API Key" />
    </application>
</manifest>

注意：

• 名称必须是 com.google.android.geo.API_KEY（Google Navigation SDK 固定读取该 meta-data）；
• 根节点 package 属性不能为空，建议与云端打包时配置的 Android 包名一致；
• 修改清单文件后需要重新打自定义基座 / 重新云打包才会生效。

iOS：在项目根目录创建 Info.plist（HBuilderX 3.6.5+ 支持），插件会读取其中的 GoogleNavigationAPIKey：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>GoogleNavigationAPIKey</key>
    <string>你的 iOS API Key</string>
</dict>
</plist>

未配置 iOS Key 时调用会回调 onError(-5) 并提示在 Info.plist 中添加 GoogleNavigationAPIKey。

3. 权限

插件已声明所需权限，业务侧只需在首次使用前拿到定位权限（原生页内也会自行申请一次）：

• Android：INTERNET、ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION、 FOREGROUND_SERVICE、FOREGROUND_SERVICE_LOCATION、POST_NOTIFICATIONS（Android 13+）。
• iOS：NSLocationWhenInUseUsageDescription、NSLocationAlwaysAndWhenInUseUsageDescription、 UIBackgroundModes（location / audio）等已在插件 Info.plist 中声明。

4. 导航条款弹窗公司名（可选）

首次进入导航页会弹出 Google 导航服务条款，公司名默认自动取当前 App 的应用名称（Android 取应用 label，iOS 取 CFBundleDisplayName / CFBundleName），通常无需配置。

快速开始

// #ifdef APP-PLUS
import {
  openNavigation,
  stopNavigation,
  isNavigationSupported
} from '@/uni_modules/google-navigation'
// #endif

export default {
  methods: {
    startNavigation() {
      // #ifdef APP-PLUS
      if (!isNavigationSupported()) {
        uni.showToast({ title: '当前环境不支持应用内导航', icon: 'none' })
        return
      }
      const result = openNavigation({
        // 最终目的地（必填）
        destination: { latitude: 22.3193, longitude: 114.1694, title: '目的地' },
        // 途经点（可选，按数组顺序导航）
        waypoints: [
          { latitude: 22.3100, longitude: 114.1700, title: '途经点1' }
        ],
        audioGuidance: true,        // 语音播报，默认 true
        simulate: false,            // 调试：沿路线模拟行驶，默认 false
        simulateSpeedMultiplier: 5  // 调试：模拟速度倍率，默认 5
      }, (eventJson) => {
        // 事件统一为 JSON 字符串，需自行解析
        let e = eventJson
        if (typeof e === 'string') {
          try { e = JSON.parse(e) } catch (err) { e = { type: 'unknown' } }
        }
        switch (e.type) {
          case 'onOpened':
            console.log('导航页已打开')
            break
          case 'onRoutesReady':      // 路线已规划：预览阶段
            console.log('路线数=', e.routeCount, '距离=', e.distanceMeters,
              '用时=', e.remainingSeconds, '预计到达=', e.etaTimestamp)
            // e.polyline 为 Google 编码折线，可解码后用于业务侧地图展示
            break
          case 'onNavigationStarted':
            console.log('开始逐向导航')
            break
          case '':         // 剩余时间/距离变化（约 5 秒或 5 米一次）
          case 'onRouteChanged':     // 路线变化（含偏航重算完成）
            console.log('剩余', e.distanceMeters, '米 /', e.remainingSeconds, '秒')
            break
          case 'onRerouting':
            console.log('已偏航，正在重新规划')
            break
          case 'onLocation':         // 道路吸附后的实时位置
            console.log('位置', e.latitude, e.longitude, '朝向', e.bearing, '速度', e.speed)
            break
          case 'onArrival':
            // 到达途经点或最终目的地（到达不自动完成业务订单）
            console.log(e.isFinalDestination ? '已到达最终目的地' : '已到达途经点')
            break
          case 'onError':
            uni.showToast({ title: e.message || '导航出错', icon: 'none' })
            break
          case 'onClosed':
            console.log('导航页已关闭')
            break
        }
      })

      if (!result.success) {
        // 例如：标准基座未包含插件、参数非法
        uni.showToast({ title: result.message, icon: 'none' })
      }
      // #endif
    },

    // 业务侧主动结束导航（例如订单被取消）
    stopNavigation() {
      // #ifdef APP-PLUS
      stopNavigation()
      // #endif
    }
  }
}

要点：

• JS 侧必须自行处理降级：H5 / 小程序等非 App 平台调用会返回 success: false，建议用条件编译包裹。
• 打开导航页是同步返回（是否成功拉起原生页面），后续进度一律走事件回调。
• 事件参数是 JSON 字符串而不是对象（UTS 跨语言回调的稳定性考虑），先 JSON.parse 再使用。

API 说明

openNavigation(options, callback?)

打开原生导航页（同步返回是否成功拉起）。

返回值：{ success: Boolean, message: String }。

stopNavigation()

主动结束导航并关闭原生页面，返回 { success, message }。 用户在原生页内点「结束导航」或系统返回键也会关闭页面，并回调 onClosed。

isNavigationSupported()

当前平台是否支持应用内 Google 导航，返回 Boolean（仅 App-Android / App-iOS 为 true）。

事件列表（callback 收到的 JSON）

polyline 为 Google 标准编码折线字符串，可用常见 decodePolyline 算法解码为坐标数组。

错误码（onError.errorCode）

多语言（界面文案）

插件的界面文案（按钮、状态提示、错误信息）内置三种语言：

语言解析顺序：openNavigation 的 locale 参数 → 系统语言 → 简体中文。

openNavigation({
  destination: { latitude: 22.3193, longitude: 114.1694, title: '目的地' },
  locale: 'en'   // 不传时跟随系统语言，系统语言非中文/英文时默认简体中文
}, onEvent)

说明：

• 导航页内文案（原生实现）与 onError 文案都按上述顺序解析；
• UTS 层同步返回的提示（参数校验失败等）按 locale 解析，未传时为简体中文，建议显式传入 locale 保持两端一致；
• Google Navigation SDK 自带控件（SDK 渲染的导航提示等）的语言由系统语言决定，不受 locale 影响；
• 条款弹窗中的公司名不是界面文案，默认自动取当前 App 的应用名称，也可改为固定公司名（见「前置准备 - 导航条款弹窗公司名」）。

调试技巧

无车验证完整引导流程时，可打开模拟行驶：

openNavigation({
  destination: { latitude: 22.3193, longitude: 114.1694, title: '目的地' },
  simulate: true,
  simulateSpeedMultiplier: 8
}, onEvent)

常见问题

Q：调用后提示插件不可用 / 直接返回失败？ 使用自定义基座或云打包。标准基座不包含本插件，也不能临时加载原生代码。

Q：进入导航页后黑屏 / 提示初始化失败 / 报未授权（NOT_AUTHORIZED）？ 按顺序排查：是否已在项目根目录 AndroidManifest.xml 声明 com.google.android.geo.API_KEY（iOS 检查根目录 Info.plist 的 GoogleNavigationAPIKey）→ Key 的来源限制是否正确（Android 包名+签名、iOS Bundle ID）→ Google Cloud 是否已开通 Navigation SDK 与结算 → 定位权限是否授予。 修改清单/plist 后必须重新打自定义基座再运行。

Q：卡在条款弹窗？ 首次使用必须同意 Google 导航服务条款；未同意会回调 onError(-2) 并关闭页面。

Q：H5 / 小程序端怎么办？ 插件仅支持 App，非 App 平台返回 success: false，业务侧自行降级（如跳转外部地图或使用地图组件）。

Q：导航到终点后订单会自动完成吗？ 不会。onArrival 只上报事实，订单状态由业务层自行控制。

注意事项与限制

• Android 端已在真机（自定义基座）验证通过；iOS 端提供完整实现（Swift + GoogleNavigation 9.4.0），首次使用请按「前置准备」配置 Key 与权限后在 iOS 真机验收。
• Android 导航页会保持屏幕常亮（FLAG_KEEP_SCREEN_ON）。
• 页面为竖屏固定；导航中请勿在业务侧重复调用 openNavigation，避免多实例。
• 两个平台的进度事件触发频率与 polyline 范围存在细微差异（Android 取当前路线段，iOS 取全程路段），业务侧按需兼容。
• 使用 Google Navigation SDK 需遵守 Google 的服务条款与计费规则。

更新日志

• 3.3.0
  • 修复到达途经点后不再继续导航的问题：两端统一为「移除当前目的地 + 保持引导」续行到下一站
  • iOS 关闭 stopGuidanceAtArrival（默认 YES 会在途经点处中止引导），并在到达回调中 continueToNextDestination() + 恢复 isGuidanceActive
  • Android 在到达回调中对非最终点 continueToNextDestination() + startGuidance()
  • 续行后补发一次 onRouteChanged（含新路线 polyline 与剩余距离/时间）；iOS 目的地判定改为按已到达计数，不再依赖 60 米坐标近似
• 3.2.0
  • 界面文案默认改为简体中文，并支持多语言：locale 支持 zh-CN / zh-TW / en，不传时跟随系统语言、兜底简体中文
  • 新增 UTS 层共享文案表 utssdk/i18n.uts；原生导航页与同步返回提示统一走多语言表
  • 条款弹窗公司名改为默认自动取当前 App 的应用名称
• 3.1.0
  • API Key 改为由宿主工程配置：Android 从项目根目录 AndroidManifest.xml 读取，iOS 从项目根目录 Info.plist 读取，插件源码不再内置任何 Key（升级后需按「前置准备 - 配置 API Key」补配）
• 3.0.0
  • Android（Kotlin）+ iOS（Swift）双端原生实现
  • 路线预览/备选路线、逐向导航、多途经点
  • 事件体系：路线就绪、开始导航、进度、路线变化、偏航重算、位置、到达、错误、关闭
  • 语音播报开关、模拟行驶调试参数