Wear Watchface

声明依赖项

要添加对 Wear 的依赖项，您必须将 Google Maven 代码库添加到您的项目中。如需了解详情，请阅读Google 的 Maven 代码库。

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

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"
}

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"
}

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

反馈

您的反馈有助于改进 Jetpack。如果您发现新问题或有改进此库的建议，请告诉我们。在创建新问题之前，请先查看此库中现有问题。您可以通过点击星形按钮为您已有的问题投票。

创建新问题

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

版本 1.3

版本 1.3.0-alpha07

2025 年 4 月 23 日

androidx.wear.watchface:watchface-*:1.3.0-alpha07 已发布。版本 1.3.0-alpha07 包含这些提交。

新功能

• 表盘的用户样式架构定义已有一段时间，现在也可以在 XML 中定义 ColorUserStyleSetting。

API 变更

• 使用 Kotlin 2.0 发布的项目需要使用 KGP 2.0.0 或更高版本。(Idb6b5)
• 添加了 Watch Face Push API，允许 Wear OS 应用以编程方式在手表上安装表盘。

Bug 修复

• 建议使用 1.3.0-alpha06 的复杂功能提供商进行升级，因为 WearOS 的下一个版本中修复了 ComplicationDataSourceUpdateRequester 的崩溃 bug。

版本 1.3.0-alpha06

2025 年 3 月 26 日

androidx.wear.watchface:watchface-*:1.3.0-alpha06 已发布。版本 1.3.0-alpha06 包含这些提交。

新功能

• wear watchface API（watchface、watchface-client、watchface-client-guava、watchface-complications-rendering、watchface-data、watchface-editor、watchface-editor-guava 和 watchface-style）已弃用，转而使用Wear Watchface Format，并最终将从 AndroidX 中移除。复杂功能 API 未弃用，并将保留。(Ice960)
• 复杂功能 API 现在能够直接与 WearSDK 通信，由于 IPC 跳数减少，效率更高。

版本 1.3.0-alpha05

2025 年 1 月 15 日

androidx.wear.watchface:watchface-*:1.3.0-alpha05 已发布。版本 1.3.0-alpha05 包含这些提交。

新功能

表盘通常允许用户使用 ListUserStyle 选择颜色。虽然这可行，但它需要通过蓝牙将图标发送到配套编辑器，效率低下，因此我们引入了 ColorUserStyleSetting，其中有效载荷是每个样式一个或多个颜色的列表，其线格式显着更紧凑。

我们添加了一个面向 OEM 的功能，允许 OEM 复杂功能提供商向 ComplicationData 添加额外数据，供 OEM 表盘使用。

API 变更

• UserStyleSetting 和 UserStyleOption 类现在具有构建器，这是构造它们的推荐方式。(Iacd03)
• 支持在 ComplicationData 中传递额外数据。这适用于 OEM，他们同时控制复杂功能提供商和接收表盘。设置额外数据需要特权 com.google.android.wearable.permission.COMPLICATION_EXTRAS 权限。(I4e3b2)
• 表盘通常允许用户使用 ListUserStyle 选择颜色，每个 ListOption 都有一个图标。由于 UserStyle 架构通过蓝牙发送，因此控制架构的大小非常重要，如果提供数十种颜色选项，由于所有这些图标，这可能会成为问题。为了解决这个问题，我们添加了 ColorUserStyleSetting，其中选项包含颜色列表而不是图标，这更紧凑。(Ib542e)
• ColorUserStyleSetting 和 ColorOption 需要 API 34 才能使用。(I8771d)

Bug 修复

• 此库现在使用JSpecify 空值注解，它们是类型使用的。Kotlin 开发者应使用以下编译器参数强制正确使用：-Xjspecify-annotations=strict（从 Kotlin 编译器 2.1.0 版本开始，这是默认值）。(Ifd363, b/326456246)

版本 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 访问的手动概述，因为在使用带有 AGP 7.3 或更高版本（例如 R8 版本 3.3）的 R8 时，以及在使用 AGP 8.1 或更高版本（例如 D8 版本 8.1）的所有构建中，这都会通过 API 建模自动发生。建议不使用 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 包含这些提交。

新功能

• 我们现在使用引用相等性来比较最佳和 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() 创建的用户定义额外数据被传递到初始化期间调用的所有重写中。
• GlesRenderer2 现在有一个构造函数重载，允许您指定一个属性列表，以便依次尝试 eglChooseConfig。

API 变更

• StatefulWatchFaceService 现在支持重写 getComplicationSlotInflationFactory，其中传递了由 createExtra() 创建的用户定义额外数据。(I82d9f)
• 一些表盘需要与 createUserStyleSchema 期间创建的辅助数据共享给其他初始化方法。由于没有更好的替代方案，开发者通常将他们的 WatchFaceServices 设为有状态。这很危险，因为可以并发创建多个实例，这可能导致错误。为了解决这个问题，我们引入了 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 修复

• 修复了三星 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，但它是针对目标的进度，其中最小值隐式为零，并且允许值大于 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 封装器。这些功能增加了对表盘运行时的支持，表盘运行时是一种特殊的表盘，其定义从另一个包中加载。目前 WearOS 仅支持Android 表盘格式的运行时。(I2799f)
• 此补丁是 aosp/2636578 的后续，我们重命名了 int def，因此任何依赖于 WatchFaceType、CanvasType、TapType 或 ComplicationsSlotBoundsType 的代码都不需要更改。(I4098b)
• 更新了 API 文件以注解兼容性抑制。(I8e87a, b/287516207)
• 此补丁公开了 WatchFaceType 常量在 WatchFaceTypes 中，CanvasType 常量在 CanvasTypes 中，TapType 常量在 TapTypes 中，以及 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 设备的每赫兹更新的平台绑定。

API 变更

• 添加了每日距离、每日卡路里和每日楼层的动态类型。平台健康源的键现在位于 PlatformHealthSources.Keys 下方。(Ib7637)
• 实现 PlatformDataProvider 以提供心率和每日步数。SensorGateway 接口已从公共 API 中移除。(I55b84)
• 将 StateEntryValue 重命名为 DynamicDataValue，并更新状态 API 以使用 DynamicDataKey。(If1c01)
• 添加 AppDataKey 以访问应用推送状态；添加 PlatformDataKey 以访问平台数据；在 StateStore 中添加命名空间支持。(I7985e)
• enable/disablePlatformSource 方法已从 DynamicTypeEvaluator 中移除。调用者应负责更新。(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，转而使用 createRemoteWatchFaceView，后者基于 SurfaceControlViewHost 构建，允许调用者嵌入表盘中的视图，当客户端调用 RemoteWatchFaceViewHost#renderWatchFace 时，该视图会渲染。(Ib311d)
• 我们已将 renderWatchFaceToSurface 添加到 InteractiveWatchFaceClient、HeadlessWatchFaceClient 和 EditorSession。通常，这会比渲染到位图更高效。(Ieacad)
• ObservableStateStore 已重命名为 StateStore。(Ieb0e2)
• 添加了 DynamicTypeEvaluator.Builder 而不是构造函数参数，以允许更多可选参数，包括 ObservableStateStore，它现在默认为空存储。(I6f832)
• 重构了 DynamicTypeEvaluator 中的参数顺序。(Ic1ba4)
• 执行器已添加到 DynamicTypeEvaluator.bind 方法中。(I346ab)
• 我们已将 startEvaluation 方法添加到 BoundDynamicType 中，以在绑定动态类型后触发评估。(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 开始，拥有特权 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 的复杂功能提供商可以确定复杂功能请求是否来自其提供商清单中由 android.support.wearable.complications.SAFE_WATCH_FACES 元数据定义的列表中的表盘，通过 ComplicationRequest#isForSafeWatchFace。提供商将需要 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 权限才能接收除 TargetWatchFaceSafety.UNKNOWN 之外的任何内容。

• 同样从 Android T 开始，CustomValueUserStyleSetting2 可供使用，最多可容纳 12.5kb。此前 CustomValueUserStyleSetting 的限制为 1kb。尽管增加了大小限制，但仍鼓励表盘开发者保持数据较小，因为设置在编辑期间通过蓝牙发送，而蓝牙带宽有限。

API 变更

• 我们已将可选参数 eglContextAttribList 添加到 GlesRenderer 和 GlesRenderer2 中，允许您设置传递给 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，我们引入了 ComplicationRequest.isForSafeWatchFace，它专为 OEM 使用，并且需要 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)
• 修复了一个错误，该错误导致在具有多个收藏夹的表盘之间切换时，复杂功能有时无法正确显示。(b38ece)
• 修复了 perOptionScreenReaderNames 的序列化错误，导致表盘崩溃。(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 变更

• 我们已将新的可选 screenReaderName 字段添加到 ListOption 和 ComplicationSlotsOption 中供编辑器使用 - 在 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，值被限制在 [min .. max] 范围内），这会对视觉设计产生影响，可能不适合所有表盘。
• GoalProgressComplicationData 增加了对饼图和类似简单数据分解的支持。
• 我们已为 RangedValueComplicationData 添加了对可选 ColorRamps 的支持。
• 对于 Android T，我们已将 ComplicationPersistencePolicy 和 setCachePolicy 添加到 ComplicationData 中，目前允许提供商控制复杂功能是否持久化（即是否在重启后缓存）。大多数复杂功能不需要设置缓存控制，但这样做可以解决一些经常更新的复杂功能（例如健康数据复杂功能）的数据陈旧的边缘情况。我们还添加了 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 包含在 equals 和 hash 代码中。确保 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)
• 将 DisconnectReasons 暴露在公共 API 中，以便它与 IntDef 一起使用。(I791f8)

Bug 修复

• 如果 SysUI 死亡，则关闭任何打开的表盘编辑器。如果 SysUI 死亡且表盘编辑器未关闭，则表盘可能会处于不一致的状态，因为系统依赖 SysUI 来持久化任何用户样式更改。(ba762a)
• 修复了 ComplicationDataSourceInfoRetriever 中的内存泄漏，其中 kotlin 协程延续充当垃圾回收根并保留了编辑器活动。(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，并扩展了 ClientDisconnectListener，新增了一个包含 DisconnectReason 的方法，允许侦听器观察引擎分离。(I45cce)
• 为 ComplicationSlotOverlay 构造函数添加了两个可选参数 nameResourceId 和 screenReaderResourceId (I157e8)
• 我们已为带有 PreviewImageUpdateRequestedListener 的新重载 getOrCreateInteractiveWatchFaceClient 添加了一个 guava 封装器。(Ic31f0)
• 我们添加了 Renderer.sendPreviewImageNeedsUpdateRequest，这对于那些其状态在 UserStyleSchema 之外但会影响其外观的表盘非常有用（例如，具有可选背景图像的表盘）。在客户端，我们已将 PreviewImageUpdateRequestedListener 作为可选参数添加到 getOrCreateInteractiveWatchFaceClient 中，以观察这些请求。(Iff44a)
• 我们已简化了公开 WatchFaceColors 的 API，现在 Renderer 上有一个名为 watchFaceColors 的简单属性，表盘可以设置它，并在任何样式更改时根据需要更新，而不是使用 WallpaperManager 来观察颜色更改，我们已将 OnWatchFaceColorsListener 添加到 InteractiveWatchFaceClient。(I490bc)
• 我们添加了一个 WatchFaceColors 类，它包含三个最主要的表盘颜色，并向 Renderer 添加了开放方法 watchfaceColors 和 notifyWatchFaceColorsChanged，这些方法允许系统通过 WallpaperManager.getWallpaperColors 获取表盘的颜色。(I3d611)
• ShortTextComplicationData、RangedValueComplicationData、NoPermissionComplicationData（以及实验性的 DiscreteRangedValueComplicationData、GoalProgressComplicationData 和 WeightedElementsComplicationData）现在都支持 SmallImages。如果表盘选择使用多种颜色渲染复杂功能，它现在可以选择使用多色 SmallImage，而以前它必须使用单色图像。(I257df)
• 将 PreviewImageUpdateRequestedListener 重构为 Consumer<> 类型 (Ia875d)
• 将自定义的单抽象方法（SAM）类型 OnWatchfaceColorsListener 替换为通用的 Java SAM 类型（Consumer）(I0c489)
• 我们已弃用旧的 getOrCreateInteractiveWatchFaceClient 和 listenableGetOrCreateInteractiveWatchFaceClient 方法，这些方法未指定 PreviewImageUpdateRequestedListener。(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 具有零大小的边距。(I14089)
• 更改了 getComplicationSlotInflationFactory(CurrentUserStyleRepository) 签名，使其返回一个非空工厂实例。以前返回 null 是一个错误，所以这只是使 API 合同更清晰。(I0fcc0)
• 我们已将 currentUserStyleRepository 参数添加到 WatchFaceService.getComplicationSlotInflationFactory 方法中，以与 createComplicationSlotsManager 保持一致。(I2ddd2)
• UserStyleFlavors 已成为非实验性功能。(I69cdc)
• 我们已从 RangedValueComplicationData 中移除了实验性 ValueType，转而引入了实验性 DiscreteRangedValueComplicationData，它类似于 RangedValueComplicationData，但用于整数范围和值。我们还引入了实验性 GoalProgressComplicationData，它类似于 RangedValueComplicationData，但用于目标进度，其中最小值隐式为零，并且值允许大于 targetValue。请注意，对于所有 RangedValue 变体，必须指定 monochromeImage、text 或 title 中的至少一个。(I9590c)
• 我们已从 ComplicationSlotState 中移除了 boundsWithMargins，因为系统软件没有使用它的用例。(I42e26)
• 我们添加了对 WeightedElementsComplicationData 的实验性支持，它由一个元素数组（权重和颜色的对）以及可选的文本/标题/图像组成。这些可能显示为饼图，其中颜色在给定上下文中需要有意义，因为复杂功能中通常没有空间渲染标签。(I87eea)
• RangedValueComplicationData 和 GoalProgressComplicationData 可选使用的实验性 ColorRamps 现在允许您指定最多七种颜色的序列，以及一个标志，指示颜色是否应平滑渐变，或者是否应渲染等大小的实心色块。(I9f5bf)
• RangedValueComplicationData.drawSegmented 已更改为 valueType，这是一个带有相应 ValueType IntDef 的整数，它为范围值提供了语义含义，并可由复杂功能渲染器用于影响样式。(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 包含这些提交。

• 这是一个 bug 修复版本，强烈建议 1.1.0 版用户升级。

Bug 修复

• 表盘初始化是异步的，如果复杂功能在表盘准备好之前收到，它会被放入 pendingInitialComplications 列表中，稍后应用。不幸的是，pendingInitialComplications 应用得太早，这意味着在表盘初始化期间有一段时间复杂功能仍会被放入 pendingInitialComplications 并被忽略。这个问题现在已修复。此外，此补丁修复了一个 bug，即 ComplicationRenderer 错误地尝试异步加载占位符，这导致编译图形从未更新。最后，此补丁修复了一个希望是理论上的 bug，即需要合并多个 pendingInitialComplications。(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 以来的重要更改

改进的编辑

• 我们增加了对分层架构的支持，允许编辑器 UI 编写样式层次结构。您现在可以为表盘和配套编辑器指定单独的图标。
• 有选择支持表盘的多个实例，每个实例在所有 API 界面上都有唯一的 ID。
• 您现在可以为编辑器中的 ComplicationSlots 指定易读的名称。
• 对样式“风格”的实验性支持，这是从配套编辑器可见的精选样式选择。
• 编辑时会加载两个表盘实例，现在表盘实例可以共享资源，从而节省内存
• 在表盘编辑器中选择复杂功能时，当前提供商现在会预选。

改进的复杂功能

• 您现在可以指定主数据源和辅助数据源的 ComplicationType，为开发者提供了更大的开箱即用灵活性。
• 我们添加了 ComplicationDataTimeline，它提供一系列时间限定数据，这些数据可以传递到表盘，并可以自动缓存和更新。例如，不同时间的天气预报或多个即将发生的日历事件。
• 复杂功能提供商的 ComponentName 是 ComplicationData 的一部分。
• 复杂功能现在已缓存，这在切换表盘时提供了更好的体验。

其他更改

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

版本 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 丢失时间轴字段的错误。（fb392f5）
• 修复了 runBlockingWithTracing 偶尔会导致 NPE 的错误。（12ca62e）
• 修复了有时在接收复杂功能时会遇到 ClassNotFoundException: android.support.wearable.complications.ComplicationText 的错误。（217942d9）
• 修复了 GlesRenderer.backgroundThreadInitInternal 中的一个错误，该错误仅在调用 EGL14.eglCreateContext 时才调用 onBackgroundThreadGlContextCreated。修复了另一个由于 verticalFlip 导致截图出现视觉故障的错误。（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 已弃用，取而代之的是支持 SharedAssets 并将其传递给渲染方法的 Renderer.CanvasRenderer2 和 Renderer.GlesRenderer2。为了 Java 互操作性，我们引入了 ListenableCanvasRenderer2 和 ListenableGlesRenderer2。（I31ffa）
• 添加了 @WatchFaceFlavorsExperimental 功能，用于定义风格 - 预配置的样式表盘列表。（I04dd0）
• Renderer.sharedAssets 现在是一个 StateFlow，我们已删除了未使用的 Renderer.SharedAssetsFactory。（I12ac5）
• UserStyleSchema.userStyleSettings 不再弃用。（Iba7e3）
• 我们添加了 HeadlessWatchFaceClient.getUserStyleSchemaDigestHash，它允许 HeadlessWatchFaceClient 在计算摘要哈希之前避免通过 AIDL 传递模式的相对较低的开销。（I33597）
• 我们向 WatchFaceMetadataClient 添加了 isUserStyleSchemaStatic，当且仅当 UserStyleSchema 在表盘 APK 未更新的情况下可以保证不变时，它才为 true。（I45a3f）
• 我们向 UserStyleSchema 添加了 getDigestHash，它计算模式的摘要哈希。这可以用于高效地确定 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）
• 我们向 WatchFaceException 添加了 WatchFaceExceptionReason，以提供有关出错原因的上下文。（I01d15）
• ComplicationDataSourceService.onImmediateComplicationRequest 已被移除，取而代之的是添加了 ComplicationRequest.immediateResponseRequired，用于指示提供程序需要快速响应（理想情况下在 < 100 毫秒内响应）。请注意，此功能受到特权 com.google.android.wearable.permission.USE_IMMEDIATE_COMPLICATION_UPDATE 权限的保护。（Ie6b23）
• 更新了核心和 appcompat 中的可空性，以匹配 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 使用。这允许描述样式层次结构供编辑器 UI 使用，底层 UserStyle 保持不变，并且仍然是 Map<String, ByteArray>。（Iaf6f4）
• 我们添加了 WatchFace.OverlayStyle，它允许表盘配置系统状态叠加层的渲染。（I8520d）
• 我们引入了 clearWithBackgroundTintBeforeRenderingHighlightLayer，这是 CanvasRenderer 的一个新的可选构造函数参数（默认为 false），如果设置为 true，则画布将使用背景色调颜色清除。（Ie01e5）
• 添加了 androidx.watchface.complications.datasource.DEFAULT_CONFIGURATION_SUPPORTED 元数据键，它允许复杂功能数据源指示它们可以在没有任何配置的情况下提供默认值。（Icc0d4）
• 在编辑表盘时，通常会同时存在交互式实例和无头实例。为了节省内存，我们引入了 Renderer.SharedAssets，它允许表盘渲染器在实例之间共享不可变数据（例如纹理和着色器）。GlesRenderer.setEglConfig 和 GlesRenderer.setEglDisplay 已弃用，这些从未打算设置为可设置的，这样做会导致未定义的行为。（I0d9e7）
• 我们向 ComplicationSlot.Builder 添加了 setNameResourceId 和 setScreenReaderNameResourceId（它们引用字符串资源），并在 androidx.wear.watchface.client.ComplicationSlotState 中添加了相应的 getter。这允许系统获取 ComplicationSlots 的名称，以便在编辑器和屏幕阅读器中使用。（If6c6a）
• WatchfaceMetadataClient.getUserStyleSchema 和 getComplicationSlotMetadataMap 现在抛出 WatchFaceException 而不是 RemoteException。（I86f11）
• ComplicationDataSourceService 中的 onSynchronousComplicationRequest 和相关函数已重命名为 onImmediateComplicationRequest 等。（I87ba0）
• 表盘编辑器比配套编辑器具有更少的屏幕空间，因此支持表盘编辑器的不同图标是合理的。此补丁将 OnWatchEditorData（目前仅包含一个图标）添加到所有 UserStyleSettings 以及适用的 Option 类中。（If1886）
• 我们向 ListenableGlesRenderer 的构造函数添加了 @JvmOverloads，以更好地实现 Java 互操作性。（I2974a）

Bug 修复

• ListenableGlesRenderer 的构造函数现在已正确标记为 @Throws(GlesException::class)，并且现在可以在 Java 中扩展此S类。（Iac6d0）
• 修复了 PhotoImageComplicationData 的 tapAction 未正确处理的错误。（I1cc30）

版本 1.1.0-alpha02

2022 年 1 月 12 日

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

新功能

• 为了便于调试和测试，ComplicationData 及相关子类现在已重写 hashcode、equals 和 toString 方法，使其更易于使用。

API 变更

• WatchfaceMetadataClient 方法在适当时再次抛出 RemoteExceptions，使客户端代码更容易捕获表盘中的错误。（I78785）
• ComplicationData 及子类现在具有 hashcode、equals 和 toString。（I24bc6）

版本 1.1.0-alpha01

2021 年 12 月 15 日

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

新功能

• UserStyleSchema 和 ComplicationSlots 现在可以在 XML 中定义。这简化了表盘的构建。此外，WatchFaceMetadataClient 查询速度更快，因为它不需要绑定到服务来获取元数据。WatchFaceMetadataClient 和 ListenableWatchFaceMetadataClient 不再是实验性的，并将成为稳定 API 的一部分。系统将能够选择性地支持表盘的多个实例，每个实例都具有不同的用户定义样式选项。这些将在表盘选择器中可见。要选择此功能，表盘必须在其清单中包含以下元数据标签。

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

• 有些表盘的状态未捕获在 UserStyle 中，为了支持这一点和多个实例，表盘的实例 ID 现在可通过 WatchState.watchFaceInstanceId 获取。

• ComplicationData 现在被缓存，以便复杂功能在加载时立即显示。有时 ComplicationData 由系统缓存在内存中，有时由表盘库序列化。当序列化时，任何关联的 tapAction 都将丢失，如果发生这种情况，ComplicationData.tapActionLostDueToSerialization 将返回 true，并且表盘应以不同方式渲染复杂功能（例如，置灰或半透明）以表示其不可点击。系统将尽快发送带有 tapAction 的更新 ComplicationData。

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

• DefaultComplicationDataSourcePolicy 已扩展，因此您可以指定主要和次要数据源的 ComplicationType。

• 我们增加了对同步复杂功能提供程序的支持，这些提供程序在表盘可见且非环境模式下，复杂功能的更新频率高于正常水平，最高可达每秒一次。注意： 由于内存压力问题，同步复杂功能提供程序的使用可能有限。

• PendingIntentTapListener 的更改很可能会被撤销，因为我们已经在框架中解决了底层问题（表盘在按下主页按钮后 5 秒内无法启动活动）。

API 变更

• ComplicationData.isCached 已更改为 tapActionLostDueToSerialization，这在确定复杂功能槽是否应以不同方式渲染以表示其不可点击时更有用。（I6de2f）
• 将 ComplicationDataTimeline 添加到 wear-complication-data-source。这可用于向表盘提供一系列受时间限制的 ComplicationData，这些数据可以缓存并自动更新。例如，今天不同时间的天气预报或多个即将到来的日历事件。ComplicationRequestListener 已扩展了一个新方法 onComplicationDataTimeline，您可以使用它来返回此数据。有一个新的 kotlin 包装器 SuspendingTimelineComplicationDataSourceService 用于挂起数据源服务。（Idecdc）
• 添加了 PendingIntentTapListener 和 WatchFaceControlClient.getPendingIntentForTouchEvent。这可以帮助需要在响应点击时启动意图的表盘，以解决框架在按下主页按钮后 5 秒内阻止启动新活动的问题。（I98074）
• 引入了每个表盘的 ComplicationData 缓存。其目的是允许表盘在加载时显示最后已知的复杂功能数据值，直到系统有机会更新它们。有一个新的 API 方法 WatchFaceControlClient.hasComplicationCache 旨在供 OEM 使用。此外，ComplicationData 具有 isCached 属性，建议以不同方式渲染缓存的复杂功能，因为 tapAction 无法缓存，并且在缓存的复杂功能中将为 null。（I404b0）
• 表盘的实例 ID 现在可通过 WatchState.watchFaceInstanceId 获取。大多数表盘不需要使用此功能，但如果存在未存储在 Schema 中的每个表盘状态，那么这是用于标识表盘实例的关键。为了帮助支持此功能，您现在可以在调用 WatchFaceControlClient.createHeadlessWatchFaceClient 时提供一个 ID。（I1ff98）
• 扩展了 DefaultComplicationDataSourcePolicy，增加了为主要、次要提供程序和备用系统提供程序设置默认 ComplicationTypes 的功能。ComplicationSlot.defaultDataSourceType 现已弃用。（If0ce3）
• ComplicationSlot.configExtras 现在是可变的，并且可以在调用 EditorSession.openComplicationDataSourceChooser() 之前更新。（I6f852）
• 添加了 WatchFace.setComplicationDeniedDialogIntent 和 setComplicationRationaleDialogIntent。这些意图用于在请求复杂功能权限之前显示一个理由对话框，以及另一个解释在权限被拒绝时尝试编辑复杂功能需要复杂功能权限的对话框（提供程序选择器将无法打开，因此需要对话框）。（I3a29c）
• UserStyleSchema 和 ComplicationSlots 现在可以在 XML 中定义。这简化了表盘的构建，并使 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 未正确处理的错误。（I1cc30）

版本 1.0.0

2021 年 12 月 1 日

androidx.wear.watchface:watchface-*:1.0.0 已发布。版本 1.0.0 包含这些提交。

1.0.0 的主要特性

androidx.wear.watchface 包是开发 WearOS 表盘的新推荐库。与旧的 Wearable Support Library 相比，它具有许多新功能。

• 用户样式（例如，更改调色板、表针样式、时标外观等）由库直接支持（参见 androidx.wear.watchface.style）。现在使用 androidx.wear.watchface.editor 开发表盘编辑器变得容易得多，并且无需编写任何额外代码即可通过系统配套应用编辑您的表盘。
• 内置最佳实践。该库自动为复杂功能生成屏幕阅读器内容标签（您也可以添加自己的标签），并且在电池电量低且未充电时，帧速率会自动降低以延长电池寿命。
• 开发表盘所需的代码更少，特别是对于复杂功能，许多样板代码已移至库中。

Bug 修复

• 修复 EditorSession.userStyle.compareAndSet。（I6f676）
• 修复表盘极短延迟。（Iffb97）
• 在 UI 线程上分派 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 之后运行，否则我们可能会延迟 UI 线程初始化。（37650ac）

• 确保调用 Renderer.onDestroy。在渲染器已创建但 WF 初始化尚未完成且调用了 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 项目。请注意，这意味着您不能同时包含此库和任何旧版 wear:watchface:watchface-complications-data 的 alpha 版本，否则会出现类重复错误。（I97195）
• Renderer.dump 已重命名为 Renderer.onDump，并已使用 @UiThread 注解。（I44845）
• InteractiveWatchFaceClient.addWatchFaceReadyListener 已重命名为 addOnWatchFaceReadyListener，removeWatchFaceReadyListener 已重命名为 removeOnWatchFaceReadyListener。（I48fea）
• EditorSession 的 getComplicationsPreviewData 和 getComplicationsDataSourceInfo 不再是 suspend 函数，而是 StateFlow<> 属性，其初始值为 null。在 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 包含这些提交。

新功能

表盘库现在是一个单一的库组，因此库已移动，您需要按如下方式更新您的 gradle 导入：

API 变更

• 将独立的 androidx.wear Watchface 和复杂功能库迁移到 androidx.wear.watchface 库组。（b25f3c0）
• 添加了 EditorRequest.canWatchFaceSupportHeadlessEditing，以告知客户端表盘编辑器是否支持无头编辑。请注意，这会存在一些误报，因为该支持已在 asop/1756809 中添加，但它将为所有未来的表盘返回正确的值。（ca55590）
• Renderer 现在有一个 dump() 方法，可以重写该方法，将自定义数据添加到由 ABD shell dumpsys activity service 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）