向表盘添加复杂功能

表盘复杂功能可显示来自数据源的数据。利用 Complications API，表盘可以选择要用于获取基础数据的数据源。这样一来，表盘不但可以显示时刻，还可以显示其他信息，而且无需通过代码来获取数据。

使用 ComplicationSlotsManager

如需向表盘添加复杂功能，请使用 ComplicationSlotsManager。

ComplicationSlotsManager 可定义表盘所支持复杂功能的数量及其在屏幕中的位置。为了支持更改复杂功能的位置或数量，ComplicationSlotsManager 还会使用 CurrentUserStyleRepository，如以下示例所示：

 override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager {
        val defaultCanvasComplicationFactory =
            CanvasComplicationFactory { watchState, listener ->
                // ...
            }

        val leftComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 100,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        val rightComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 101,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        return ComplicationSlotsManager(
            listOf(leftComplicationSlot, rightComplicationSlot),
            currentUserStyleRepository
        )
 }

类型和字段

下表介绍了 ComplicationData 对象的类型和字段。如果表盘请求复杂功能类型无效的字段，则系统会返回该字段的默认值。例如，如果表盘尝试访问 SHORT_TEXT 类型的 LONG_TEXT 字段，系统将返回 LONG_TEXT 字段的默认值 (null)。

类型	必填字段	选填字段	备注
`SHORT_TEXT`	短文本	图标防烧屏功能图标短标题	仅显示一个图标或短标题（如果提供其中之一或同时提供两者）。
`ICON`	图标	防烧屏功能图标	在不需要文本时使用。该图标应使用单色，并且可能根据表盘进行着色。
`RANGED_VALUE`	值最小值最大值	图标防烧屏功能图标短文本短标题	不能保证会显示选填字段。如果您想自行绘制进度条，可以使用 `isRangedValueProgressHidden()` 方法隐藏 `ComplicationDrawable` 类提供的进度条。
`LONG_TEXT`	长文本	长标题图标防烧屏功能图标小图片	显示长标题（如果提供）。
`SMALL_IMAGE`	小图片		小图片具有以下两种样式之一：照片样式或图标样式。照片样式的图片应当可以填充空间并且可以裁剪；图标样式的图片不能裁剪，并且可能有内边距。由于图片是可变的，因此使用具有防烧屏功能或低位氛围模式的设备可能会显示不适合在氛围模式下显示的图片。如果启用了防烧屏功能或低位氛围模式，表盘可能会使用 Burn-in protection small image，因为它是安全的。否则，由于表盘很难判断图片是否适合显示，便不会显示。
`LARGE_IMAGE`	大图片		这种图片的大小应当足以填充表盘。由于图片是可变的，因此使用具有防烧屏功能或低位氛围模式的设备可能会显示不适合在氛围模式下显示的图片。由于表盘很难判断图片是否适合显示，因此如果已启用防烧屏功能或低位氛围模式，表盘就不会在氛围模式下显示图片。

下表介绍了可以针对任何复杂功能显示槽发送的空数据的复杂功能类型。这些类型没有对应的字段，也不需要包含在受支持类型的列表中；而且使表盘能够区分以下三种情况：

未选择任何数据源
用户已为显示槽选择“空”
数据源没有任何要发送的数据

数据源不应发送 TYPE_EMPTY 来响应更新请求，改为发送 TYPE_NO_DATA。

复杂功能类型	说明
`TYPE_NOT_CONFIGURED`	在启用复杂功能后，但用户尚未选择数据源且未设置任何默认值的情况下，系统会发送该类型。无法由数据源来发送。
`TYPE_EMPTY`	在启用复杂功能后且用户选择“空”（而非数据源），或者在表盘未选择任何数据源，而此类型作为默认值的情况下，系统会发送该类型。无法由数据源来发送。
`TYPE_NO_DATA`	在启用复杂功能（具有数据源）后，系统发送该类型以在接收数据源的实际数据之前清除复杂功能。如果数据源没有要发送的实际数据，相应数据源可发送该类型。

如需了解详情，请查看 GitHub 上的表盘示例。