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

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

此页面由 Cloud Translation API 翻译。

启用精细数据 Feed

精细导航数据 Feed 可为未专为基于地图的导航指导而设计。它能提供即将开始的机操作提供的元素：

图标（向左、向右、调头）
在环岛中转弯数字
道路名称
预计距离和时间目标账号

您可以使用精细导航来打造 Navigation SDK 界面不适合，例如 Android Auto 或屏幕上会显示不可用的 Android 堆栈。例如，您可能会将该模型用于双轮机动车驾驶员，仅含导航的指导，帮助他们更快、更好地到达目的地尽量减少干扰。

要使用 SDK，您需要创建服务并向 Navigation SDK for Android，使其可以接收新的导航信息实时（导航期间大约每秒一次）。

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

概览

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

使用 Maven 将 TurnByTurn 库添加到您的项目中（推荐）

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

设置您的环境以访问托管 Maven 制品库： <ph type="x-smartling-placeholder"></ph>

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

<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 碰头，了解所有最新动态。您可以为这些更新创建新的导航服务，或使用现有的服务。

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

以下示例中的服务会接收导航信息并使用 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()));
}

邮件内容代码

NavInfo邮件可通过 Message.what 是 Message 类的一个字段，该字段的值设置为 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 表示导航正在进行中，导航器正在寻找新路线。即将开始的动作步骤可用，因为还没有新路线。在示例应用中，“正在重新路由...”消息出现在显示导航信息。找到路由后，系统将发送 NavInfo 消息且状态为 ENROUTE 发送。
已停止 - STOPPED 表示导航已结束。例如，导航当用户退出应用中的导航时停止。在示例应用中， STOPPED 状态会清除导航信息显示，以免延迟步骤说明。

填充 Feed 显示内容

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

导航卡片信息字段

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

当用户进入引导式导航时，顶部会显示一张导航卡片，包含从 Navigation SDK。相关图片显示了这些重要的导航元素

此表显示了导航信息的各个字段以及各个字段的位置。

每个导航步骤对应的字段	整个行程的字段
发现位置：`StepInfo`	发现位置：`NavInfo`
完整道路名称	剩余时间
“操纵”图标	距离目的地的距离
与下一路段的距离
车道导航字段

车道导航

Navigation SDK 表示导航中的车道将卡设为车道和 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 的边界框为目标平台的汽车应用库。请参阅 setsLaneImage 和 CarIcon 详情请参阅 Android 参考文档。

图标生成示例

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 应用：
- 绘制地图并启用导航。