Skip to content

真实导航与模拟导航

功能介绍

导航启动统一通过 NavigationService.startNavigation(...) 完成，通过参数区分两种模式：

  • 真实导航：使用实时定位推进导航，适用于实车场景。
  • 模拟导航：沿路线按给定速度推进导航，适用于联调、演示、回归测试。

停止导航统一通过 NavigationService.stopNavigation() 完成。

核心接口

接口 说明
startNavigation(route, isSimulation, simulateSpeedMetersPerSecond) 启动导航会话；返回 NavigationSession?（成功非空）
NavigationSession.setDemonstrateSpeed(speed) 模拟导航运行中动态调整速度（m/s）
stopNavigation() 停止当前导航会话并销毁会话对象；返回执行结果
eventHub.addNavigationEventListener(listener) 注册导航事件监听（导航状态、进度等）；详细字段见后续文档

参数说明

startNavigation

参数 说明
route 导航路线。可通过 NavigationService.createNavigableRouteTask(...) 或 NavigationService.createNavigableEvTripPlanTask(...) 获取
isSimulation false：真实导航；true：模拟导航
simulateSpeedMetersPerSecond 仅 isSimulation == true 时生效，单位 m/s，有效范围 [0.0, 100.0]

返回值：

  • 成功：返回 NavigationSession
  • 失败：返回 null（例如已有活动会话未先停止）

异常：

  • 可能抛出 NavigationException（如 NavigationService 已 dispose，或路线/服务状态不合法）

stopNavigation

返回值语义：

  • true：停止成功
  • false：当前无活动会话，或底层停止失败

启停流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
算路成功（拿到 Route）
   ↓
eventHub.addNavigationEventListener(listener)   ← 建议在 startNavigation 前注册
   ↓
startNavigation(route, isSimulation, speed)
   ↓
返回 NavigationSession（非空）并进入导航中
   ↓
onNavigationEventUpdated 等回调（主状态见「2 导航状态信息」，其它事件见 11–14 等专题）
   ↓
stopNavigation()
   ↓
removeNavigationEventListener(listener)

示例代码

导航状态、剩余距离/时间、偏航等通过 NavigationEventListener 回调；各字段含义见 导航状态信息。

1
2
3
4
5
6
7
8
val navigationEventListener = object : NavigationEventListener {
    override fun onNavigationEventUpdated(navEvent: NavigationEvent) {
        // 导航状态更新（约 1 Hz）
    }
    // 其它回调见 概述「能力地图」（导航指令列表、到达/离开途经点、限时通行等）
}

navigationService.eventHub.addNavigationEventListener(navigationEventListener)

1) 真实导航

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
val route: Route = selectedRoute

val session = navigationService.startNavigation(
    route = route,
    isSimulation = false,
    simulateSpeedMetersPerSecond = 0.0
)

if (session == null) {
    // 启动失败：常见原因是已有活动会话未停止
    return
}

2) 模拟导航

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
val route: Route = selectedRoute

val session = navigationService.startNavigation(
    route = route,
    isSimulation = true,
    simulateSpeedMetersPerSecond = 22.22 // 约 80 km/h
)

if (session == null) {
    // 启动失败处理
    return
}

3) 模拟导航运行中调速

模拟导航会话启动后，可通过 NavigationSession 动态调速：

1
session?.setDemonstrateSpeed(30.0) // 30 m/s，约 108 km/h

说明：

  • 接口签名：setDemonstrateSpeed(speed: Double)
  • 有效范围：[0.0, 100.0]（m/s）
  • 建议仅在 isSimulation = true 的会话中使用

4) 停止导航

1
2
3
4
5
6
val stopped = navigationService.stopNavigation()
if (!stopped) {
    // 当前可能没有活动会话，或停止失败
}

navigationService.eventHub.removeNavigationEventListener(navigationEventListener)

注意事项

  • 进入导航页时注册 NavigationEventListener，退出时调用 removeNavigationEventListener，避免泄漏或重复回调。
  • 启动新会话前，先确保旧会话已停止；否则 startNavigation 可能返回 null。
  • simulateSpeedMetersPerSecond 仅在模拟导航模式生效。
  • 模拟导航仅建议用于开发/测试；量产建议使用真实定位。
  • stopNavigation() 后会话对象即失效，不应继续使用旧 NavigationSession。