在手表表盘中添加复杂功能

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

使用手表表盘格式

使用 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 或更早版本的设备。
  • 收到 Wear OS 5 的 OTA 升级的设备。

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

但是，在搭载 Wear OS 5 的新手表上，表盘必须使用 表盘格式。为此，我们建议你迁移到使用表盘格式。