启用精细数据 Feed

精细导航数据 Feed 可为并非专为基于地图的导航设计的设备提供导航专用信息。它会为即将执行的动作提供您提供的元素：

  • 图标（向左、向右、掉头）
  • 环岛的转弯编号
  • 道路名称
  • 到下一个导航步骤或最终目的地的预计距离和时间

您可以使用精细导航信息流来打造不适合使用完整 Navigation SDK 界面的体验，例如针对 Android Auto 或无法使用完整 Android 堆栈的小屏幕显示屏。例如，您可以将此测试用于双轮机动车驾驶员，这样，您就可以投射纯导航指导，帮助他们更快、更自信地到达目的地，最大限度地减少干扰。

如需使用该 SDK，您需要创建一个服务并将其注册到 Navigation SDK for Android，以便它能够实时接收新的导航信息（在导航期间大约每秒一次）。

本文档介绍了如何创建和注册从 SDK 接收导航信息并向接收设备提供导航状态的导航服务。

概览

本部分介绍了如何将 TurnByTurn 库添加到您的项目中，并总结了构建精细导航功能的概要流程。

要使用独立版本的 TurnByTurn 库，请按以下步骤操作：

  1. 设置您的环境以访问主机 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()
}
  2. 将以下依赖项添加到您的 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 文件夹中。如果您没有访问权限，请与您的代表联系。

  1. 下载并解压缩 google_turnbyturn_*.jar。
  2. 将下载的 JAR 文件复制到项目的 app/libs 目录中。

  3. 将以下代码添加到 build.gradle 中，以便在 build 中添加 JAR。

    dependencies {
    ...
    api fileTree(include: ['*.jar'], dir: 'libs')
}

使用 TurnByTurn 库

以下是启用精细导航功能的简要步骤。后续部分详细介绍了每个步骤。

  1. 创建用于接收导航更新的服务。

  2. 注册服务。

  3. 了解导航状态。

  4. 查看显示基本元素的导航栏示例。

创建用于接收导航更新的服务

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 字段可用于识别 NavInfo 消息，该字段设置为 TurnByTurnManager.MSG_NAV_INFO 的值。

注册服务以获取导航更新

以下代码段会注册导航服务。

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 显示屏

现在，您已经设置了精细导航服务，本部分将介绍可用于为精细导航 Feed 填充导航卡片的视觉和文本元素。

一个手机屏幕，显示 100 英尺处即将到来的左转弯，进入 W Ahwanee Ave。在屏幕底部，到达目的地的剩余时间是 46 分钟，剩余距离是 39 英里。

当用户进入引导式导航时，顶部会显示一张导航卡片，其中包含通过 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 会检测操作是在左侧还是右侧流量中发生的，并输出相应的操作。因此，顺时针和逆时针转弯的标志图标可能会有所不同。

展开即可查看不同操作的示例图标

示例图标 TurnByTurn 操作
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

使用生成的图标

Navigation SDK 提供的生成图标的一小部分。

为了方便使用 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 字段。

后续步骤