精细数据 Feed 可为并非专为基于地图的导航指导而设计的设备提供仅限导航的信息。它会使用您提供的元素提供即将进行的动作:
- 图标(左、右、调头)
- 在环岛中转弯数字
- 道路名称
- 距离下一个导航步骤或最终目的地的估算距离和时间
您可以使用精细信息流来打造不适合完整 Navigation SDK 界面的体验,例如适用于 Android Auto 或无法提供完整 Android 堆栈的小屏幕显示屏。例如,您可以对双轮机动车乘客使用这种方法,在这种情况下,您可以投影仅限导航的指导,帮助他们更快、更自信地到达目的地,同时最大限度地减少干扰。
如需使用该 SDK,您需要创建一个服务,并向 Navigation SDK for Android 注册该服务,以便它能够实时接收新的导航信息(在导航期间大约每秒一次)。
本文档介绍了如何创建和注册导航服务,该服务从 SDK 接收导航信息并向接收设备提供导航状态。
概览
本部分介绍了如何将 TurnByTurn 库添加到您的项目,并总结了构建精细导航功能的概要流程。
使用 Maven 将 TurnByTurn 库添加到您的项目中(推荐)
如需使用独立版本的 TurnByTurn 库,请按以下步骤操作:
按照行程和订单文档中的驱动程序 SDK 使用入门中的说明,设置您的环境以访问主机 Maven 制品库。
将以下依赖项添加到您的 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 库添加到您的项目中
DonByTurn 库以 JAR 文件的形式位于此 SDK 文件夹中。如果您无权访问,请与您的代表联系。
- 下载并解压缩
google_turnbyturn_*.jar
。 - 将下载的 JAR 文件复制到项目的
app/libs
目录中。 将以下代码添加到
build.gradle
中,以将 JAR 文件包含在您的 build 中。dependencies { ... api fileTree(include: ['*.jar'], dir: 'libs') }
使用 TurnByTurn 库
以下是启用精细导航功能的大致步骤。以下部分详细介绍了各个步骤。
创建服务以接收导航更新 {#service}
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
消息。
注册服务以接收导航更新 {#register}
以下代码段会注册导航服务。
boolean isNavInfoReceivingServiceRegistered = navigator.registerServiceForNavUpdates( getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);
启动和停止服务
只要 Navigation SDK 绑定到导航服务,导航服务就会处于活跃状态。您可以手动调用 startService()
和 stopService()
来控制导航服务生命周期,但当您向 Navigation SDK 注册服务时,服务会自动启动,并且仅在您取消注册时停止。根据您设置应用的方式,您可能需要考虑启动前台服务,如 Android 文档服务概览中所述。
取消注册服务
如需停止接收导航更新,请从 Navigation SDK 中取消注册该服务。
navigator.unregisterServiceForNavUpdates();
了解导航状态 {#states}
使用 NavInfo.getNavState()
获取当前的导航状态,可以是以下状态之一:
进入路线 -
ENROUTE
状态表示引导式导航当前处于有效状态,且用户位于提供的路线上。提供了有关当前即将执行的操纵步骤的信息。正在重选 -
REROUTING
表示导航正在进行中,但导航器正在查找新路线。由于还没有新路线,即将到来的操作步骤不可用。在示例应用中,导航信息显示屏中显示“Rerouting...”消息。找到路由后,系统会发送一条状态为ENROUTE
的NavInfo
消息。已停止 -
STOPPED
表示导航已结束。例如,当用户退出应用中的导航时,导航会停止。在示例应用中,STOPPED
状态会清除导航信息显示,以防止显示延迟步骤说明。
填充 Feed 显示视图
现在,您已设置精细导航服务,本部分将介绍可用于填充精细导航 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 应用: