表盘复杂功能

复杂功能是指表盘主题中显示的除时间以外的其他任何功能。例如，电量指示器就是一项复杂功能。Complications API 既适用于表盘主题，也适用于数据提供器应用。

本文档的其余部分介绍了数据提供程序、表盘和复杂功能类型。

复杂功能数据提供器

为表盘主题提供复杂功能相关数据（如电池电量、天气或步数数据）的应用称为“复杂功能数据提供器”。这些数据提供器会提供原始数据，并不负责控制数据在表盘主题上的呈现方式。要编写为表盘主题提供数据的应用，请参阅向复杂功能提供数据。

如下图所示，Wear OS by Google 谷歌负责调节从提供器到表盘主题的数据流。

复杂功能数据流

表盘中的复杂功能

表盘主题从复杂功能数据提供器接收数据，这样便可以包含复杂功能，而无需用于获取底层数据的代码。表盘控制数据的呈现方式，因此可以将数据与其设计自然融合在一起；请参阅复杂功能的设计模式。

如需了解如何向表盘添加复杂功能，请参阅向表盘添加复杂功能。

复杂功能类型

复杂功能类型定义了可在复杂功能中显示的数据类型或可由数据提供器提供的数据类型。例如，当数据主要由短字符串组成时，使用 SHORT_TEXT 类型。ComplicationData 对象始终有一个复杂功能类型，用来定义必填字段和选填字段。通常，必填字段代表数据的主要部分；大多数类型的名称都取自必填字段。

数据提供器使用这些复杂功能类型的方式与表盘主题有所不同：

  • 数据提供器会选择要提供的复杂功能数据类型（包括要提供这些类型的哪些选填字段）以及可以支持多少种不同类型。例如，步数提供器可能支持 RANGED_VALUE 和 SHORT_TEXT 类型，而“下次会议”提供器可能支持 SHORT_TEXT 和 LONG_TEXT 类型。
  • 您可以选择要在表盘主题中包含的复杂功能数量以及要支持的复杂功能类型。例如，表盘上的刻度盘复杂功能可能支持 SHORT_TEXT、ICON 和 RANGED_VALUE 类型，而表盘上的计量器可能仅支持 RANGED_VALUE 类型。

如需详细了解不同的复杂功能类型以及每种类型支持的字段，请参阅使用和测试复杂功能类型。

API 摘要

以下是 Complications API 的摘要。此 API 是穿戴式设备支持库的一部分；请参阅 Wear API 参考文档。

  • ComplicationData
    • Parcelable（在内部使用软件包）；不可变
    • 代表所有类型的复杂功能数据
    • 包含用于创建实例的 Builder
  • ComplicationDrawable
    • 可让您在画布上呈现整个复杂功能
  • ComplicationHelperActivity
    • 用于请求以下权限：
      com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
    • 替代了 ProviderChooserIntent，在几乎所有情况下用于启动选择器
  • ComplicationManager
    • 复杂功能管理器服务的封装容器，供提供程序使用
    • 允许提供程序向系统发送复杂功能数据
  • ComplicationProviderService
    • 扩展 Service 并包含回调方法来响应复杂功能系统
    • 回调方法都在主线程上调用
  • ComplicationText
    • 用于在 ComplicationData 对象中提供基于文本的值
    • 包含随时间变化的值的选项，其文本值取决于当前时间
  • ProviderChooserIntent
    • 不常用且不可实例化的实用程序类；改用 ComplicationHelperActivity
  • ProviderInfoRetriever
    • 可（由表盘配置 Activity）用来检索属于相应表盘的所有复杂功能的当前数据提供程序信息（应用、提供程序名称、图标）
  • ProviderUpdateRequester
    • 可供数据提供程序应用用来在其提供程序服务中触发对 onComplicationUpdated 的调用，以启用更新推送
  • SystemProviders
    • 列出因仅提供表盘本来可以自行获取的信息而被视为“安全”的系统提供程序
  • TextRenderer
    • 简化在画布上绘制文字的操作

此外，WatchFaceService.Engine 类还包含以下方法：