为表盘添加复杂功能

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

使用表盘格式

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

如需了解更多信息，请查看 GitHub 上的WatchFaceFormat 示例。

类型和字段

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





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

 如果提供图标或短标题（或两者都提供），则只显示其中一个。
MONOCHROMATIC_IMAGE 单色图片
 防烧屏图标
内容描述

 在不需要文本时使用。图标应为单色，并可能由表盘着色。
RANGED_VALUE 值
最小值
最大值
 单色图片
防烧屏图标
短文本
短标题
颜色渐变
动态值
内容描述

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

 GOAL_PROGRESS 适用于步数等情况，其中“值”从零开始，并且允许超过“目标值”。
LONG_TEXT 长文本
 长标题
单色图片
防烧屏图标
小图片
内容描述
 如果提供，则显示长标题。
SMALL_IMAGE 小图片
 内容描述
 小图片有两种样式：照片样式或图标样式。照片样式表示预期它会填充空间并可以裁剪。图标样式表示它不能裁剪并且可以添加内边距。图片多样性可能导致在具有防烧屏或低位环境模式的设备上，在环境模式下显示不合适的图片。当启用防烧屏或低位环境模式时，表盘可能会使用防烧屏小图片，因为它更安全。否则，由于表盘难以判断适用性，图片将不显示。
LARGE_IMAGE 大图片
 内容描述
 此图片应足够大以填充表盘。图片多样性可能导致在具有防烧屏或低位环境模式的设备上，在环境模式下显示不合适的图片。由于表盘难以判断显示适用性，如果启用防烧屏或低位环境模式，表盘将不在环境模式下显示图片。
WEIGHTED_ELEMENTS 元素列表
 单色图片
防烧屏图标
短文本
短标题
内容描述
 每个元素都包含颜色和权重（大于零）。渲染时元素的大小应与其权重成比例。权重不要求总和为特定值。请注意，表盘可以重新着色 WEIGHTED_ELEMENTS。

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

  • 未选择来源
  • 用户为槽位选择了“空”
  • 来源没有数据可发送

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

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

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

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

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

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

如果您的现有表盘使用 Jetpack Watch Face 库或 Wearable Support 库，用户将在以下设备上的表盘复杂功能中继续看到来自所有数据源的数据

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

此外，如果您的现有表盘使用 Jetpack Watch Face 库或 Wearable Support 库并安装在这些设备之一上，则该表盘可以继续接收更新。

然而，在搭载 Wear OS 5 发布的新手表上，表盘必须使用表盘格式。因此，我们建议您迁移到使用表盘格式。