Wear Watchface

打造适用于 Wear OS by Google 谷歌智能手表的应用。

注意 ：自 2024 年 7 月 10 日起，表盘必须采用表盘格式，才能在预安装了 Wear OS 5 的设备上安装；自 2025 年 1 月 27 日起，在 Google Play 上发布的所有新表盘都必须采用表盘格式。

如需详细了解面向用户的变更，请参阅这篇帮助中心文章。

最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2024 年 9 月 18 日 1.2.1 - - 1.3.0-alpha04

声明依赖项

如需添加 Wear 的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 制品库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

dependencies {
    // Use to implement wear watchfaces
    implementation "androidx.wear.watchface:watchface:1.2.1"

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.2.1"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1"

    // Use to implement a watchface style and complication editor
    implementation "androidx.wear.watchface:watchface-editor:1.2.1"

    // Can use to render complications.
    // This library is optional and watchfaces may have custom implementation for rendering
    // complications.
    implementation "androidx.wear.watchface:watchface-complications-rendering:1.2.1"
}

Kotlin

dependencies {
    // Use to implement wear watchfaces
    implementation("androidx.wear.watchface:watchface:1.2.1")

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.2.1"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1"

    // Use to implement a watchface style and complication editor
    implementation("androidx.wear.watchface:watchface-editor:1.2.1")

    // Can use to render complications.
    // This library is optional and watchfaces may have custom implementation for rendering
    // complications.
    implementation "androidx.wear.watchface:watchface-complications-rendering:1.2.1"
}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 1.3

版本 1.3.0-alpha04

2024 年 9 月 18 日

发布了 androidx.wear.watchface:watchface-*:1.3.0-alpha04。版本 1.3.0-alpha04 包含这些提交内容。

新功能

  • 添加了对 UserStyleSettings 和 UserStyleOptions 中图标延迟加载的支持，这对加载表盘有助于提升性能。(Iaf43d)
  • 添加了一个选项，以便在系统配置发生变化（例如语言区域发生变化）时通过新的 Watchface.setUpdateScreenshotOnConfigurationChange 截取更新后的屏幕截图。默认情况下，此设置处于关闭状态。I765a1

bug 修复

  • 移除了手动说明对新平台 API 的访问权限，因为当将 R8 与 AGP 7.3 或更高版本（例如 R8 版本 3.3）搭配使用时，系统会通过 API 建模自动执行此操作；当使用 AGP 8.1 或更高版本（例如 D8 版本 8.1）时，系统会针对所有 build 自动执行此操作。建议不使用 AGP 的客户更新到 D8 8.1 或更高版本。如需了解详情，请参阅这篇文章。（Ia60e0、b/345472586）

版本 1.3.0-alpha03

2024 年 4 月 17 日

发布了 androidx.wear.watchface:watchface-*:1.3.0-alpha03。版本 1.3.0-alpha03 包含这些提交内容。

API 变更

  • 我们添加了 EditorSession#setOverrideComplications，用于在编辑时暂时设置底层表盘实例的 ComplicationData。如果复杂功能的更改频率较低，这种方式比通过 EditorSession#renderWatchFaceToBitmap 传入替换项更高效。(I19384)

bug 修复

  • 以前，selectComplicationDataForInstant 会针对任何时间轴调用 toApiComplicationData，这意味着后续的 === 引用等式测试始终会失败。这意味着复杂功能会在每一帧中重新加载，导致电池电量耗尽。 (717406)

版本 1.3.0-alpha02

2024 年 4 月 3 日

发布了 androidx.wear.watchface:watchface-*:1.3.0-alpha02。版本 1.3.0-alpha02 包含这些提交内容。

新功能

  • 由于等号运算符的开销较大，因此我们现在使用引用相等来比较 best 和 selectedData。(446b00)

API 变更

  • 我们为 GoalProgressComplicationData 添加了一个无回退的动态 API。(c33264)

版本 1.3.0-alpha01

2024 年 2 月 7 日

发布了 androidx.wear.watchface:watchface-*:1.3.0-alpha01。版本 1.3.0-alpha01 中包含这些提交内容。

新功能

  • WatchFaceServices 可以并发初始化，因此它们应是无状态的。为支持这一点，我们添加了 StatefulWatchFaceService，其中由 createExtra() 创建的用户定义的 extra 会传递到初始化期间调用的所有替换项。
  • GlesRenderer2 现在具有一个构造函数重载，可让您指定要依次使用 eglChooseConfig 尝试的属性列表。

API 变更

  • StatefulWatchFaceService 现在支持替换 getComplicationSlotInflationFactory，将由 createExtra() 创建的用户定义的 extra 传入其中。(I82d9f)
  • 某些表盘需要与其他初始化方法共享在 createUserStyleSchema 期间创建的辅助数据。由于没有更好的替代方案，开发者通常会使 WatchFaceServices 具有状态。这很危险，因为系统可能会同时创建多个实例，从而导致 bug。为了解决此问题，我们引入了 StatefulWatchFaceService 和 StatefulWatchFaceRuntimeService，其中用户定义的类型由 createExtra() 创建，并作为参数传递给各种创建方法。(If8a99)
  • 我们已将 getUserStyleFlavors 添加到 InteractiveWatchFaceClient，这对原始设备制造商 (OEM) 而言非常重要。(I0f5d8)
  • GlesRenderer2 现在具有一个构造函数重载，可让您指定要依次使用 eglChooseConfig 尝试的属性列表。例如，这样您就可以先尝试使用抗锯齿的配置，然后在需要时回退到不使用抗锯齿的配置。(I1ba74)
  • 从 Android U 开始，WearOS 将添加对 SystemDataSources.DATA_SOURCE_HEART_RATE 的支持。此复杂功能仅保证支持 SHORT_TEXT 复杂功能，但建议 ComplicationSlot 也接受 SMALL_IMAGE，因为 OEM 可能会选择提供指向其健康应用的快捷方式，而不是实时值。(I34223)
  • 我们添加了 METADATA_KEY_CONFIG_RESTORE_SUPPORTED，从 Android U 开始，该方法用于控制在系统使用 METADATA_KEY_DATA_SOURCE_CONFIG_ACTION 从复杂功能数据源的备份恢复时会发生什么。默认情况下，系统会假定复杂功能数据源服务支持备份任何配置数据，但如果不支持，则可以将元数据设置 METADATA_KEY_DATA_SOURCE_CONFIG_ACTION 添加为 false，这会将复杂功能显示槽标记为未配置。(I6c505)

版本 1.2

版本 1.2.1

2024 年 1 月 24 日

发布了 androidx.wear.watchface:watchface-*:1.2.1。版本 1.2.1 中包含这些提交内容。

bug 修复

  • 修复了 Samsung Galaxy Watch 4、5 和 6 上发生的崩溃问题。(43f0b0)

版本 1.2.0

2023 年 11 月 29 日

发布了 androidx.wear.watchface:watchface-*:1.2.0。版本 1.2.0 中包含这些提交内容。

自 1.1.0 以来的重要变更

  • 我们添加了对一些新复杂功能类型的支持，这些复杂功能类型可从 Android T 开始使用：
    • GoalProgressComplicationData，它与 RangedValueComplicationData 类似，不同之处在于它用于实现 min 隐式为 0，且值可以大于 targetValue 的目标。
    • WeightedElementsComplicationData，它由一组元素（粗细和颜色对）以及可选的文本/标题/图片组成。它们可能会显示为饼图，其中的颜色必须在上下文中有意义，因为复杂功能中通常没有空间可用于渲染标签。
  • 我们为 RangedValueComplicationData 添加了对可选 ColorRanges 的支持。通常，复杂功能将以表盘所选择的颜色进行渲染，但有时适合放置 ComplicationDataSource 来设置颜色，例如当颜色具有特定的语义含义时。例如，当以从红到蓝来代表温度时，就可以这样设置。
  • 现在，几乎所有类型的 ComplicationData 都支持 SmallImages。
  • 我们添加了 ComplicationDisplayPolicy，其中 DO_NOT_SHOW_WHEN_DEVICE_LOCKED 用于指示兼容的表盘在设备锁定时不显示复杂功能。
  • 从 Android T 开始，原始设备制造商 (OEM) 将能够通过 ComplicationRequest#isForSafeWatchFace 确定复杂功能请求是否来自提供方的清单中由 android.support.wearable.complications.SAFE_WATCH_FACES 元数据定义的列表所含的表盘。提供方需要有 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 权限才能接收 TargetWatchFaceSafety.UNKNOWN` 以外的任何数据。
  • UserStyleFlavors 已成为非实验性功能。

版本 1.2.0-rc01

2023 年 10 月 18 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-rc01。版本 1.2.0-rc01 中包含这些提交内容。

版本 1.2.0-beta02

2023 年 9 月 6 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-beta02。版本 1.2.0-beta02 中包含这些提交内容。

新功能

  • SuspendingComplicationDataSourceService#onDestroy 现已开放。请注意，系统已移除对默认天气复杂功能的支持。

API 变更

  • 还原了“为天气复杂功能公开新的数据源”。(I6f335)

版本 1.2.0-beta01

2023 年 8 月 23 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-beta01。版本 1.2.0-beta01 中包含这些提交内容。

新功能

  • 从 Android T 开始，WearOS 现在支持默认的天气系统复杂功能。

API 变更

  • 为复杂功能添加了天气默认系统回退。(Ia0994)
  • 此补丁会添加 WatchFaceRuntimeService 和 WatchFaceControlClient.createWatchFaceRuntimeControlClient 以及 guava 封装容器。这些 API 添加了对表盘运行时的支持，表盘运行时是一种特殊的表盘，可从其他软件包加载其定义。目前，WearOS 仅支持 Android 表盘格式的运行时。(I2799f)
  • 此补丁是对 aosp/2636578 的后续补丁，我们在其中重命名了 int 定义，因此依赖于 WatchFaceType、CanvasType、TapType 或 ComplicationsSlotBoundsType 的任何代码都无需更改。(I4098b)
  • 更新了 API 文件，以注释兼容性抑制。（I8e87a、b/287516207）
  • 此补丁公开了 WatchFaceTypes 中的 WatchFaceType 常量、CanvasTypes 中的 CanvasType 常量、TapTypes 中的 TapType 常量和 ComplicationsSlotBoundsType 中的 ComplicationsSlotBoundsType 常量。（I3b85a、b/288750666）
  • WatchFace.OverlayStyle 的使用率非常低，并且 OEM 对其支持不佳，因此我们将逐步弃用它，并计划日后将其移除。(I7344a)

版本 1.2.0-alpha09

2023 年 6 月 21 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-alpha09。版本 1.2.0-alpha09 中包含这些提交内容。

新功能

  • RangedValueComplicationData.Builder 现在接受 DynamicFloat，并且新的 DynamicComplicationText 可用作 ComplicationText 的子类，这两者都可以使用动态表达式以及在受支持的 Wear 4 设备上以 1 赫兹的频率更新的平台绑定。

API 变更

  • 为每日距离、每日卡路里和每日楼层数添加了动态类型。平台健康运行来源的键现在位于 PlatformHealthSources.Keys 下 (Ib7637)
  • 实现 PlatformDataProvider 以提供心率和每日步数。从公共 API 中移除了 SensorGateway 接口。(I55b84)
  • 将 StateEntryValue 重命名为 DynamicDataValue，并更新状态 API 以使用 DynamicDataKey。(If1c01)
  • 添加了用于访问应用推送状态的 AppDataKey；添加了用于访问平台数据的 PlatformDataKey；在 StateStore 中添加了命名空间支持。(I7985e)
  • DynamicTypeEvaluator 已移除 enable/disablePlatformSource 方法。调用方应负责更新。(I78c6d)
  • 允许限制绑定数据类型的大小。(Ie2966)

版本 1.2.0-alpha08

2023 年 4 月 19 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-alpha08。版本 1.2.0-alpha08 中包含这些提交内容。

新功能

  • 从 Android T 开始，具有特权 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 的复杂功能提供程序可以注册 androidx.wear.watchface.complications.datasource.SAFE_WATCH_FACE_SUPPORTED_TYPES 元数据，以替换安全表盘的 android.support.wearable.complications.SUPPORTED_TYPES。这意味着复杂功能提供程序可以选择向可信表盘和不可信表盘提供不同类型的复杂功能。

API 变更

  • 将 @Deprecated 类传播到属性 (I882d1、b/271441831)
  • 更改了 Enum.valueOf 的值形参名称 (Ia9b89)
  • 枚举 valueOf 抛出的更多异常 (I818fe)
  • 我们移除了 renderWatchFaceToSurface，改用基于 SurfaceControlViewHost 构建的 createRemoteWatchFaceView，该方法允许调用方嵌入表盘中的视图，该视图会在客户端调用 RemoteWatchFaceViewHost#renderWatchFace 时进行渲染。(Ib311d)
  • 我们已向 InteractiveWatchFaceClient、HeadlessWatchFaceClient 和 EditorSession 添加了 renderWatchFaceToSurface。通常，这比渲染到位图的性能更高。(Ieacad)
  • ObservableStateStore 已重命名为 StateStore。(Ieb0e2)
  • 添加了 DynamicTypeEvaluator.Builder（而非构造函数参数），以允许更多可选参数，包括 ObservableStateStore（现在默认为空存储区）。(I6f832)
  • 重构了 DynamicTypeEvaluator 中的参数顺序。(Ic1ba4)
  • 已向 DynamicTypeEvaluator.bind 方法添加了 Executor。(I346ab)
  • 我们在 BoundDynamicType 中添加了 startEvaluation 方法，以便在动态类型绑定后触发评估。(I19908)
  • 具有特权 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 的复杂功能提供程序可以注册 androidx.wear.watchface.complications.datasource.SAFE_WATCH_FACE_SUPPORTED_TYPES 元数据，以替换安全表盘的 android.support.wearable.complications.SUPPORTED_TYPES。(Id1c73)
  • 已将 CustomValueUserStyleSettings2 重命名为 LargeCustomValueUserStyleSettings。(Ic17ac)

bug 修复

  • 移除了 DynamicTypeValueReceiver#onPreUpdate。(I2dc35)

版本 1.2.0-alpha07

2023 年 2 月 22 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-alpha07。版本 1.2.0-alpha07 中包含这些提交内容。

新功能

  • 从 Android T 开始，原始设备制造商 (OEM) 将能够通过 ComplicationRequest#isForSafeWatchFace 确定复杂功能请求是否来自提供方的清单中由 android.support.wearable.complications.SAFE_WATCH_FACES 元数据定义的列表所含的表盘。提供方需要有 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 权限才能接收 TargetWatchFaceSafety.UNKNOWN 以外的任何数据。

  • 另外，从 Android T 开始，CustomValueUserStyleSetting2 也可供使用，最大可存储 12.5kb 的数据。之前 CustomValueUserStyleSetting 的上限为 1kb。尽管大小限制放宽了，但我们仍鼓励表盘开发者将数据控制在较小体量，因为在修改设置期间会通过蓝牙发送设置，而蓝牙带宽有限。

API 变更

  • 我们在 GlesRenderer 和 GlesRenderer2 中添加了可选参数 eglContextAttribList，以使您能设置传递给 EGL14.eglCreateContext 的 EGL14.EGL_CONTEXT_CLIENT_VERSION。(I2a83e)
  • 表盘库已迁移到 androidx.core.util.Consumer，而非 java.util.function.Consumer。(I273f5)
  • KT 属性访问器抛出的更多异常 (Iff9d9)
  • 我们添加了 InteractiveWatchFaceClient.isComplicationDisplayPolicySupported，以使客户端可以确定是否必须代表旧表盘模拟支持。(I24c89)
  • 我们决定 isForSafeWatchFace 应为三态 IntDef。(Ief2f7)
  • 对于 Android T，我们引入了适用于 OEM 的 ComplicationRequest.isForSafeWatchFace，它需要 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE。对于系统映像中的数据源，如果请求的表盘位于其清单中的数据源指定的安全表盘列表中，则会返回 true。(I0cbb6)
  • 对于 Android T，我们添加了 CustomValueUserStyleSetting2，它最多可存储 12.5kb 的数据。之前 CustomValueUserStyleSetting 的上限为 1kb。(I0b100)

版本 1.2.0-alpha06

2023 年 1 月 25 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-alpha06。版本 1.2.0-alpha06 中包含这些提交内容。

新功能

  • 我们正在努力增加对复杂功能平台绑定的支持，不过目前还不能投入使用，敬请期待！
  • 为新的复杂功能类型 GOAL_PROGRESS 和 WEIGHTED_ELEMENTS 添加了 XML ComplicationSlot 支持。

bug 修复

  • 修复了表盘编辑器未在三星设备上正确发布的漏洞。(3b5987)
  • 修复了以下 bug：在具有多个收藏夹的表盘之间切换时，复杂功能有时无法正确显示。(b38ece)
  • 修复了导致表盘崩溃的 perOptionScreenReaderNames 序列化 bug。(e9f466)

版本 1.2.0-alpha05

2022 年 12 月 7 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-alpha05。版本 1.2.0-alpha05 中包含这些提交内容。

新功能

  • 不久前，我们添加了对分层 UserStyleSettings 的支持，从 Android T 开始，一个层次结构中现在可以包含多个 ComplicationSlotsUserStyleSetting。只有一个 ComplicationSlotsUserStyleSetting 处于活动状态，具体取决于用户的样式选择。

  • 我们将通过添加 screenReaderName 字段来改进针对 ListOption 和 ComplicationSlotsOption 的屏幕阅读器支持。请注意，在 Android T 之前的版本中，该字段会被配套编辑器忽略。

API 变更

  • 我们向 ListOption 和 ComplicationSlotsOption 添加了一个新的可选 screenReaderName 字段，以供编辑器使用。在 Android T 之前的版本中，该字段会被设备上的配套编辑器忽略。(I75326)
  • 从 Android T 开始，一个样式层次结构中现在可以支持多个 ComplicationSlotsUserStyleSettings，前提是在任何情况下都最多只有一个处于活动状态。我们在 UserStyleSchema 中添加了实用函数 findComplicationSlotsOptionForUserStyle，以帮助查找处于活动状态的 ComplicationSlotsOption（如果有）。(Ic2b06)
  • RangedValuesTypes 已被提取到 RangedValueComplicationData 的伴生对象中并重命名为 TYPE_UNDEFINED、TYPE_RATING，还添加了新的 TYPE_PERCENTAGE。(I55d02)
  • 我们已将实验性 DynamicFloat 重命名为 FloatExpression，并将其标记为 @hide。(Idf4f1)
  • 添加了 @JvmDefaultWithCompatibility 注解 (I8f206)

版本 1.2.0-alpha04

2022 年 11 月 9 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-alpha04。版本 1.2.0-alpha04 中包含这些提交内容。

新功能

  • 针对 Android T，我们添加了对 GoalProgressComplicationData 和 WeightedElementsComplicationData 这两种新复杂功能类型的支持。
  • GoalProgressComplicationData 与 RangedValueComplicationData 类似，但前者的值允许超出目标值（RangedValueComplicationData 的值则被限制在 [最小 .. 最大] 的范围内），这会对视觉设计造成影响，可能不适用于所有表盘。
  • GoalProgressComplicationData 添加了对饼图和简单数据类似细分的支持。
  • 为 RangedValueComplicationData 添加了对 ColorRamps 的可选支持。
  • 对于 Android T，我们在 ComplicationData 中添加了 ComplicationPersistencePolicy 和 setCachePolicy，以便提供程序能够控制复杂功能是否持久保留（即是否在重新启动后进行缓存）。大多数复杂功能无需设置缓存控件，但这样做可以解决一些经常更新的复杂功能（例如运行状况数据复杂功能）存在过时数据的极端情况。我们还添加了 ComplicationDisplayPolicy，其中 DO_NOT_SHOW_WHEN_DEVICE_LOCKED 用于指示兼容的表盘在设备锁定时不显示复杂功能。(Ic9574)

API 变更

  • GoalProgressComplicationData、WeightedElementsComplicationData 和 ColorRamp 不再是实验性功能。(Ica9e2)
  • ComplicationPersistencePolicy 和 ComplicationDisplayPolicy 现在已正确标记为 T API。(I31d88)
  • 已废弃的 ComplicationSlotOverlay 构造函数现在具有 DeprecationLevel.WARNING，允许再次通过 Java 进行调用。(Ib308c)
  • 通过使用 @JvmDefaultWithCompatibility 为 ComplicationRequestListener、CanvasComplication、ComplicationTapFilter 以及 InteractiveWatchFaceClient 添加注解，我们解决了它们存在的一些 Java 兼容性问题 (Id94fc)
  • 移除了实验性 ProtoLayoutComplicationData 和 ListComplicationData。我们不太清楚相关的开发者故事，希望以后能提供。(I9df05)
  • 已将 ValueType 重新添加到 RangedValueComplicationData。WeightedElementsComplicationData 现在支持背景颜色。移除了 DiscreteRangedValueComplicationData，因为其功能是 WeightedElementsComplicationData 的子集。(I6446c)

bug 修复

  • 在等号和哈希代码中添加了 isForScreenShot。确保 onRenderParametersChanged 获取正确的 isForScreenshot 值 (I04a41)
  • 修复了无头客户端中 WatchFaceControlService 泄露的问题。(e90e00)

版本 1.2.0-alpha03

2022 年 10 月 5 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-alpha03。版本 1.2.0-alpha03 中包含这些提交内容。

新功能

  • 没有新功能，但我们修复了一些表盘编辑器 bug。

API 变更

  • 废弃了 UserStyleSchema.userStyleSettings，因为 rootUserStyleSettings 已成为非实验性功能 (Ie96e3)
  • 将 rootUserStyleSettings 移出了实验阶段 (I8d6b3)
  • 我们已将 WatchFaceColors 标记为实验性功能，因为并非所有系统都支持此功能 (I6d75d)
  • 在公共 API 中公开 DisconnectReasons，使其可与 IntDef 配合使用。(I791f8)

bug 修复

  • 如果 SysUI 终止，请关闭任何已打开的手表编辑器。如果 SysUI 终止，并且表盘编辑器未关闭，表盘可能会处于不一致状态，因为系统会依赖 SysUI 来保留任何用户样式更改。(ba762a）
  • 修复了 ComplicationDataSourceInfoRetriever 中的内存泄漏问题，即 kotlin 协程继续作为 gc 根并保留编辑器 activity。(33ee06)

版本 1.2.0-alpha02

2022 年 9 月 21 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-alpha02。版本 1.2.0-alpha02 中包含这些提交内容。

新功能

  • 有些表盘在 UserStyle 外部的配置会对其产生视觉影响（例如选择背景照片）。我们添加了 Renderer.sendPreviewImageNeedsUpdateRequest，以允许表盘请求更新后的预览图片。请注意，这需要完成相应的系统更新。

  • 此外，我们还为表盘添加了一个 API，用于向系统公开其颜色，以便系统据此选择调色板。请注意，这已成为对补丁的跟进中的实验性功能。

  • 现在，几乎所有类型的 ComplicationData 都支持 SmallImages。

API 变更

  • 壁纸管理器有时会与一个引擎分离并连接另一个引擎。我们添加了 DisconnectReason int def，并通过一个包含 DisconnectReason 的新方法扩展了 ClientDisconnectListener，从而允许监听器观察引擎分离。(I45cce)
  • 向 ComplicationSlotOverlay 构造函数添加了两个可选参数 nameResourceId 和 screenReaderResourceId (I157e8)
  • 为带有 PreviewImageUpdateRequestedListener 的新 getOrCreateInteractiveWatchFaceClient 重载添加了 guava 封装容器。(Ic31f0)
  • 我们添加了 Renderer.sendPreviewImageNeedsUpdateRequest，当表盘具有会影响外观的 UserStyleSchema 之外的状态时（例如，具有可选择背景图片的表盘），此方法会很有用。在客户端，我们将 PreviewImageUpdateRequestedListener 作为可选参数添加到了 getOrCreateInteractiveWatchFaceClient，以观察这些请求。(Iff44a)
  • 我们简化了用于公开 WatchFaceColors 的 API，现在 Renderer 中有一个名为 watchFaceColors 的简单属性，表盘可以设置此属性。必要时，此属性应随着样式的变化而更新。我们向 InteractiveWatchFaceClient 添加了 OnWatchFaceColorsListener，不再使用 WallpaperManager 观察颜色变化。(I490bc)
  • 我们添加了一个 WatchFaceColors 类，用于保存三种最显眼的表盘颜色；还向渲染程序添加了 watchfaceColors 和 notifyWatchFaceColorsChanged open 方法，这些方法可让系统通过 WallpaperManager.getWallpaperColors 获取表盘的颜色。(I3d611)
  • ShortTextComplicationData、RangedValueComplicationData、NoPermissionComplicationData（以及实验性的 DiscreteRangedValueComplicationData、GoalProgressComplicationData 和 WeightedElementsComplicationData）现在均支持 SmallImages。如果表盘选择渲染具有多种颜色的复杂功能，它现在可以选择使用多色 SmallImage，而以前则必须使用单色图片。(I257df)
  • 将 PreviewImageUpdateRequestedListener 重构为 Consumer<> (Ia875d)
  • 将自定义单一抽象方法 (SAM) 类型 OnWatchfaceColorsListener 替换为通用 Java SAM 类型（使用方）(I0c489)
  • 我们废弃了未指定 PreviewImageUpdateRequestedListener 的旧版 getOrCreateInteractiveWatchFaceClient 和 listenableGetOrCreateInteractiveWatchFaceClient 方法。(Iec502)

bug 修复

  • DisconnectReason.BINDER_DIED 已重命名为 DisconnectReason.ENGINE_DIED。(I4eb0e)

版本 1.2.0-alpha01

2022 年 8 月 10 日

发布了 androidx.wear.watchface:watchface-*:1.2.0-alpha01。版本 1.2.0-alpha01 中包含这些提交内容。

新功能

  • 我们添加了对各种新的复杂功能格式的实验性支持。该领域正处于积极开发中；这些新格式随时可能发生更改，恕不另行通知；目前，CanvasComplicationDrawable 不提供渲染程序支持。
  • 此外，我们还为复杂功能显示槽添加了可选的外边距，让小型复杂功能更易于点按。

API 变更

  • 实验性 BoundingArc 类现已不可变。(If624a)
  • 小型复杂功能可能难以点按。为帮助缓解此问题，我们引入了对外边距的支持，从而在不影响渲染的情况下增大可点按区域面积。除非有明确指定（在代码中或通过 XML），否则 ComplciationSlots 的外边距大小为 0。(I14089)
  • 更改了 getComplicationSlotInflationFactory(CurrentUserStyleRepository) 签名，以返回非 null 的工厂实例。之前返回 null 是错误的，因此这项更改使 API 协定更加明确了。(I0fcc0)
  • 我们在 WatchFaceService.getComplicationSlotInflationFactory 方法中添加了 currentUserStyleRepository 参数，以便与 createComplicationSlotsManager 保持一致。(I2ddd2)
  • UserStyleFlavors 已成为非实验性功能。(I69cdc)
  • 我们从 RangedValueComplicationData 中移除了实验性的 ValueType，改为引入了实验性的 DiscreteRangedValueComplicationData，它与 RangedValueComplicationData 类似，不同之处在于整数范围和值。此外，我们还引入了实验性的 GoalProgressComplicationData，它与 RangedValueComplicationData 类似，不同之处在于它用于实现 min 隐式为 0，且值可以大于 targetValue 的目标。请注意，对于所有 RangedValue 变体，monochromeImage、text 或 title 中必须至少有一项是明确指定的。(I9590c)
  • 我们从 ComplicationSlotState 中移除了 boundsWithMargins，因为系统软件没有对应的用例。(I42e26)
  • 我们添加了对 WeightedElementsComplicationData 的实验性支持，它由一组元素（粗细和颜色对）以及可选的文本/标题/图片组成。它们可能会显示为饼图，其中的颜色必须在上下文中有意义，因为复杂功能中通常没有空间可用于渲染标签。(I87eea)
  • 现在，借助可由 RangedValueComplicationData 和 GoalProgressComplicationData 选择性使用的实验性 ColorRamps，您可以指定一个不超过 7 种颜色的序列和一个标志，该标志用于指明是否应对颜色进行流畅的补间动画处理，或是否应渲染相同大小的单色色阶。(I9f5bf)
  • RangedValueComplicationData.drawSegmented 已更改为 valueType，这是一个具有相应 ValueType IntDef 的 int，它会为范围值提供语义含义，并且可供复杂功能渲染程序用于对样式施加影响。(I0616b)
  • 我们为 RangedValueComplicationData 添加了对可选 ColorRanges 的实验性支持。通常，复杂功能将以表盘所选择的颜色进行渲染，但有时适合放置 ComplicationDataSource 来设置颜色，例如当颜色具有特定的语义含义时。例如，当以从红到蓝来代表温度时，就可以这样设置。(I5153a)
  • 我们在 RangedValueComplicationData 中添加了实验性的 drawSegmented 提示。此信号会指示渲染程序使用线段来绘制范围值指示器，其中 1 个线段 = 1 个单位。(I7d7c1)

bug 修复

  • 我们添加了相对于预定义屏幕坐标系定义 ComplicationSlotBounds 的功能。(I0985d)

版本 1.1

版本 1.1.1

2022 年 8 月 10 日

发布了 androidx.wear.watchface:watchface-*:1.1.1。版本 1.1.1 中包含这些提交内容。

  • 这是一个问题修复版本，强烈建议 1.1.0 版本的用户进行升级。

bug 修复

  • 表盘初始化是异步进行的，系统如果在表盘就绪之前收到某项复杂功能，就会将其加入 pendingInitialComplications 列表，待时机成熟后再应用。遗憾的是，以前 pendingInitialComplications 应用得太快了，以至于表盘初始化期间存在这样一个时间段：在此期间，系统仍会将复杂功能置于 pendingInitialComplications 上并予以忽略。此问题现已修复。此外，该补丁还修复了以下 bug：ComplicationRenderer 错误地尝试异步加载占位符；此操作会失败，并会导致复杂功能图形一直无法更新。最后，该补丁修复了一项理论性 bug（希望这项 bug 没有实际引发任何后果），即需要合并多个 pendingInitialComplications 的 bug。(0d03ba3)

  • 修复了 InteractiveInstanceManager 中可能出现的死锁问题，即 getExistingInstanceOrSetPendingWallpaperInteractiveWatchFaceInstance 保持锁定的时间过长，超出了必要的限度。通常，我们希望 engine.setUserStyle 能够快速运行，但如果出于某种原因无法快速运行，最终就可能会出现死锁/ANR 问题。该补丁将不必要的工作从锁定中移除，消除了出现死锁问题的可能性。(5a2adca)

  • 修复了导致保留 WatchFaceService 的几个问题。WakeLock 有时可能会保留 WatchFaceService，添加 release() 调用即可修复此问题。此外，StateFlows 也可能会保留 WatchFaceService，取消底层 CoroutineScopes 即可修复此问题。(fd48138)

  • 为 awaitDeferredWatchFace* 添加了超时并修复了 watchfaceOverlayStyle NullPointerException。正常情况下，这不应超时，CPU 负载较高的全新安装场景和 DirectBoot 场景也不例外。此外，我们还修复了在 close() 之后调用 getWatchfaceOverlayStyle 时出现 NPE 的问题。(a4c3a5a)

版本 1.1.0

2022 年 6 月 15 日

发布了 androidx.wear.watchface:watchface-*:1.1.0。版本 1.1.0 中包含这些提交内容。

自 1.0.0 以来的重要变更

改进的编辑功能：

  • 我们添加了对分层架构的支持，从而允许编辑器界面对样式层次结构进行标记。您现在可以指定单独的图标，供表盘和配套编辑器使用。
  • 可选择启用多个表盘实例，每个实例在所有 API Surface 之间有一个唯一 ID。
  • 您现在可以为 ComplicationSlots 指定能让人看懂的名称，以供在编辑器中使用。
  • 对样式“变种”提供实验性支持，这些精选样式将在配套编辑器中可见。
  • 加载表盘的两个实例时，表盘实例现在可以共享资源，从而节省内存
  • 现在，在表盘编辑器中选择复杂功能时，系统会预先选择当前的提供程序。

经过改进的复杂功能：

  • 您现在可以为主要数据源和次要数据源指定 ComplicationType，从而为开发者提供更灵活的“开箱即用”体验。
  • 我们添加了 ComplicationDataTimeline，用于为表盘提供一系列有时间限制的数据，这些数据可自动缓存和更新。例如，今天不同时间的天气预报或多个即将发生的日历活动。
  • 复杂功能提供程序的 ComponentName 是 ComplicationData 的一部分。
  • 系统现在会缓存复杂功能，以便在切换表盘时提供更好的体验。

其他变更：

  • 现在，您可以使用 XML 定义 UserStyleSchema 和 ComplicationSlots。这有助于简化表盘构造，并允许系统更快地进行元数据查询。
  • 表盘现在可以影响用于渲染系统叠加层的颜色。

版本 1.1.0-rc01

2022 年 5 月 18 日

发布了 androidx.wear.watchface:watchface-*:1.1.0-rc01。版本 1.1.0-rc01 中包含这些提交内容。

新功能

  • 我们对表盘 XML 支持做了一些易用性调整，让您能够更轻松地指定 ComplicationSlotBounds 和支持引用。继续进行边缘复杂功能 BoundingArc 的实验，使其连接持续到 drawHighlight，但不建议在此时间使用。

API 变更

  • 我们添加了 drawHighlight 的实验性过载，它接受 BoundingArc 参数。(I705f8)
  • 表盘 XML 现在支持资源引用，使您能够在 XML 和代码中使用相同的常量。(I3ef61)
  • 添加了以 center_x, center_y, size_x, size_y 格式定义 ComplicationSlotBounds 的功能。现在，借助资源引用也可以使用不同的单位（例如 dp）。(Iace98)

bug 修复

  • 修复了在错误上下文中运行任务的 runBlockingWithTracing。(4f595fe)
  • 使 BaseEditorSession.close 变得同步。BaseEditorSession.close 的异步问题在于，我们释放 ComplicationDataSourceInfoRetriever 的时间太晚，导致 Logcat 中出现警告垃圾信息。这可能没什么损害，但 Logcat 垃圾信息会分散注意力，应予以避免。(35a5308)

版本 1.1.0-beta02

2022 年 5 月 11 日

发布了 androidx.wear.watchface:watchface-*:1.1.0-beta02。版本 1.1.0-beta02 中包含这些提交内容。

新功能

  • 我们添加了对新的 ComplicationData 类型的实验性支持，这些类型尚不可用，敬请关注后续资讯。

API 变更

  • 我们添加了实验性的类 BoundingArc，用于说明边缘复杂功能显示槽的几何图形。此类已添加到 ComplicationSlot，并会被传送到 ComplicationSlotState 和 WatchFaceMetadataClient。(I61a40)
  • 我们添加了在 UserStyleSetting XML 中继承设置的功能。这样一来，您就可以降低详细程度，并在表盘之间共享一个设置。(Ief841)
  • 我们添加了两种新的实验性 ComplicationData 类型：ListComplicationData 和 ProtoLayoutComplicationData。目前，这两种类型都不支持渲染，如果这些类型添加到 ComplicationDataSource's 清单中，WearOS 目前无法识别。(I1811c)

bug 修复

  • 修复了 TimeLineEntry 类型的序列化问题。我们不会对 TimeLineEntry 类型进行序列化，这意味着，当访问不存在的必填字段时，类型为 NoData 的缓存 TimeLineEntries 会被错误解读为其父级复杂功能类型会导致 NPE。(55ffdf5)
  • 修复了 setComplicationData 丢弃时间轴字段的 bug (fb392f5)
  • 修复了在极个别情况下 runBlockingWithTracing 会导致 NPE 的 bug (12ca62e)
  • 修复了接收复杂功能时我们有时会收到 ClassNotFoundException: android.support.wearable.complications.ComplicationText 的 bug。(217942d9)
  • 修复了 GlesRenderer.backgroundThreadInitInternal 中仅在调用 EGL14.eglCreateContext 时才调用 onBackgroundThreadGlContextCreated 的 bug。修复了 verticalFlip 导致屏幕截图中出现视觉小故障的另一个 bug。(c674ad2)
  • 修复了 WatchFaceService XML 版本检查从错误的软件包加载的问题。(dfa06f3)
  • 占位符传输格式现在使用内部软件包。我们不希望占位符破坏可能使用隐藏的内部 a.s.w.c.ComplicationData 的现有表盘。以前，NoDataComplication 数据的传输格式会将占位符存储在常规字段中（问题在于，旧的表盘会渲染出并非预期的占位符字符串），现在我们会使用内部软件包来完全隔离。(d5e7bd2)

版本 1.1.0-beta01

2022 年 4 月 20 日

发布了 androidx.wear.watchface:watchface-*:1.1.0-beta01。版本 1.1.0-beta01 中包含这些提交内容。

API 变更

  • 现在 WatchFaceMetadataClient 方法（getUserStyleSchema、getComplicationSlotMetadataMap、getUserStyleFlavors）和 HeadlessWatchFaceClient.getUserStyleFlavors 抛出未检查的 RuntimeException，而不是 WatchFaceException。(I0718a)
  • WatchFaceMetadataClient.WatchFaceException 已经放到类外面，从而能够被重复使用。(I4e869)

bug 修复

  • 发送部分 ComplicationSlotBounds 时，WatchFaceMetadataClient 将不会再崩溃。(Iaafd)

版本 1.1.0-alpha05

2022 年 4 月 6 日

发布了 androidx.wear.watchface:watchface-*:1.1.0-alpha05。版本 1.1.0-alpha05 中包含这些提交内容。

新功能

  • 您现在可以通过检查 ComplicationData.dataSource 来确定哪个数据源发送了 ComplicationData，一些表盘主题可能会使用此方法来自定义复杂功能显示方式。(I44a73)

API 变更

  • 废弃了 Renderer.CanvasRenderer 和 Renderer.GlesRenderer，取而代之的是 Renderer.CanvasRenderer2 和 Renderer.GlesRenderer2，后者支持传递给呈现方法的 SharedAssets。为了 Java 互操作性，我们引入了 ListenableCanvasRenderer2 和 ListenableGlesRenderer2。(I31ffa)
  • 添加了定义变种的 @WatchFaceFlavorsExperimental 功能 - 预配置的样式表盘主题列表 (I04dd0)
  • Renderer.sharedAssets 现在是 StateFlow，我们移除了未使用的 Renderer.SharedAssetsFactory (I12ac5)
  • 不再废弃 UserStyleSchema.userStyleSettings (Iba7e3)
  • 添加了 HeadlessWatchFaceClient.getUserStyleSchemaDigestHash，它可让 HeadlessWatchFaceClient 避免在计算摘要哈希之前通过 AIDL 传递架构时产生相对较低的开销。(I33597)
  • 将 isUserStyleSchemaStatic 添加到了 WatchFaceMetadataClient，当且仅当可以确信 UserStyleSchema 不会发生更改时（除非更新了表盘 APK），该参数的值才为 true。(I45a3f)
  • 将 getDigestHash 添加到了 UserStyleSchema，以计算架构的摘要哈希。这可用于高效地确定 UserStyleSchema 是否已更改。(I2063d)
  • METADATA_KEY_DATA_SOURCE_DEFAULT_CONFIGURATION_SUPPORTED 已重命名为 METADATA_KEY_DATA_SOURCE_DEFAULT_CONFIG_SUPPORTED (I9ba5d)
  • UserStyleSetting.OnWatchEditorData 已重命名为 UserStyleSetting.WatchFaceEditorData，其中包含仅供表盘编辑器使用的数据。(If3afb)

版本 1.1.0-alpha04

2022 年 3 月 9 日

发布了 androidx.wear.watchface:watchface-*:1.1.0-alpha04。版本 1.1.0-alpha04 中包含这些提交内容。

API 变更

  • 由于有时可能没有最新的 ComplicationData（例如，缓存的 ComplicationData 已过期），因此我们使用可选的占位符 ComplicationData 扩展了 NoDataComplication 并添加了 ComplicationText.PLACEHOLDER、MonochromaticImage.PLACEHOLDER、SmallImage.PLACEHOLDER 和 PhotoImage.PLACEHOLDER 占位符，但这些占位符只能在 NoDataComplicationData 占位符的上下文中使用。如果选择了这些占位符，建议使用灰色方框/弧形呈现它们。(I6285d)
  • 添加了 ComplicationData.getNextChangeInstant，它会告诉您继引用 Instant 之后，下一个会出现复杂功能中任何字段可能发生变化的 Instant。它在内部用于排定复杂功能的更新时间范围。例如，如果表盘主题通常每分钟更新一次，那么设置秒表复杂功能会导致它每秒更新一次。(I7ceb2)
  • EditorSession.watchFaceId 现在可用于所有 API 级别。此外，它的值现在将始终与 WatchState.watchFaceInstanceId 一致。(I323b9)
  • 根本问题已在框架中修复，不再需要 getPendingIntentForTouchEvent API，因此移除了所有相关 API。即使用户最近按了主屏幕按钮，表盘也无需为触发 PendingIntents 而执行任何特殊操作。(I1f2e8)
  • 添加了 RendererParameters.isForScreenShot，如果渲染针对的是屏幕截图，该参数的值将为 true。一些包含动画的表盘主题需获知此信息，才能进行调整以确保呈现最佳效果。(I96d99)
  • 将 WatchFaceExceptionReason 添加到了 WatchFaceException，以针对错误情况提供背景信息。(I01d15)
  • 移除了 ComplicationDataSourceService.onImmediateComplicationRequest，改为添加了 ComplicationRequest.immediateResponseRequired，以指示提供程序需要快速响应（最好在 100 毫秒以内响应）。请注意，此功能受特许的 com.google.android.wearable.permission.USE_IMMEDIATE_COMPLICATION_UPDATE 权限保护。(Ie6b23)
  • 更新了 core 和 appcompat 中的可为 null 性，以匹配 Tiramisu DP2 (I0cbb7)

bug 修复

  • 现在，如果架构验证失败，表盘主题应用会崩溃并出现异常 (Ia400f)

版本 1.1.0-alpha03

2022 年 2 月 9 日

发布了 androidx.wear.watchface:watchface-*:1.1.0-alpha03。版本 1.1.0-alpha03 中包含这些提交内容。

API 变更

  • 添加了对层级式架构的实验性支持。我们为 androidx.wear.watchface.style.UserStyleSetting.Option 添加了一个新属性，即 childSettings，该属性最初仅可通过 ListOption 使用。这样一来，就可以描述样式的层次结构以供编辑器界面使用，而底层 UserStyle 则保持不变，仍为 Map<String, ByteArray>。(Iaf6f4)
  • 添加了 WatchFace.OverlayStyle，以便表盘对系统状态叠加层的呈现进行配置。(I8520d)
  • 为 CanvasRenderer 引入了 clearWithBackgroundTintBeforeRenderingHighlightLayer，这是一个新的可选构造函数参数（默认值为 false），如果该参数设为 true，画布中的内容将被清除并显示背景色调颜色。(Ie01e5)
  • 添加了 androidx.watchface.complications.datasource.DEFAULT_CONFIGURATION_SUPPORTED 元数据键，以便复杂功能数据源指明它们无需任何配置即可提供默认值 (Icc0d4)
  • 在修改表盘时，使表盘同时存在交互式实例和无头实例的情况很常见。为了帮助节省内存，我们引入了 Renderer.SharedAssets，以便表盘渲染程序在实例之间共享不可变数据（如纹理和着色器）。废弃了 GlesRenderer.setEglConfig 和 GlesRenderer.setEglDisplay，我们从未打算使其可设置，因为这样做会导致出现未定义的行为。(I0d9e7)
  • 在 androidx.wear.watchface.client.ComplicationSlotState 中为 ComplicationSlot.Builder 和相应的 getter 添加了 setNameResourceId 和 setScreenReaderNameResourceId（引用字符串资源）。这样一来，系统便可以提取 ComplicationSlot 的名称，以便在编辑器和屏幕阅读器中使用。(If6c6a)
  • WatchfaceMetadataClient.getUserStyleSchema 和 getComplicationSlotMetadataMap 现在会抛出 WatchFaceException，而非 RemoteException。(I86f11)
  • ComplicationDataSourceService 中的 onSynchronousComplicationRequest 和相关函数已重命名为 onImmediateComplicationRequest 等…(I87ba0)
  • 表盘编辑器的屏幕空间比配套编辑器的屏幕空间小得多，因此支持在表盘编辑器上使用不同的图标是合理的。此补丁会将 OnWatchEditorData（当前仅包含图标）添加到所有 UserStyleSetting，并会在适当情况下添加到其 Option 类。(If1886)
  • 为 ListenableGlesRenderer 的构造函数添加了 @JvmOverloads，以实现更好的 Java 互操作性。(I2974a)

bug 修复

  • ListenableGlesRenderer 的构造函数现已正确标记为 @Throws(GlesException::class)，因此现在可以在 Java 中扩展此类。(Iac6d0)
  • 修复了无法正确处理 PhotoImageComplicationData tapAction 的 bug (I1cc30)

版本 1.1.0-alpha02

2022 年 1 月 12 日

发布了 androidx.wear.watchface:watchface-*:1.1.0-alpha02。版本 1.1.0-alpha02 中包含这些提交内容。

新功能

  • 为便于调试和测试，ComplicationData 和相关子类现在替换了哈希代码、equals 方法和 toString 方法，使其更易于使用。

API 变更

  • WatchfaceMetadataClient 方法会再次视情况抛出 RemoteExceptions，从而使客户端代码可以更轻松地捕获表盘中的错误。(I78785)
  • ComplicationData 和子类现在具有哈希代码、equals 方法和 toString 方法。(I24bc6)

版本 1.1.0-alpha01

2021 年 12 月 15 日

发布了 androidx.wear.watchface:watchface-*:1.1.0-alpha01。版本 1.1.0-alpha01 中包含这些提交内容。

新功能

  • 现在，您可以使用 XML 定义 UserStyleSchema 和 ComplicationSlots。这有助于简化表盘构造。此外，WatchFaceMetadataClient 查询会更快，因为它不需要绑定到服务，即可获取元数据。WatchFaceMetadataClient 和 ListenableWatchFaceMetadataClient 不再是实验性功能，而是将成为稳定 API 的一部分。系统将能够自行选择是否支持一个表盘的多个实例，其中每个实例都有由用户定义的不同样式选项。这些实例将显示在表盘选择器中。如需选择启用此功能，表盘的清单中必须包含以下元数据标记。

        <meta-data
        android:name="androidx.wear.watchface.MULTIPLE_INSTANCES_ALLOWED"
        android:value="true" />

  • 有些表盘拥有未捕获到 UserStyle 中的状态，为了支持此情况及多个实例的情况，现在可以通过 WatchState.watchFaceInstanceId 获取表盘的实例 ID。

  • 系统目前会缓存 ComplicationData，以便复杂功能在加载时立即显示。有时，ComplicationData 会由系统缓存在内存中，有时则由表盘库进行序列化处理。进行序列化处理后，所有关联的 tapAction 都会丢失。如果发生这种情况，ComplicationData.tapActionLostDueToSerialization 将返回 true，并且表盘应以不同方式呈现复杂功能（例如灰显或半透明显示），以指明无法点按复杂功能。系统将尽快发送更新后的 ComplicationData，其中会包含 tapAction。

  • 某些 ComplicationData 不应长时间缓存，为了支持这一点，我们添加了更通用的功能 ComplicationDataTimeline。该功能可用于提供一系列有时间限制的 ComplicationData，以便发送到可自动缓存和更新的表盘。例如，今天不同时间的天气预报或多个即将到来的日历活动。ComplicationRequestListener 已扩展，其中添加了一个新方法 onComplicationDataTimeline，该方法可用于返回这些数据。

  • DefaultComplicationDataSourcePolicy 已扩展，以便您为主要数据源和辅助数据源指定 ComplicationType。

  • 我们添加了对同步复杂功能提供程序的支持，在此类提供程序中，复杂功能的更新频率高于正常频率，当表盘可见且处于非氛围模式时，最高更新频率可达到每秒一次。注意：由于内存压力问题，同步复杂功能提供程序的使用可能会受到限制。

  • 可能会还原对 PendingIntentTapListener 所做的更改，因为我们已解决框架中的底层问题（在用户按下主屏幕按钮后，表盘在 5 秒内无法启动 activity）。

API 变更

  • ComplicationData.isCached 已更改为 tapActionLostDueToSerialization，在确定是否应以不同方式呈现复杂功能显示槽以指明无法点按该显示槽时，后者更为有用。(I6de2f)
  • 为 wear-complication-data-source 添加了 ComplicationDataTimeline。该功能可用于提供一系列有时间限制的 ComplicationData，以便发送到可自动缓存和更新的表盘。例如，今天不同时间的天气预报或多个即将到来的日历活动。ComplicationRequestListener 已扩展，其中添加了一个新方法 onComplicationDataTimeline，该方法可用于返回这些数据。此外，新增了一个用于挂起数据源服务的 Kotlin 封装容器 SuspendingTimelineComplicationDataSourceService。(Idecdc)
  • 添加了 PendingIntentTapListener 和 WatchFaceControlClient.getPendingIntentForTouchEvent。这可以帮助需要启动 intent 来响应点按操作的表盘解决以下问题：在用户按下主屏幕按钮后，框架会阻止在 5 秒内启动新的 activity。(I98074)
  • 引入了基于表盘的 ComplicationData 缓存。这样做的目的是，允许表盘在加载时显示最新的已知复杂功能数据值，直到系统有机会对其进行更新为止。此外，新增了一个面向原始设备制造商 (OEM) 的 API 方法 WatchFaceControlClient.hasComplicationCache。这可能会影响关于向表盘发送复杂功能的系统策略。此外，ComplicationData 具有 isCached 属性，我们建议以不同方式呈现缓存的复杂功能，因为 tapAction 无法缓存，并且在缓存的复杂功能中将为 null。(I404b0)
  • 现在，可以通过 WatchState.watchFaceInstanceId 获取表盘的实例 ID。大多数表盘不需要使用此 ID，但如果有基于表盘的状态未存储在架构中，那么此 ID 便是用于识别表盘实例的键。为了帮助支持这一点，您现在可以在调用 WatchFaceControlClient.createHeadlessWatchFaceClient 时提供一个 ID。(I1ff98)
  • 扩展了 DefaultComplicationDataSourcePolicy，现在它能够为主要提供程序、辅助提供程序和后备系统提供程序设置默认的 ComplicationTypes。ComplicationSlot.defaultDataSourceType 现已废弃。(If0ce3)
  • ComplicationSlot.configExtras 现在是可变的，可以在调用 EditorSession.openComplicationDataSourceChooser() 之前进行更新。(I6f852)
  • 添加了 WatchFace.setComplicationDeniedDialogIntent 和 setComplicationRationaleDialogIntent。启动这些 intent 是为了在请求复杂功能权限之前显示一个理由对话框，以及在权限已被拒的情况下，在尝试修改复杂功能时显示另一个对话框来解释为什么需要相应的复杂功能权限（提供程序选择器将无法打开，因此需要显示该对话框）。(I3a29c)
  • 现在，您可以使用 XML 定义 UserStyleSchema 和 ComplicationSlots。这有助于简化表盘构造，并提高 WatchFaceMetadataClient 查询的速度，因为它们不需要绑定到服务，即可获取元数据。(I85bfa)
  • 添加了 InteractiveWatchFaceClient.supportsPendingIntentForTouchEvent，以便客户端可以确定表盘是否支持 getPendingIntentForTouchEvent。(I0b917)
  • WatchFaceMetadataClient 和 ListenableWatchFaceMetadataClient 不再是实验性功能。它们可用于高效获取表盘元数据，在可能的情况下，甚至无需打开表盘的 binder。(Ibb827)
  • 添加了对同步复杂功能提供程序的支持，在此类提供程序中，复杂功能的更新频率高于正常频率，当表盘可见且处于非氛围模式时，最高更新频率可达到每秒一次。要使用此类提供程序，必须在其清单中添加新的 androidx.wear.watchface.complications.data.source.SYNCHRONOUS_UPDATE_PERIOD_SECONDS 元数据标记，并替换 onSynchronousComplicationRequest。您可能还需要替换 onStartSynchronousComplicationRequests 和 onStopInteractiveComplicationRequests，以便在复杂功能进入和退出互动模式时收到通知，具体取决于数据源的性质。(I8fe9d)

1.0 版

版本 1.0.1

2022 年 2 月 9 日

发布了 androidx.wear.watchface:watchface-*:1.0.1。版本 1.0.1 中包含这些提交内容。

bug 修复

  • 修复了无法正确处理 PhotoImageComplicationData tapAction 的 bug (I1cc30)

版本 1.0.0

2021 年 12 月 1 日

发布了 androidx.wear.watchface:watchface-*:1.0.0。版本 1.0.0 中包含这些提交内容。

1.0.0 的主要功能

androidx.wear.watchface 软件包是开发 WearOS 表盘的新推荐库。与旧版穿戴式设备支持库相比，该库纳入了诸多新功能。

  • 该库可直接支持用户样式设置，例如更改调色板、手表指针的样式、时点的外观等（详见 androidx.wear.watchface.style）。现在，使用 androidx.wear.watchface.editor 开发表盘编辑器更容易，并且无需编写任何额外代码即可通过系统配套应用编辑表盘。
  • 已纳入最佳实践。该库会自动为复杂功能生成屏幕阅读器内容标签（您也可以添加自己的标签），而且在电池电量不足且未在充电时，帧速率会自动降低，以延长电池续航时间。
  • 开发表盘主题需要的代码较少，尤其是对于将大量样板文件移至库中的复杂功能。

bug 修复

  • 修复了 EditorSession.userStyle.compareAndSet (I6f676)
  • 修复了非常短的表盘延迟 (Iffb97)
  • 在界面线程上调度 InteractiveWatchFaceImpl.onDestroy (I83340)
  • 修复了与广播接收器相关的多个问题 (I7d25f)

版本 1.0.0-rc01

2021 年 11 月 3 日

发布了 androidx.wear.watchface:watchface-*:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

bug 修复

  • 修复了因流迁移而损坏的 dump()（由 adb shell dumpsys 调用）。(087cf9e)

  • 确保 writeDirectBootPrefs 的排序正确。我们希望 writeDirectBootPrefs 始终在 initStyleAndComplications 后面运行，否则会出现延迟界面线程 init 的风险。(37650ac)

  • 确保已调用 Renderer.onDestroy。在已创建渲染程序但尚未完成 WF init 且已调用 Engine.onDestroy 的场景中，我们需要调用 Renderer.onDestroy。 (f9952dc)

  • 优化/修复了 isBatteryLowAndNotCharging。此补丁会提前移动 isBatteryLowAndNotCharging 的初始设置，这意味着它可以与 createWatchFace 并行完成。此外，我们现在还会监听 ACTION_POWER_DISCONNECTED。(ddffd80

  • 关闭后，InteractiveWatchFaceClientImpl.isConnectionAlive 为 false (ab9774e)

版本 1.0.0-beta01

2021 年 10 月 27 日

发布了 androidx.wear.watchface:watchface-*:1.0.0-beta01。版本 1.0.0-beta01 中包含这些提交内容。

版本 1.0.0-alpha24

2021 年 10 月 13 日

发布了 androidx.wear.watchface:watchface-*:1.0.0-alpha24。版本 1.0.0-alpha24 中包含这些提交内容。

API 变更

  • 软件包 androidx.wear.watchface.complications 中的类已被移入新的 wear:watchface:watchface-complications 项目。请注意，这意味着您无法添加此库以及之前的所有 Alpha 版 wear:watchface:watchface-complications-data，而是会在添加时收到类重复的出错提示。(I97195)
  • Renderer.dump 已重命名为 Renderer.onDump，且带有 @UiThread 注解。(I44845)
  • InteractiveWatchFaceClient.addWatchFaceReadyListener 已重命名为 addOnWatchFaceReadyListener，且 removeWatchFaceReadyListener 已重命名为 removeOnWatchFaceReadyListener。(I48fea)
  • EditorSession中的 getComplicationsPreviewData 和 getComplicationsDataSourceInfo 不再是挂起函数，而是初始值为 null 的 StateFlow<> 属性。移除了 ListenableEditorSession 中的 getListenableComplicationPreviewData 和 getListenableComplicationsProviderInfo，取而代之的是基类中的新 StateFlow<> 对象。如果您需要监听 Java 代码中的更改，不妨使用 androidx.lifecycle.FlowLiveDataConversions.asLiveData 将其转换为 LiveData<>。(Ic5483)

版本 1.0.0-alpha23

2021 年 9 月 29 日

发布了 androidx.wear.watchface:watchface-*:1.0.0-alpha23。版本 1.0.0-alpha23 中包含这些提交内容。

新功能

watchface 库现在是一个单独的库组，因此这些库已移到新位置，您需要按如下所示更新 Gradle 导入：

旧版本 新版本
androidx.wear:wear-complications-data androidx.wear.watchface:watchface-complications-data
androidx.wear:wear-complications-data-source androidx.wear.watchface:watchface-complications-data-source
androidx.wear:wear-watchface androidx.wear.watchface:watchface
androidx.wear:wear-watchface-complications-rendering androidx.wear.watchface:watchface-complications-rendering
androidx.wear:wear-watchface-client androidx.wear.watchface:watchface-client
androidx.wear:wear-watchface-client-guava androidx.wear.watchface:watchface-client-guava
androidx.wear:wear-watchface-data androidx.wear.watchface:watchface-data
androidx.wear:wear-watchface-editor androidx.wear.watchface:watchface-editor
androidx.wear:wear-watchface-editor-guava androidx.wear.watchface:watchface-editor-guava
androidx.wear:wear-watchface-guava androidx.wear.watchface:watchface-guava
androidx.wear:wear-watchface-style androidx.wear.watchface:watchface-style

API 变更

  • 将单独的 androidx.wear Watchface 和 complications 库迁移到 androidx.wear.watchface 库组。(b25f3c0)
  • 添加了 EditorRequest.canWatchFaceSupportHeadlessEditing，用于告知客户端表盘编辑器是否支持无头修改。请注意，这会带来一些假负例，因为已在 asop/1756809 中添加了对这些情况的支持，但此操作会为未来的所有表盘返回正确的值。(ca55590)
  • 渲染程序现在具有 dump() 方法，您可以替换该方法以向 ABD shell dumpsys activity 服务 WatchFaceService 生成的信息添加自定义数据。(95235f9)
  • InteractiveWatchFaceClient.addWatchFaceReadyListener 现在会先指定执行程序。(563ac2f)
  • StateFlowCompatHelper 已移除，应改用 asLiveData (androidx.lifecycle.asLiveData)。(bd35d3)
  • CurrentUserStyleRepository.userStyle 不再可变。(I44889)
  • WatchFaceReadyListener 已重命名为 OnWatchFaceReadyListener。(Ic12a9)

bug 修复

  • InteractiveInstanceManager.deleteInstance 会调用 onDestroy。这是确保 InteractiveWatchFaceImpl 回收垃圾的关键（fce4af8、b/199485839）