精细导航数据 Feed 为并非专为基于地图的导航设计的设备提供导航专用信息。它使用您提供的元素为即将发生的操作提供:
- 图标(向左、向右、调头)
- 在环岛中转弯数字
- 道路名称
- 预计到达下一导航路段或最终目的地的距离和时间
您可以使用精细导航信息流来打造不适合使用完整 Navigation SDK 界面的体验,例如针对 Android Auto 或无法使用完整 Android 堆栈的小屏幕显示屏。例如,您可以将此测试用于双轮机动车驾驶员,这样,您就可以投射纯导航指导,帮助他们更快速、更自信地到达目的地,最大限度地减少干扰。
如需使用该 SDK,您需要创建一个服务并向 Navigation SDK for Android 注册该服务,以便该服务可以实时(在导航期间大约每秒一次)接收新的导航信息。
本文档介绍了如何创建和注册从 SDK 接收导航信息并向接收设备提供导航状态的导航服务。
概览
本部分介绍如何将 TurnByTurn 库添加到项目中,并总结了构建精细导航功能的大致流程。
使用 Maven 将 TurnByTurn 库添加到您的项目中(推荐)
要使用独立版本的 TurnByTurn 库,请按以下步骤操作:
- 设置您的环境以访问托管 Maven 制品库:
Maven
请将以下内容添加到
pom.xml
文件:<project> ... <repositories> <repository> <id>google-maven-repository</id> <url>https://maven.google.com</url> </repository> </repositories> ... </project>
Gradle
请将以下内容添加到
build.gradle
文件:repositories { ... google() }
将以下依赖项添加到您的 Maven 或 Gradle 配置:
-
Maven
<dependencies> ... <dependency> <groupId>com.google.android.maps</groupId> <artifactId>google_turnbyturn</artifactId> <version>1.0.0</version> </dependency> </dependencies>
Gradle
dependencies { ... implementation 'com.google.android.maps:google_turnbyturn:1.0.0' }
使用下载的 JAR 文件(备用)将 TurnByTurn 库添加到您的项目中
TurnByTurn 库以 JAR 文件的形式提供,位于此 SDK 文件夹中。如果您没有访问权限,请与您的代表联系。
- 下载并解压缩
google_turnbyturn_*.jar
。 - 将下载的 JAR 文件复制到项目的
app/libs
目录中。 将以下内容添加到
build.gradle
,以将 JAR 包含在 build 中。dependencies { ... api fileTree(include: ['*.jar'], dir: 'libs') }
使用 TurnByTurn 库
以下是启用精细导航功能的大致步骤。后续部分提供了有关每个步骤的详细信息。
创建用于接收导航更新的服务
Navigation SDK 会绑定到您的 TurnByTurn 服务,并通过 Android Messenger 向其发送导航更新。您可以为这些更新创建新的导航服务,也可以使用现有服务。
使用服务接收导航更新的好处是服务可以位于单独的后台进程中。
以下示例中的服务会接收导航信息,并使用 TurnByTurnManager
将数据转换为包含导航详情的 NavInfo
对象。
/** * Receives turn-by-turn navigation information forwarded from NavSDK. */ public class NavInfoReceivingService extends Service { /** The messenger used by the service to receive nav step updates. */ private Messenger incomingMessenger; private TurnByTurnManager turnByTurnManager; private final class IncomingNavStepHandler extends Handler { public IncomingNavStepHandler(Looper looper) { super(looper); } @Override public void handleMessage(Message msg) { // Identify the message through the msg.what field. if (TurnByTurnManager.MSG_NAV_INFO == msg.what) { // Extract the NavInfo object using the TurnByTurnManager. NavInfo navInfo = turnByTurnManager .readNavInfoFromBundle(msg.getData())); // Do something with the NavInfo } } } @Nullable @Override public IBinder onBind(Intent intent) { return incomingMessenger.getBinder(); } @Override public void onCreate() { turnByTurnManager = TurnByTurnManager.createInstance(); HandlerThread thread = new HandlerThread("NavInfoReceivingService", Process.THREAD_PRIORITY_DEFAULT); thread.start(); incomingMessenger = new Messenger( new IncomingNavStepHandler(thread.getLooper())); }
邮件内容代码
您可以通过 Message
类的 Message.what 字段(设置为 TurnByTurnManager.MSG_NAV_INFO
的值)来识别 NavInfo
消息。
注册服务以获取导航更新
以下代码段会注册导航服务。
boolean isNavInfoReceivingServiceRegistered = navigator.registerServiceForNavUpdates( getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);
启动和停止服务
只要 Navigation SDK 绑定到该服务,导航服务就处于活跃状态。您可以手动调用 startService()
和 stopService()
来控制导航服务生命周期,但当您向 Navigation SDK 注册服务时,服务会自动启动,只有在您取消注册后才会停止。根据应用设置的方式,您可能需要考虑启动前台服务,如 Android 文档服务概览中所述。
取消注册服务
如需停止接收导航更新,请从 Navigation SDK 中取消注册该服务。
navigator.unregisterServiceForNavUpdates();
了解导航状态
使用 NavInfo.getNavState()
获取导航的当前状态,其中包括以下状态之一:
途中 -
ENROUTE
状态表示引导式导航当前处于活动状态,并且用户位于提供的路线上。提供有关当前即将进行的操作步骤的信息。正在重选路线 -
REROUTING
表示导航正在进行中,但导航器正在查找新路线。即将到来的操作步骤不可用,因为还没有新路线。在示例应用中,导航信息显示区中会显示“正在重新路由...”消息。找到路由后,系统会发送状态为ENROUTE
的NavInfo
消息。已停止 -
STOPPED
表示导航已结束。例如,当用户退出应用中的导航时,导航会停止。在示例应用中,STOPPED
状态会清除导航信息显示,以免显示延迟的步骤说明。
填充 Feed 显示内容
现在,您已经设置了精细导航服务,本部分将介绍可用于为精细导航信息流填充导航卡片的视觉和文本元素。
导航卡片信息字段
当用户进入引导式导航时,顶部会显示一张导航卡片,其中包含通过 Navigation SDK 填充的导航数据。相关图片展示了这些基本导航元素的示例。
此表显示了导航信息的各个字段以及各个字段的位置。
每个导航步骤对应的字段 | 整个行程的字段 |
---|---|
发现位置:StepInfo |
发现位置:NavInfo |
完整道路名称 | 剩余时间 |
“操纵”图标 | 距离目的地的距离 |
与下一路段的距离 | |
车道导航字段 |
车道导航
Navigation SDK 将导航转弯卡中的车道表示为 Lane 和 LaneDirection 数据对象。Lane
对象表示导航期间的特定车道,该对象包含一个 LaneDirection
对象列表,用于描述可通过这条车道进行的所有转弯。
用户在车道中应采用的建议方向由 isRecommended 字段标记。
车道导航示例
以下代码段展示了上方所示车道的数据表示形式。
// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
{/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]
// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]
创建操作图标
Maneuver
枚举定义了导航时可能发生的每种操作,您可以通过 StepInfo.getManeuver()
方法获取指定步骤的操作。
您必须创建操作图标,并将其与相关的操作配对。
对于某些操作,您可以设置与图标的一对一映射,例如 DESTINATION_LEFT
和 DESTINATION_RIGHT
。不过,由于一些操作是类似的,因此您可能需要将多项操作映射到单个图标。例如,TURN_LEFT
和 ON_RAMP_LEFT
都可以映射到左转弯图标。
一些操作包含额外的 clockwise
或 counterclockwise
标签,SDK 根据国家/地区的驾驶侧来确定该标签。例如,在道路左侧驾驶的国家/地区,驾驶员会按顺时针方向环岛或调头,而道路右侧的国家/地区则顺时针方向。Navigation SDK 会检测操控操作发生在左侧还是右侧流量中,并输出适当的操作。因此,顺时针和逆时针操纵的操纵图标可能有所不同。
展开即可查看不同操作的示例图标
示例图标 | 转弯技巧 |
---|---|
DEPART UNKNOWN |
|
STRAIGHT ON_RAMP_UNSPECIFIED OFF_RAMP_UNSPECIFIED NAME_CHANGE
|
|
TURN_RIGHT ON_RAMP_RIGHT
|
|
TURN_LEFT ON_RAMP_LEFT
|
|
TURN_SLIGHT_RIGHT ON_RAMP_SLIGHT_RIGHT OFF_RAMP_SLIGHT_RIGHT
|
|
TURN_SLIGHT_LEFT ON_RAMP_SLIGHT_LEFT OFF_RAMP_SLIGHT_LEFT
|
|
TURN_SHARP_RIGHT ON_RAMP_SHARP_RIGHT OFF_RAMP_SHARP_RIGHT
|
|
TURN_SHARP_LEFT ON_RAMP_SHARP_LEFT OFF_RAMP_SHARP_LEFT
|
|
TURN_U_TURN_COUNTERCLOCKWISE ON_RAMP_U_TURN_COUNTERCLOCKWISE OFF_RAMP_U_TURN_COUNTERCLOCKWISE
|
|
TURN_U_TURN_CLOCKWISE ON_RAMP_U_TURN_CLOCKWISE OFF_RAMP_U_TURN_CLOCKWISE
|
|
ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_SHARP_RIGHT_CLOCKWISE
|
|
ROUNDABOUT_RIGHT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_RIGHT_CLOCKWISE
|
|
ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE
|
|
ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_STRAIGHT_CLOCKWISE
|
|
ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE
|
|
ROUNDABOUT_LEFT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_LEFT_CLOCKWISE
|
|
ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_SHARP_LEFT_CLOCKWISE
|
|
ROUNDABOUT_U_TURN_COUNTERCLOCKWISE
|
|
ROUNDABOUT_U_TURN_CLOCKWISE
|
|
ROUNDABOUT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_CLOCKWISE
|
|
ROUNDABOUT_EXIT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_EXIT_CLOCKWISE
|
|
MERGE_RIGHT OFF_RAMP_RIGHT
|
|
MERGE_LEFT OFF_RAMP_LEFT
|
|
FORK_RIGHT TURN_KEEP_RIGHT ON_RAMP_KEEP_RIGHT OFF_RAMP_KEEP_RIGHT
|
|
FORK_LEFT TURN_KEEP_LEFT ON_RAMP_KEEP_LEFT OFF_RAMP_KEEP_LEFT
|
|
MERGE_UNSPECIFIED
|
|
DESTINATION
|
|
DESTINATION_RIGHT
|
|
DESTINATION_LEFT
|
|
FERRY_BOAT
|
|
FERRY_TRAIN
|
使用生成的图标
为方便 Android Auto 用例,Navigation SDK 支持生成机动车道和车道导航图标。这些图标符合 Android Auto 汽车应用库的图片大小指南,该库建议以 500 x 74 dp 的边界框为目标平台。如需了解详情,请参阅 Android 参考文档中的 setsLaneImage 和 CarIcon。
图标生成示例
NavigationUpdatesOptions options =
NavigationUpdatesOptions.builder()
.setNumNextStepsToPreview(numNextStepsToPreview)
.setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
.setDisplayMetrics(getResources().getDisplayMetrics())
.build();
boolean isRegistered =
navigator.registerServiceForNavUpdates(
getPackageName(),
NavInfoReceivingService.class.getName(),
options);
启用图标生成功能后,TurnbyTurn StepInfo
对象会使用图标填充 maneuverBitmap 和 lanesBitmap 字段。
后续步骤
- 对于 Android Auto 应用: