向表盘添加复杂功能

表盘复杂功能可显示来自数据源的数据。使用 [表盘格式][1]，您可以选择数据源以获取底层数据。这样一来，表盘不但可以显示时刻，还可以显示其他信息，而且无需通过代码来获取数据。

使用表盘格式

借助 [Complication][2] 元素，您可以在单个表盘中定义最多 8 个复杂功能。您还可以通过该元素定义每个复杂功能在表盘上的显示位置。

如需了解详情，请查看 GitHub 上的 [WatchFaceFormat 示例][4]{: .external}。

类型和字段

下表介绍了 [ComplicationData][3] 对象的类型和字段。如果表盘请求复杂功能类型无效的字段，系统会返回该字段的默认值。例如，如果表盘尝试访问 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	当具有数据源的复杂功能激活时，系统发送该类型以在接收数据源的实际数据之前清除复杂功能。 如果数据源没有要发送的实际数据，相应数据源可发送该类型。

大多数数据源都需要表盘格式

如需在即将发布的 Wear OS 版本中保留表盘复杂功能的外观，您必须使用 [表盘格式][1]。如果您的表盘改用 [Jetpack 表盘库][6] 或 [穿戴式设备支持库][7]，则较新版本的 Wear OS 将无法在表盘复杂功能中显示来自大多数数据源的数据。

为了在不使用表盘格式的表盘中完全保留复杂功能的外观，表盘必须在其复杂功能显示槽中使用以下数据源之一：

• [DATA_SOURCE_WATCH_BATTERY][8]
• [DATA_SOURCE_APP_SHORTCUT][12]
• [DATA_SOURCE_UNREAD_NOTIFICATION_COUNT][13]
• [DATA_SOURCE_DATE][9]
• [DATA_SOURCE_TIME_AND_DATE][10]
• [DATA_SOURCE_DAY_OF_WEEK][14]
• [DATA_SOURCE_DAY_AND_DATE][15]
• [DATA_SOURCE_WORLD_CLOCK][11]

在不使用表盘格式的表盘中，您可能会看到一些额外的复杂功能来源，具体取决于设备制造商。