向表盘添加复杂功能

表盘复杂功能显示来自数据源的数据。使用手表表盘格式，您可以选择数据源以获取基础数据。这可以让您的表盘显示除时间以外的信息，而无需编写获取数据的代码。

使用手表表盘格式

Complication 元素允许您在一个表盘中定义最多八个复杂功能。该元素还允许您定义每个复杂功能在表盘上的显示位置。

有关更多信息，请查看 GitHub 上的WatchFaceFormat 示例。

类型和字段

下表描述了ComplicationData 对象的类型和字段。如果表盘请求的字段对于复杂功能类型无效，则会返回该字段的默认值。例如，如果表盘尝试访问SHORT_TEXT类型的LONG_TEXT字段，则会返回LONG_TEXT字段的默认值 null。请注意，可选字段不保证会显示。





类型 必填字段 可选字段 备注
SHORT_TEXT 短文本 图标
防烧屏保护图标
短标题
内容描述

 如果提供任一或两个图标或短标题，则仅显示一个图标或短标题。
MONOCHROMATIC_IMAGE 单色图像
 防烧屏保护图标
内容描述

 当不需要文本时使用。预计图标为单色，表盘可能会对其进行着色。
RANGED_VALUE 值
最小值
最大值
 单色图像
防烧屏保护图标
短文本
短标题
颜色渐变
动态值
内容描述

 如果要绘制自己的进度条，可以使用 isRangedValueProgressHidden() 方法隐藏由 ComplicationDrawable 类提供的进度条。
GOAL_PROGRESS 值
目标值
 单色图像
防烧屏保护图标
短文本
短标题
颜色渐变
动态值
内容描述

 GOAL_PROGRESS 用于步数等情况，其中 Value 从零开始，并且允许超过 Target 值。
LONG_TEXT 长文本
 长标题
单色图像
防烧屏保护图标
小图像
内容描述
 如果提供了长标题，则显示长标题。
SMALL_IMAGE 小图像
 内容描述
 小图像有两种样式：照片样式或图标样式。照片样式表示它应该填充空间，并且可以裁剪。图标样式表示它不能裁剪，并且可以填充。图像变化可能会导致在具有防烧屏保护或低位环境模式的设备的环境模式下显示不合适的图像。启用防烧屏保护或低位环境模式时，表盘可能会使用防烧屏保护小图像，因为它很安全。否则，由于表盘难以确定是否合适，因此不会显示图像。
LARGE_IMAGE 大图像
 内容描述
 此图像应足够大以填充表盘。图像变化可能会导致在具有防烧屏保护或低位环境模式的设备的环境模式下显示不合适的图像。由于表盘难以确定是否适合显示，因此如果启用了防烧屏保护或低位环境模式，表盘不会在环境模式下显示图像。
WEIGHTED_ELEMENTS 元素列表
 单色图像
防烧屏保护图标
短文本
短标题
内容描述
 每个元素都包含一种颜色和一个权重（大于零）。渲染时元素的大小应与其权重成正比。权重不需要加总到任何特定值。请注意，表盘可以重新着色 WEIGHTED_ELEMENTS。

下表描述了可以为任何复杂功能插槽发送的空数据的复杂功能类型。这些类型没有字段，不需要包含在支持类型列表中。这些类型使表盘能够区分以下三种情况

  • 未选择任何源
  • 用户已为插槽选择“空”
  • 某个源没有要发送的数据

源不能在响应更新请求时发送TYPE_EMPTY。请改用发送TYPE_NO_DATA。

复杂功能类型 描述
TYPE_NOT_CONFIGURED 当复杂功能激活但用户未选择源且未设置默认值时，由系统发送。

源无法发送。
TYPE_EMPTY 当复杂功能激活并且用户选择“空”而不是源，或者表盘选择没有源并将此复杂功能类型作为默认值时，由系统发送。

源无法发送。
TYPE_NO_DATA 当具有源的复杂功能激活以清除复杂功能并在从源接收实际数据之前发送时，由系统发送。

如果源没有要发送的实际数据，则可以由源发送。

在某些设备上，表盘和复杂功能必须使用手表表盘格式

如果现有的表盘使用Jetpack 表盘库或可穿戴支持库，则用户将继续在以下设备上的表盘复杂功能中查看来自所有数据源的数据

  • 运行 Wear OS 4 或更早版本的设备。
  • 接收 Wear OS 5 OTA 升级的设备。

此外，如果您的现有表盘使用 Jetpack 表盘库或可穿戴支持库，并且安装在这些设备之一上，则表盘可以继续接收更新。

但是，在使用 Wear OS 5 推出的新手表上，表盘必须使用手表表盘格式。因此，我们建议您迁移到使用手表表盘格式。