适用于 Android Automotive intent 的 Google 地图

免责声明

此产品/功能将发生变化，并且不受任何服务等级协议 (SLA) 或弃用政策的约束。实现方式在未来版本中可能会发生变化。

关于本文件随附的示例软件、数据文件和/或源代码：本产品“按原样”提供，不附带任何形式的保证，Google 明确声明放弃所有明示、默示、法定或其他形式的保证，包括但不限于适销性保证、特定用途适用性保证以及不侵犯与本产品相关的任何权利的保证。

您可以通过 Android Automotive intent 在 Google 地图中启动导航。

如需了解详情，请参阅 适用于 Android 的 Google 地图 intent。

如需详细了解如何将应用部署到搭载 Android Auto 或 Android Automotive OS 的车辆上，请参阅 Android for Cars。

概览

本页介绍了可与 Android Automotive 版 Google 地图搭配使用的 intent。如需查看详细的 Android 开发者文档，请参阅：

intent 请求

如需通过 intent 启动 Android Automotive 版 Google 地图，您必须先创建一个 Intent 对象，并指定其操作、URI 和软件包。

  • 操作。所有 Google 地图 intent 都称作“查看”操作 ACTION_VIEW。

  • URI。Google 地图 intent 使用的 URI 编码字符串指定所需操作，以及一些用于执行操作的数据。

  • 软件包。调用 setPackage("com.google.android.apps.maps") 可确保 Android 版 Google 地图应用处理 intent。如果未设置软件包，系统会确定哪些应用可以处理 intent。如果有多个应用可用，系统可能会询问您想要使用哪个应用。

创建 intent 后，您可以通过多种方式请求系统启动相关应用。一种常用方法是将 intent 传递给 startActivity() 方法。系统将启动必要的应用（在本例中为 Google 地图），并启动相应的 activity。

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

如果系统无法找到可响应 intent 的应用，您的应用可能会崩溃。因此，请先确认接收应用已安装，然后再将其中一个 intent 提供给用户。

如需确认存在可接收 intent 的应用，请对 Intent 对象调用 resolveActivity()。如果结果为非空，则至少有一个应用能够处理该 intent，并且可以安全调用 startActivity()。如果结果为 null，则您不应使用该 intent。如有可能，请停用调用该 intent 的功能。

if (mapIntent.resolveActivity(getPackageManager()) != null) {
...
}

例如，如需启动前往悉尼塔朗加动物园的转弯提示导航，您可以使用以下代码：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

URI 编码查询字符串

传递给 Google 地图 intent 的所有字符串都必须是 URI 编码字符串。例如，字符串“1st & Pike, Seattle”应编码为 1st%20%26%20Pike%2C%20Seattle。字符串中的空格可使用 %20 编码或替换为加号 (+)。

您可以使用 android.net.Uri parse() 方法为字符串编码。例如：

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

启动精细导航

此 intent 用于启动 Google 地图导航，获得前往指定一个或多个地址或坐标的转弯提示路线。一律以用户当前位置为起点提供路线。

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude
google.navigation:place=placename

参数

如需启动导航，请将 place 或 q 与 waypoints 搭配使用（可选）。如需选择将某个航点标记为充电站，请参阅将电动车辆行程计划发送到 Google 地图。

  • q 用于设置导航搜索的端点。它可以是纬度/经度或查询格式的地址。如果它是返回多个结果的查询字符串，系统会选择第一个结果。

  • place 会将端点设置为家或工作地点。指定“home”可导航到用户的家，“work”可导航到用户的工作场所。

  • avoid 用于设置路线应尝试避开的特征。avoid 是可选项，可设置为下列一个或多个值：

    • t（用于收费站）
    • h 适用于高速公路
    • f（适用于渡轮）

  • waypoints 用于指定一个或多个中途地点，以便将路线引导至由 q 指定的最终目的地。您可以使用竖线字符 (|) 分隔地点来指定多个路径点，例如 Berlin,Germany|Paris,France。您可以根据需要使用任意数量的航点。这些航点将按照网址中列出的顺序添加到路线中。每个路径点可以是地址，也可以是逗号分隔的纬度/经度坐标；您可以在同一 intent 中包含地址和纬度/经度坐标。字符串应为网址转义字符串，因此“Berlin,Germany|Paris,France”这样的路径点应转换为 Berlin%2CGermany%7CParis%2CFrance。

示例

此 intent 将请求前往澳大利亚悉尼塔朗加动物园的转弯提示导航：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

如果您不想支付通行费或乘坐渡船，可以请求尽量避开以下情况的路线：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

或者，如果您想导航到住宅，请使用以下命令：

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

如需依次启动前往以下三个地址的导航，请将塔龙加动物园作为最终目的地 q，并将 Google 悉尼和悉尼歌剧院作为路点：

  1. Google 悉尼办事处

  2. 悉尼歌剧院

  3. 澳大利亚悉尼塔朗加动物园

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

与 q 类似，您可以使用以英文逗号分隔的经纬度（而非地址）来表示任何航点。例如，如需启动相同的导航，同时传递悉尼歌剧院的纬度经度（而非地址），请执行以下操作：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

将电动汽车行程计划发送到 Google 地图

使用此多目的地导航 intent 将某些目的地指定为电动汽车 (EV) 充电点。此 intent 扩展了多航点 intent，可在电动车行程规划应用和 Google 地图之间同步充电站信息，帮助驾驶员保持充足的电动车电池电量，以便顺利抵达目的地。

对于充电站，行程 intent：

  • 必须包含名称和经纬度
  • 可选择包含功率输出，以用于计算充电时间

Google 会使用充电站名称和纬度-经度来查找匹配的充电站地点，以显示丰富的数据，例如连接器类型、总数、速度和实时空闲情况、支持的付款方式以及托管地图注点 (POI)。例如，导航最后一段的室外停车场驾车路线、营业时间、评分。为确保充电站与 Google 数据完全匹配，请使用 <brand name>，例如 ChargePoint。

参数

终点站

如需将充电站设置为最终目的地，请使用以下命令：

  • q：必须包含充电站的纬度-经度值。
  • q_type：1 指定最终目的地是充电站。
  • q_name：最终目的地的名称。如果 q_type 为 1，则必须提供此值。
  • q_power_output_kw：充电站功率输出（以千瓦为单位）的双精度数。可选。

航点

对于航点，所有参数都是并行的，值以 |- 分隔，且与航点（不包括最终目的地）的顺序相同。如果并行数组中的元素数量不匹配，则会被视为格式错误的 intent。

如需添加一个或多个充电站航点，请使用以下参数（所有这些参数都是可选的）。如果某个目的地被标记为充电站，则该目的地必须具有航点名称。

  • waypoints：精细导航 intent 中所述的路点列表。对于充电站航点，必须是经纬度值。

  • waypoint_types：每个航点的类型（以数字指定）。 0 是任何经停点（默认值），1 是充电站。

  • waypoint_names：航点名称。对于充电站，此字段是必填字段。

  • waypoint_power_outputs_kw：充电站功率（以千瓦为单位）的双精度数字。对于充电站，您可以选择指定航点功率输出值，以便在找不到匹配的充电站时用作回退。空槽表示未提供任何值。

用户体验 (UX) 行为

对于包含多个目的地的行程 intent，系统会显示路线概览屏幕，但导航不会自动启动。

如果 intent 格式正确，Google 地图将显示相应行程的路线概览屏幕。路线概览屏幕将显示 intent 中的所有路点和最终目的地，并提供适用的充电建议。

对于标记为充电站的任何路点或最终目的地，Google 地图会在 Google 数据库中搜索匹配的地点。

如果找到匹配项，Google 地图会使用 Google 数据在界面 (UI) 中显示相应充电站，并为该充电站提供充电建议。如果未找到匹配项，系统会使用 intent 中为充电站提供的数据（经纬度、名称和功率输出）在界面中显示此充电站，并提供此充电站的充电建议。

示例

通过多个充电站导航到最终目的地

以下 intent 会通过两个充电站（ChargePoint 和 Evie）导航到最终目的地 Port Macquarie NSW。

目标平台（按顺序）：

  1. ChargePoint 充电站（位置：-32.9599188,151.6240806，功率输出：6.6kw）

  2. Evie 充电站（位置：-31.9432539,152.4699808，功率输出： 350kw）

  3. 新南威尔士州 Port Macquarie

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

未知功率输出

如果功率输出值未知，请将 waypoint_power_outputs_kw 的相关槽留空。或者，如果所有槽均为空，则无需指定 waypoint_power_outputs_kw 参数。

目标平台（按顺序）：

  1. ChargePoint 充电站（位置：-32.9599188,151.6240806，功率输出：未知）

  2. 新南威尔士州 Port Macquarie

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

将最终目的地标记为充电站

如需将最终目的地标记为充电站，请指定 q_type、q_name 和 q_power_output_kw 参数。

目标平台（按顺序）：

  1. 澳大利亚悉尼塔朗加动物园

  2. ChargePoint 充电站（位置：-32.9599188,151.6240806，功率输出：未知）

  3. Evie 充电站（位置：-31.9432539,152.4699808，功率输出：350kw）

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

操作 intent

以下包含接口的 Action intent 可供使用：

操作 说明
geo.action:?act=mute 关闭所有导航语音导航。
geo.action:?act=unmute 取消静音，启用导航语音导航。
geo.action:?act=show_traffic 在地图上显示交通线条。
geo.action:?act=hide_traffic 隐藏地图上的路况线。
geo.action:?act=show_satellite 在地图上显示卫星图像。
geo.action:?act=hide_satellite 在地图上隐藏卫星图像。
geo.action:?act=query_next_turn Google 地图会播报下一个转弯（仅在导航时有效）。
geo.action:?act=distance_to_next_turn Google 地图会播报到下个转弯处的距离（仅在导航时有效）。
geo.action:?act=time_to_next_turn Google 地图会播报下一个转弯的时间（仅在导航时有效）。
geo.action:?act=distance_to_destination Google 地图会读出与目的地之间的距离（仅在导航时有效）。
geo.action:?act=go_back Google 地图会返回界面中的上一屏幕。
geo.action:?act=query_current_road Google 地图会读出当前道路。
geo.action:?act=query_destination Google 地图会播报目的地。
geo.action:?act=apply_electric_vehicle_connector_filter 对电动车辆充电站搜索结果应用连接器类型过滤器。
geo.action:?act=remove_electric_vehicle_connector_filter 移除了电动车辆充电站搜索结果的连接器类型过滤条件。
geo.action:?act=apply_electric_vehicle_payment_filter 对电动车辆充电站搜索结果应用付款过滤条件。
geo.action:?act=remove_electric_vehicle_payment_filter 移除了电动车辆充电站搜索结果的付款过滤条件。
geo.action:?act=apply_electric_vehicle_fast_charging_filter 对电动车辆充电站搜索结果应用快速充电过滤器。
geo.action:?act=remove_electric_vehicle_fast_charging_filter 移除了电动车辆充电站搜索结果中的快速充电过滤条件。
geo.action:?act=avoid_tolls 如果用户正在导航，则指示 Google 地图避开收费路线。 如果当前路线有收费路段，这可能会导致重新规划路线。
geo.action:?act=allow_tolls 如果用户正在导航，则指示 Google 地图允许显示收费路线。 如果允许使用收费道路可获得更好的路线，系统可能会重新规划路线。
geo.action:?act=avoid_ferries 如果用户正在导航，则指示 Google 地图避开有渡轮的路线。如果当前有效路线包含渡轮，这可能会导致重新规划路线。
geo.action:?act=allow_ferries 如果用户正在导航，则告知 Google 地图允许使用渡轮的路线。如果允许使用渡轮可获得更优路线，系统可能会重新规划路线。
geo.action:?act=avoid_highways 如果用户正在导航，则指示 Google 地图避开高速公路。如果当前有效路线包含高速公路，这可能会导致重新规划路线。
geo.action:?act=allow_highways 如果用户正在导航，则告知 Google 地图允许使用高速公路。如果允许使用高速公路可获得更优路线，系统可能会重新规划路线。
geo.action:?act=eta 如果用户正在导航，Google 地图会播报目的地的预计到达时间（例如上午 9:15）。
geo.action:?act=time_to_destination 如果用户正在导航，Google 地图会播报到达目的地的预计时间（例如 15 分钟）。
geo.action:?act=exit_navigation 退出导航。
geo.action:?act=select_search_result&id=0 如果搜索结果目前显示在屏幕上（见下文），则根据提供的 ID 参数开始导航到第 n 个结果。请注意，索引从 0 开始（即，上述 intent 将选择列表中的第一个结果）。

屏幕上显示的搜索结果