Cluster

介绍

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

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，但建议在启动时传递适当的默认配置作为额外参数。

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

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

运行时更新配置

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

更改 ETA 组件可见性的示例

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

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

同样也可以通过 adb 实现：

1
adb shell
2
am 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` 参数的值决定。	`boolean`	`true`
`hpComponentRect`	表示一个矩形，用于配置 Horizon Panel 的尺寸和位置。	`object`	实现定义
`hpElementsToShowOnCluster`	配置在 Horizon Panel 上显示哪些子面板。可能的取值： `SLG`：简单车道引导面板 `CMP`：连续操作面板 `ETA`：预计到达时间面板 `JV`：交叉口视图面板 `UEP`：即将发生事件面板	`set`	`CMP`
`nipLayoutType`	表示 Next Instruction Panel（作为 Horizon Panel 的一部分显示）的布局配置。可选值：`NORMAL_LAYOUT`、`LANDSCAPE_MINIMAL`、`LANDSCAPE_MEDIUM`、 `LANDSCAPE_MAXIMAL`、`PORTRAIT_MINIMAL`、`PORTRAIT_MEDIUM`、`PORTRAIT_MAXIMAL`。	`string`	`NORMAL_LAYOUT`
`etaLayoutType`	表示 ETA 面板的布局配置类型（作为 Horizon Panel 的一部分显示）。可能的取值：`NORMAL_LAYOUT_WIDE`、`NORMAL_LAYOUT_NARROW`、`MINIMAL`、 `MEDIUM`、`MAXIMAL`。	`string`	`MINIMAL`
`displayMapComponent`	如果参数设置为 true，则在 Cluster 上显示地图组件，否则隐藏。	`boolean`	`true`
`displayVignette`	如果参数设置为 true，则在 Cluster 的外缘显示渐晕效果，否则隐藏。	`boolean`	`true`
`displayPX`	如果参数设置为 true，则支持像素显示配置。如果您以像素为单位提供 `startMargin`、`topMargin`、`width` 和 `height`，则应将此参数设置为 true。如果参数设置为 false，则以密度相关像素为单位提供这些值。	`boolean`	`false`
`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 参数。