Developer

Cluster

Request Access
Version: 0.5.0

介绍

本教程将指导您如何在车辆的仪表盘集群上集成导航元素。

Cluster 活动

Automotive Navigation Application 包含一个专用的 Cluster Activity，旨在在车辆的仪表盘集群上显示导航信息。
Cluster Activity 提供了一个可定制的 UI，用于显示导航元素，如地图、操作指令和预计到达时间（ETA）信息。
它会自动适应当前的导航状态，确保向驾驶员展示相关信息。

Cluster Activity

如何集成 Cluster Activity

定义默认配置

集成 Cluster Activity 的第一步是定义您自己的默认配置。
Cluster Activity 可以在启动时通过在启动 Activity 的 intent 中传递 JSON 配置作为额外参数来配置。
该配置允许您定义在 Cluster 上显示哪些组件及其布局。

请参阅下文的配置参数部分，了解可用配置参数及其默认值的概述。

启动 Cluster Activity

Cluster Activity 可以通过 intent 启动。
虽然可以使用内置的默认配置启动 Cluster Activity，但建议在启动时传递适当的默认配置作为额外参数。

1val myClusterActivityDefaultConfiguration = """
2    {
3      "displayHpComponent": true,
4      "displayVignette": true,
5      "displayPX": false,
6      (...),
7    }
8""".trimIndent()
9

10val intent = Intent()
11intent.action = "com.tomtom.automotive.clusterui.cluster.COMPONENT_VISIBILITY"
12intent.addCategory("android.car.cluster.NAVIGATION")
13intent.putExtra("clusterConfigurationUpdate", myClusterActivityDefaultConfiguration)
14startActivity(intent)

运行时更新配置

您可以通过启动 Cluster Activity 时使用的相同 intent 在运行时更新配置。
请注意，配置更新不需要详尽无遗，这意味着您可以只更新想要更改的参数。

更改 ETA 组件可见性的示例

您可以通过 intent 编程方式更新配置：

1val intent = Intent()
2intent.action = "com.tomtom.automotive.clusterui.cluster.COMPONENT_VISIBILITY"
3intent.addCategory("android.car.cluster.NAVIGATION")
4intent.putExtra("clusterConfigurationUpdate", "{\"displayHpComponent\": false}")
5startActivity(intent)

同样也可以通过 adb 实现：

1adb shell
2am start -a "com.tomtom.automotive.clusterui.cluster.COMPONENT_VISIBILITY" \
3         -c "android.car.cluster.NAVIGATION" \
4         --es "clusterConfigurationUpdate" '{"displayHpComponent": false}'

配置参数

Cluster Activity 的配置使用 JSON 定义，支持以下参数：

参数描述类型默认值
displayHpComponent

如果参数设置为 true，则在 Cluster 上显示 Horizon Panel 组件，否则隐藏。
其尺寸和屏幕上的位置由 hpComponentRect 参数的值决定。

booleantrue
hpComponentRect

表示一个矩形，用于配置 Horizon Panel 的尺寸和位置。

Horizon Panel positioning
object实现定义
hpElementsToShowOnCluster

配置在 Horizon Panel 上显示哪些子面板。

可能的取值：

  • SLG：简单车道引导面板
  • CMP：连续操作面板
  • ETA：预计到达时间面板
  • JV：交叉口视图面板
  • UEP：即将发生事件面板
Horizon Panel elements
setCMP
nipLayoutType

表示 Next Instruction Panel（作为 Horizon Panel 的一部分显示）的布局配置。

可选值：NORMAL_LAYOUT、LANDSCAPE_MINIMAL、LANDSCAPE_MEDIUM、 LANDSCAPE_MAXIMAL、PORTRAIT_MINIMAL、PORTRAIT_MEDIUM、PORTRAIT_MAXIMAL。

stringNORMAL_LAYOUT
etaLayoutType

表示 ETA 面板的布局配置类型（作为 Horizon Panel 的一部分显示）。

可能的取值：NORMAL_LAYOUT_WIDE、NORMAL_LAYOUT_NARROW、MINIMAL、 MEDIUM、MAXIMAL。

stringMINIMAL
displayMapComponent如果参数设置为 true，则在 Cluster 上显示地图组件，否则隐藏。booleantrue
displayVignette如果参数设置为 true，则在 Cluster 的外缘显示渐晕效果，否则隐藏。booleantrue
displayPX

如果参数设置为 true，则支持像素显示配置。
如果您以像素为单位提供 startMargin、topMargin、width 和 height，则应将此参数设置为 true。
如果参数设置为 false，则以密度相关像素为单位提供这些值。

booleanfalse
safeAreaComponentRect

表示一个矩形，用于配置 Cluster 上安全区域组件的尺寸和位置。
Chevron（箭头）位于安全区域矩形的中间。

object实现定义

示例配置

下面是一个示例配置：

1    {
2      "displayHpComponent": true,
3      "hpComponentRect": {
4        "topMargin": 0,
5        "startMargin": 0,
6        "width": 403,
7        "height": 640
8      },
9      "hpElementsToShowOnCluster": [
10        "CMP"
11      ],
12      "nipLayoutType": "NORMAL_LAYOUT",
13      "etaLayoutType": "MINIMAL",
14      "displayMapComponent": true,
15      "displayVignette": true,
16      "displayPX": false,
17      "safeAreaComponentRect": {
18        "topMargin": 0,
19        "startMargin": 574,
20        "width": 574,
21        "height": 840
22      }
23    }

最佳实践

由于您只能配置（而不能修改）Cluster Activity：

  • 适应您的显示密度：根据仪表盘集群的显示特性，适当使用 displayPX 参数。