向表盘添加复杂功能

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

使用表盘格式

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

有关更多信息，请查看 GitHub 上的 表盘格式示例。

类型和字段

下表描述了 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 推出的新手表上，表盘必须使用手表表盘格式。因此，我们建议您迁移到使用手表表盘格式。