Navigation SDK 目前仅面向部分客户提供。如需了解详情，请与销售人员联系。

Google Maps Platform 即将推出新的地图样式设置。此次地图样式更新包括新的默认调色板，并改进了地图体验和易用性。所有地图样式都将在 2025 年 3 月自动更新。如需详细了解适用范围以及如何提前选择启用，请参阅 Google Maps Platform 的新地图样式。

此页面由 Cloud Translation API 翻译。

启用精细数据 Feed

精细导航数据 Feed 可向未设计为提供基于地图的导航指引的设备提供仅限导航的信息。它会为即将执行的动作提供您提供的元素：

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

您可以使用精细导航 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 中，以便在 build 中添加 JAR。

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

使用导航库

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

创建用于接收导航更新的服务。
注册服务。
了解导航状态。

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

Navigation SDK 会绑定到您的精细导航服务，并通过 Android 信使向其发送导航更新。您可以为这些更新创建新的导航服务，也可以使用现有服务。

使用服务接收导航更新的好处在于，该服务可以位于单独的后台进程中。

以下示例中的服务会接收导航信息，并使用 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 会根据国家/地区的驾驶侧来确定这些标签。例如，在车辆靠左行驶的国家/地区，驾驶员在环岛路或 U 形转弯时会顺时针行驶，而在车辆靠右行驶的国家/地区，驾驶员则会逆时针行驶。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`

使用生成的图标

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);

启用图标生成后，导航图 StepInfo 对象会使用图标填充 maneuverBitmap 和 lanesBitmap 字段。

后续步骤

对于 Android Auto 应用：
- 绘制地图并启用导航。