将复杂功能添加到表盘

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

使用表盘格式

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 表盘库可穿戴设备支持库,用户将继续在以下设备上的表盘复杂功能中看到所有数据源的数据:

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

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

但是,在发布时预装 Wear OS 5 的新智能手表上,表盘必须使用表盘格式。因此,我们建议您迁移到使用表盘格式。