表盘复杂功能

复杂功能是表盘中显示的除时间以外的其他任意功能。 例如,电池指示器就是一个复杂功能。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
    • 可打包(在内部使用 Bundle);不可变
    • 表示所有类型的复杂功能数据
    • 包括一个用于创建实例的构建器
  • ComplicationDrawable
    • 使您可以在画布上渲染整个复杂功能
  • ComplicationHelperActivity
    • 用于请求以下权限:
      com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
    • 用于在几乎所有情况下代替 ProviderChooserIntent 来启动选择器
  • ComplicationManager
    • 一种用于复杂功能管理器 service 的包装器,供提供程序使用
    • 允许提供程序向系统发送复杂功能数据
  • ComplicationProviderService
    • 拓展 Service 和包含回调函数以响应复杂功能系统
    • 回调函数全部在主线程上调用
  • ComplicationText
    • 用于在 ComplicationData 对象中提供基于文本的值
    • 包括用于随时间变化的值的选项,其文本值取决于当前时间
  • ProviderChooserIntent
    • 不常用的不可实例化实用程序类;请使用 ComplicationHelperActivity
  • ProviderInfoRetriever
    • 可用于(通过表盘配置 Activity)为属于表盘的所有复杂功能检索当前数据提供程序信息(应用、提供程序名称、图标)
  • ProviderUpdateRequester
    • 可由数据提供程序应用用于在其提供程序 service 中触发对 onComplicationUpdated 的调用,以启用更新推送
  • SystemProviders
    • 列出被视为“安全”的系统提供程序,因为这些提供程序仅提供表盘自身已经可以获取的信息
  • TextRenderer
    • 擦除画布上的文本绘制

此外,WatchFaceService.Engine 类还包含以下函数: