Skip to content

Most visited

Recently visited

navigation

表盘复杂功能

复杂功能是表盘中小时和分钟显示之外的任意功能。例如,电池指示器就是一个复杂功能。Complications API 适用于表盘和数据提供程序应用。

复杂功能

表盘无需用于获取底层数据的代码即可显示额外信息。数据提供程序可以使用 API 向任意表盘提供数据(例如,电池电量、天气或步数数据)。

为复杂功能向表盘提供数据的应用称为“复杂功能数据提供程序”。这些数据提供程序不负责控制它们的数据在表盘上的渲染方式。因此,表盘可以自然地将数据与表盘设计集成;请参阅复杂功能的设计模式

表盘负责绘制其复杂功能。表盘可以接收各种类型的复杂功能数据(例如,小文本数据或图标数据),然后显示这些数据。请参阅向表盘添加复杂功能

如下图中所示,Android Wear 负责调节从提供程序到表盘的数据流。

复杂功能数据流

对于向表盘提供数据的写入应用,请参阅向复杂功能显示数据

向表盘添加复杂功能

表盘开发者可以接收复杂功能数据并让用户可以选择数据提供程序。此外,Android Wear 还提供了一个用于选择数据源的界面

接收数据

要开始接收复杂功能数据,表盘将通过一个表盘复杂功能 ID 列表在 WatchFaceService.Engine 类中调用 setActiveComplications()。表盘会创建这些 ID,对复杂功能可以在表盘上显示的位置进行唯一标识,并将这些 ID 传递至 createProviderChooserIntent() 函数以允许用户决定各个复杂功能的显示位置。

复杂功能数据通过 WatchFaceService.EngineonComplicationDataUpdate() 回调进行传输。

渲染复杂功能

只要预期字段得到表示,表盘就可能根据需要渲染数据;应始终包含必填字段,并且数据也应以相同方式进行表示。根据类型的不同,也应包含一些可选字段(请参阅下中的“备注”列)。

我们为自己的样式提供了设计指南,作为标准复杂功能的建议,不过开发者既可以使用他们自己的样式,也可以通过不同方式将数据整合到表盘中。

绘制复杂功能

您可以利用 ComplicationDrawable 类在画布上渲染整个复杂功能。

该类支持全部六个主要的复杂功能类型,并为您进行以下操作:

如果您针对 API 级别 24,可以在 XML 中将 ComplicationDrawable 对象定义为资源。或者,您也可以通过编程方式创建一个 ComplicationDrawable 对象。您应使用 draw() 函数绘制一个复杂功能,并为交互模式和微光模式设置样式选项。

如需了解有关绘制复杂功能的详细说明和示例,请参阅 ComplicationDrawable,其中包括示例 XML。有关利用此类并包含示例 XML 的示例表盘,请参阅表盘示例应用中的 AnalogComplicationWatchFaceService 示例。

如果您不使用 ComplicationDrawable 对象,请为复杂功能的文本使用 TextRenderer

渲染文本

TextRenderer 类旨在用于复杂功能,并且可以简化画布上的文本绘制。该类包括以下特性:

初始化表盘引擎时,您可以创建一个 TextRenderer 对象并将其传入您希望 TextRenderer 对象使用的 TextPaint 对象。TextPaint 对象可以定义字体、文本大小和颜色等。您应为每个字段创建一个 TextRenderer 对象,例如,为文本字段和标题字段各创建一个。

如需了解示例代码,包括用于在想要渲染的文本上指定边界的代码,请参阅 TextRenderer

允许用户选择数据提供程序

Android Wear 通过 Activity 提供了一个界面,让用户可以为特定的复杂功能选择提供程序。表盘可以调用 createProviderChooserIntent 函数来获取一个 intent,这个 intent 可用于显示选择器界面。

此 intent 必须与 startActivityForResult() 结合使用。在调用 createProviderChooserIntent 时,表盘将提供一个表盘复杂功能 ID 和一个受支持类型的列表。这些类型应当按照优先级顺序列示,提供更多信息的类型(例如范围值)通常具有更高的优先级。

在用户选择数据提供程序时,配置将自动保存;不需要表盘提供其他任何信息。

用户与复杂功能的交互

提供程序可以指定在用户点按复杂功能时发生的操作,因此,大多数复杂功能都应当是可点按的。此操作将被指定为 ComplicationData 对象中的 PendingIntent。表盘负责检测复杂功能上的点按,并且应在点按发生时触发待定 intent。

可能无法将某些复杂功能设置为可点按(例如,填充表盘整个背景的复杂功能),不过,表盘会尽可能接受对复杂功能的点按。

具有复杂功能的任何表盘都应包含一种可让用户配置这些复杂功能的方式。请参阅表盘示例应用,了解界面设置的全功能建议代码。

该代码具备以下特性:

查看该代码的起点是 AnalogComplicationConfigActivity 类,它具有一个 getDataToPopulateAdapter() 函数,此函数可以返回界面中可用设置条目的列表。

复杂功能数据的权限

表盘必须具有以下权限才能接收复杂功能数据和打开提供程序选择器:

com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA

打开提供程序选择器

没有获得以上权限的表盘将无法启动提供程序选择器。

为了简化请求权限和启动选择器的操作,穿戴式设备支持库中提供了 ComplicationHelperActivity 类。在几乎所有情况下,应使用此类而不是 ProviderChooserIntent 类来启动选择器。

请求必要权限

要使用 ComplicationHelperActivity,请在 manifest 文件中将其添加到表盘:

<activity android:name="android.support.wearable.complications.ComplicationHelperActivity"/>

要启动提供程序选择器,请调用 ComplicationHelperActivity.createProviderChooserHelperIntent 函数来获取一个 intent。

可以将新 intent 与 startActivitystartActivityForResult 结合使用来启动选择器。

下面是一个将新 intent 与 startActivityForResult 结合使用的示例:

startActivityForResult(
  ComplicationHelperActivity.createProviderChooserHelperIntent(
     getActivity(),
     watchFace,
     complicationId,
     ComplicationData.TYPE_LARGE_IMAGE),
  PROVIDER_CHOOSER_REQUEST_CODE);

在帮助程序 Activity 启动后,它将检查是否已授予权限。如果未授予权限,帮助程序 Activity 将发起一个运行时权限请求。如果权限请求被接受(或者不需要),将显示提供程序选择器。

如果 startActivityForResult 与 intent 结合使用,传回调用 Activity 的结果的代码将为 RESULT_OK(提供程序成功设置)或者 RESULT_CANCELLED(未设置提供程序)。

在设置提供程序的情况下,选定提供程序的 ComplicationProviderInfo 类将包含在结果的数据 intent 中,作为一个带有 ProviderChooserIntent#EXTRA_PROVIDER_INFO 键的额外项。

接收复杂功能数据

一般情况下,表盘需要上面的权限才能接收复杂功能数据,不过也存在一些例外。具体来说,只有在满足以下任意条件的情况下,表盘才能从提供程序接收数据:

缺少相应的权限

如果以上条件都不满足,那么当 ComplicationData 正常被提供程序发送到表盘时,系统将发送 TYPE_NO_PERMISSION 类型的数据。此类型包括一个图标(叹号)和短文本(“--”),允许其方便地作为短文本类型或图标类型渲染。

在接收 TYPE_NO_PERMISSION 类型的数据时,表盘应对数据进行相应渲染,以便用户可以看到复杂功能正常工作需要该操作。如果可以,此状态下的复杂功能点按应启动权限请求。如果帮助程序 Activity 已添加到表盘应用中,可以使用 ComplicationHelperActivity.createPermissionRequestHelperIntent() 请求权限。

如果用户接受通过帮助程序 Activity 创建的权限请求,将自动为表盘上的所有活动复杂功能请求更新,允许 TYPE_NO_PERMISSION 数据被真实数据替换。

安全的提供程序

由于一些系统提供程序仅提供表盘自身已经获取的信息,所以它们被视为安全的。

这些提供程序列在穿戴式设备支持库的 SystemProviders 类中;请参阅 Wear API 参考。有关列表,另请参阅系统提供程序部分。

提供程序指定的安全表盘

提供程序可以将特定表盘指定为“安全的”以接收其数据。只有表盘尝试将提供程序用作默认值(见下文),并且提供程序信任表盘应用时,才应使用这种方式。

为了将表盘声明为安全的,提供程序会添加一个带有 android.support.wearable.complications.SAFE_WATCH_FACES 键的元数据。元数据值应为逗号分隔的列表(忽略空格)。列表中的条目可以是 WatchFaceServices 的组件名称(假设已调用 ComponentName.flattenToString()),也可以是应用的软件包名称(指定应用中的每一个表盘都被视为安全的)。

例如:

<meta-data
       android:name="android.support.wearable.complications.SAFE_WATCH_FACES"
        android:value="
          com.app.watchface/com.app.watchface.MyWatchFaceService,
          com.anotherapp.anotherwatchface/com.something.WatchFaceService,
          com.something.text
        "/>

表盘的默认提供程序

表盘可以指定在用户选择提供程序前使用的默认提供程序。

设置默认提供程序

WatchFaceService.Engine 中使用 setDefaultComplicationProvider() 函数设置默认提供程序。可以随时调用此函数,不过,如果用户已经为给定的复杂功能选择提供程序,调用此函数将不起作用。

对于大多数提供程序,在数据可以流向表盘之前,必须向表盘授予 RECEIVE_COMPLICATION_DATA 权限。不过,一些系统提供程序被视为安全的,并且不需要表盘具有该权限即可发送数据(请参阅安全的提供程序系统提供程序)。最好将这些提供程序用作默认值,因为它们可以立即提供数据。

或者,如果表盘与特定的提供程序有联系并且希望将这个提供程序用作默认值,可以请求该提供程序将其列为安全表盘(请参阅提供程序指定的安全表盘)。

系统提供程序

系统包括可以用作默认值的提供程序。WatchFaceService.Engine 类中的 setDefaultSystemComplicationProvider() 函数可以为复杂功能设置默认的系统提供程序。此函数将获取一个表示系统提供程序的 ID(整型)。可用 ID 列在 SystemProviders 类中。

下表包含与被视为安全的提供程序有关的详细信息:

SystemProviders 类中的函数名称 安全性 可以是默认值 备注
dateProvider() 标准的系统日期提供程序。点按将打开标准的“日程”应用。
currentTimeProvider() 标准的系统“时间与日期”提供程序。无点按操作。
batteryProvider() 标准的系统电池提供程序。无点按操作。
stepCountProvider() 显示每日总步数,通过 readDailyTotal 报告。
unreadCountProvider() 显示流中的未读通知数量。
worldClockProvider() 将默认为伦敦或纽约。可以点按来更改时区。
appsProvider() 最初将显示“应用”图标,可以点按来选择应用。
nextEventProvider() 是(但不是安全的提供程序) 标准的系统“下一个活动”提供程序。点按将打开标准的“日程”应用。

向复杂功能显示数据

复杂功能数据提供程序是一个可以扩展 ComplicationProviderService 的 service。要响应来自系统的更新请求,您的数据提供程序必须实现 ComplicationProviderService 类的 onComplicationUpdate() 函数。此函数将在系统想要从您的提供程序获取数据时调用 - 可能是使用您的提供程序的复杂功能变成活动时,也可能是经过固定的时间后。ComplicationManager 对象将以参数形式传递到 onComplicationUpdate 函数中,可用于将数据送回系统。

:当您以复杂功能数据提供程序形式提供数据时,表盘将接收您发送的原始值,以便可以在表盘上绘制这些数据。

在您的应用的 manifest 中,声明 service 并为以下代码添加一个 intent 过滤器:

android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST
    

service 的 manifest 条目还应包含一个 android:icon 属性。提供的图标应是一个单色白图标。建议为图标使用矢量图。图标应表示提供程序并将显示在提供程序选择器中。

如果需要,请包含元数据,以指定受支持的类型、更新期间和配置操作;如需了解详情,请参阅 Wear API 参考中为 ComplicationProviderService 类列出的键。

此外,提供程序 service 的权限还能确保只有 Android Wear 系统可以绑定到提供程序 service。只有 Android Wear 系统具有此权限。

提供程序 service 应将以下代码添加到它们在 manifest 的 service 声明中:

android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER"

更新期间

您的提供程序可以在 manifest 中使用以下元数据键指定更新期间:

android.support.wearable.complications.UPDATE_PERIOD_SECONDS

应将更新期间设置得尽可能长,因为过于频繁地更新可能会影响电池续航时间。请注意,不能保证按照此频率发送更新请求。系统会应用最小更新期间,尤其是当设备处于微光模式或者未佩戴时,更新请求的频率可能会减小。

您也可以使用“推送样式”发送更新,而不是以固定频率请求更新。为此,您可以将更新期间设置为 0,这样就不会发生计划的更新请求(或者将其设为非零值),并根据需要使用 ProviderUpdateRequester 来触发对 onComplicationUpdate 的调用。

提供程序配置

如果需要,提供程序可以包含一个在用户选择数据提供程序时会向其显示的配置 Activity。要包含配置 Activity,请在 manifest 的提供程序 service 声明中添加一个元数据条目,该条目带有以下键:

android.support.wearable.complications.PROVIDER_CONFIG_ACTION

值可以是您选择的操作。

然后,为该操作创建一个带有 intent 过滤器的配置 Activity。配置 Activity 与提供程序必须位于相同的软件包中。配置 Activity 必须返回 RESULT_OKRESULT_CANCELED 以告知系统是否应设置提供程序。

如果数据提供程序需要特定的权限来访问用户数据,则需要运行时权限的标准代码。可以使用配置 Activity 请求提供程序需要的任何权限。

如需了解详情,请参阅 Wear API 参考ComplicationProviderService 类中的以下代码:

METADATA_KEY_PROVIDER_CONFIG_ACTION
    

使用和测试复杂功能类型

复杂功能类型决定复杂功能中显示的数据种类。例如,如果关键数据为短字符串,可以使用 SHORT_TEXT 类型。在 SHORT_TEXT 类型的示例中,可选数据是一个图标和一个短标题。

数据提供程序使用这些复杂功能类型的方式不同于表盘提供程序使用这些类型的方式:

ComplicationData 对象将始终具有一个复杂功能类型。每个复杂功能类型都有必填字段和可选字段。一般来说,必填字段表示数据的主要部分;大多数类型都会从必填字段中获取其名称。

给定类型可能包含不同的字段组。例如,SHORT_TEXT 可以是一段文本、标题与文本,或者是图标与文本。支持给定类型的复杂功能必须能够显示所有预计的变体。不过,一些可选字段不需要显示(请参阅下表中的备注列)。例如,RANGED_VALUE 类型的 Short title 字段不是必填字段,这样可以在不包含文本的情况下显示量表。

测试复杂功能类型

每个复杂功能类型都有字段,例如文本和图标。如果您的表盘支持复杂功能类型,那么您需要支持所有有效字段组合。

您可以测试复杂功能在表盘上显示的方式。具体来说,您可以使用测试套件测试复杂功能类型的显示。因此,您不需要编写代码来测试 ComplicationData 对象的有效字段组合。

测试套件是一个数据提供程序,以示例形式提供,它可以循环切换给定复杂功能类型的有效字段组合。

要使用测试套件,请执行以下操作:

  1. 在设备或者模拟器上安装测试套件 APK。
  2. 访问您的表盘并点按其主设置图标。
  3. 使用设置界面选择测试套件:WearComplication-ProviderTestSuite
  4. 选择一个要测试的复杂功能数据类型。
  5. 点按您的复杂功能以查看数据类型的变体。
  6. 重复点按您的复杂功能以验证所有相关字段组合都已正确显示。

例如,如果复杂功能支持短文本,请点按您的复杂功能以查看短文本的所有主要字段组合。

复杂功能类型示例

下面显示了复杂功能类型的示例:

复杂功能类型

类型和字段

下表介绍了 ComplicationData 对象的类型和字段。如果表盘请求对某种复杂功能类型来说无效的字段,将返回该字段的默认值。例如,如果表盘尝试访问 SHORT_TEXT 类型的 Long text 字段,将返回 Long text 字段的默认值。

类型 必填字段 可选字段 备注
SHORT_TEXT Short text Icon
Burn-in protection icon
Short title
预计应显示 Icon/Short title 中的一个(如果提供一个或两个)。
ICON Icon Burn-in protection icon 在不需要文本时使用。图标应是单色,可能会被表盘着色。
RANGED_VALUE Value
Min value
Max value
Icon
Burn-in protection icon
Short text
Short title
不保证显示可选字段。
LONG_TEXT Long text Long title
Icon
Burn-in protection icon
Small image
如果提供,应显示标题。
SMALL_IMAGE Small image 小图片拥有两种样式之一:照片样式图标样式。照片样式的图片应当可以填充空间并且可以裁剪;图标样式的图片不应裁剪,并且可能有内边距。在带有防烙印或低位微光模式的设备上,图片变化可能产生不适合在微光模式下显示的图片。由于表盘很难确定图片是否适合显示,因此如果已启用防烙印或低位微光模式,表盘就不应在微光模式下显示图片。
LARGE_IMAGE Large image 这种图片的大小应当足以填充表盘。在带有防烙印或低位微光模式的设备上,图片变化可能产生不适合在微光模式下显示的图片。由于表盘很难确定图片是否适合显示,因此如果已启用防烙印或低位微光模式,表盘就不应在微光模式下显示图片。

下表中的类型适合空白数据,并且可以针对任何复杂功能显示位置发送。这些类型没有字段,并且不需要包含到受支持类型的列表中。这些类型让表盘可以区分以下三种情况:

提供程序不应发送 TYPE_EMPTY 来响应更新请求。提供程序应发送 TYPE_NO_DATA

下表中介绍了适合“空白”数据的复杂功能类型的详细信息:

复杂功能类型 说明
TYPE_NOT_CONFIGURED 由系统在某个复杂功能已激活但用户尚未选择提供程序时发送,未设置默认值。

无法由提供程序发送。

TYPE_EMPTY 由系统在以下情况下发送:某个复杂功能已激活并且用户已选择“空白”而非提供程序,或者表盘未选择提供程序而是选择此类型作为默认值。

无法由提供程序发送。

TYPE_NO_DATA 由系统在某个复杂功能(具有提供程序)已激活时发送,用于在从提供程序接收实际数据之前清除复杂功能。

在提供程序没有要发送的实际数据时应由提供程序发送。

为复杂功能数据使用字段

ComplicationData 对象的字段具有不同的功能。例如,文本字段包含主要数据,而标题字段则为说明性;步数复杂功能的文本字段值可能为“2,543”,标题字段值为“steps”。

下表包含 ComplicationData 对象中字段的说明。这些字段可能填充也可能不填充,具体取决于复杂功能类型。

字段 说明
Short text 小型复杂功能的主要文本字段。此字段的最大长度不应超过七个字符(包括任何随时间而变的文本)。表盘应当可以渲染任何七字符字符串。字符串的宽度各不相同,具体取决于使用的字符。表盘应当调整文本大小以让自身适应复杂功能。如果文本超过七个字符,可能会被截断。
Icon 表示数据或数据源的单色图像。必须可以着色。建议为此字段使用矢量图。
Burn-in protection icon 在使用防烙印的设备上,用于启用要在微光模式下显示的图标的字段。在微光模式下,使用防烙印的设备上的表盘不应显示纯色像素块。Burn-in protection icon 字段对包含 icon 字段的任何复杂功能类型来说都是可选字段。Burn-in protection icon 字段不应包含任何纯色像素块。如果提供程序的标准图标不适合防烙印,Burn-in protection icon 字段应由提供程序提供。如果表盘在启用防烙印的设备的微光模式下渲染,它应使用 Burn-in protection icon 字段(如适用),而不是 icon 字段。
Short title 小型复杂功能的说明性字段。只有在与 Short text 字段组合时才有意义。此字段的最大长度不应超过七个字符(包括任何随时间而变的文本)。表盘应当可以渲染任何七字符字符串。字符串的宽度各不相同,具体取决于使用的字符。表盘应当调整文本大小以让自身适应复杂功能。如果文本超过七个字符,可能会被截断。
Long text 适用于基于文本的大型复杂功能的主要数据字段。
Long title 适用于基于文本的大型复杂功能的说明性字段。只有在与 Long text 组合时才有意义。
Value 数据的数字(浮点)表示形式。预计可以相对于 Min valueMax value 字段的边界描绘(但不需要介于这些边界之间)。
Min value 应在其中描绘 Value 的范围的下边界。只有在与 ValueMax value 组合时才有意义。
Max value 应在其中描绘 Value 的范围的上边界。只有在与 ValueMin value 组合时才有意义。
Small image 用于表示数据或数据源的小图片。可以是全色。不应填充整个表盘。
Large image 一种具有足够的分辨率来填充表盘的图片。可以是全色。

提供随时间变化的值

一些复杂功能需要显示与当前时间相关的值。示例包括当前日期、距离下一次会议的时间或者另一个时区中的时间。

此类数据的提供程序应当不需要每秒/分钟更新复杂功能以使这些值处于最新状态。不过,它们可以将值指定为与当前日期或时间相关。

提供程序可以在 ComplicationText 类中使用构建器创建这些随时间变化的值。

API 摘要

下面是 Complications API 的摘要。API 是穿戴式设备支持库的一部分;请参阅 Wear API 参考

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

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)