向表盘添加复杂功能

表盘复杂功能显示来自数据源的数据。使用 Watch Face Format，您可以选择数据源以获取基础数据。这使您的表盘能够显示除时间以外的信息，而无需编写获取数据的代码。

使用 Watch Face Format

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 当具有来源的复杂功能激活以清除复杂功能然后再从来源接收实际数据时，由系统发送。

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

在某些设备上，表盘和复杂功能必须使用 Watch Face Format

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

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

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

但是，在预装 Wear OS 5 的新款手表上，表盘必须使用 Watch Face Format。因此，我们建议您迁移到使用 Watch Face Format。