向表盘添加复杂功能

表盘复杂功能可显示来自数据源的数据。使用 表盘格式,您可以选择数据源来获取底层信息 数据。这样一来,您的表盘不仅可以显示当前时间,还可以显示其他信息 而无需用于获取数据的代码。

使用表盘格式

借助 Complication 元素,您可以在 一个表盘主题您还可以通过该元素定义表盘上的位置 显示相应的每项复杂功能

如需了解详情,请参阅 WatchFaceFormat 示例 GitHub。

类型和字段

下表介绍了 ComplicationData 对象。如果表盘请求的字段无效 对于复杂功能类型,系统将返回该字段的默认值。例如: 如果表盘尝试访问 SHORT_TEXT 类型的 LONG_TEXT 字段, 返回 LONG_TEXT 字段的默认值 (null)。备注选填字段 也不一定会显示





类型 必填字段 选填字段 备注
SHORT_TEXT 短文本 图标
防烧屏功能图标
短标题
内容说明

仅显示一个图标或短标题(如果提供其中之一或同时提供两者)。
MONOCHROMATIC_IMAGE 单色图片
防烧屏功能图标
内容说明

在不需要文本时使用。该图标应使用单色,并且可能根据表盘进行着色。
RANGED_VALUE
最小值
最大值
单色图片
防烧屏功能图标
短文本
短标题
颜色梯度
动态值
内容说明

如果您想自行绘制进度条,可以使用 isRangedValueProgressHidden() 方法隐藏 ComplicationDrawable 类提供的进度条。
GOAL_PROGRESS
目标值
单色图片
防烧屏功能图标
短文本
短标题
颜色梯度
动态值
内容说明

GOAL_PROGRESS 适用于步数等,其中“值”从零开始,并且可以超出“目标值”。
LONG_TEXT 长文本
长标题
单色图片
防烧屏功能图标
小图片
内容说明
显示长标题(如果提供)。
SMALL_IMAGE 小图片
内容说明
小图片具有以下两种样式之一:照片样式或图标样式。照片样式的图片应当可以填充空间并且可以裁剪;图标样式的图片不能裁剪,并且可能有内边距。由于图片是可变的,因此使用具有防烧屏功能或低位氛围模式的设备可能会显示不适合在氛围模式下显示的图片。如果启用了防烧屏功能或低位氛围模式,表盘可能会使用 Burn-in protection 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 的新手表上,表盘必须使用 表盘格式。因此,我们建议您改为使用 表盘格式