佩戴表盘

声明依赖项

要添加对 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-alpha03

2024 年 4 月 17 日

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

API 更改

• 我们添加了 EditorSession#setOverrideComplications，它在编辑时暂时设置底层手表界面实例的 ComplicationData。如果并发症很少更改，这比通过 EditorSession#renderWatchFaceToBitmap 传递覆盖更有效。 (I19384)

错误修复

• 以前，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() 创建）将传递到初始化期间调用的所有覆盖。
• 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 包含以下提交。

错误修复

• 修复了三星 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 定义进行了重命名，因此任何依赖于 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 设备上以 1Hz 更新的平台绑定。

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)
• enum 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）

错误修复

• 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 更改

• 我们已将可选参数 eglContextAttribList 添加到 GlesRenderer 和 GlesRenderer2，它允许您设置传递给 EGL14.eglCreateContext 的 EGL14.EGL_CONTEXT_CLIENT_VERSION。（I2a83e）
• 我们已将手表面库迁移到 androidx.core.util.Consumer，而不是 java.util.function.Consumer。（I273f5）
• KT 属性访问器中抛出的更多异常（Iff9d9）
• 我们已添加 InteractiveWatchFaceClient.isComplicationDisplayPolicySupported，以便客户端可以确定它是否必须代表旧手表面模拟支持。
• 我们已决定 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 支持。

错误修复

• 修复了在三星设备上手表面编辑器未正确释放导致的泄漏问题。（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 现在在样式层次结构中受支持，只要在任何时间最多只有一个处于活动状态即可。我们已将实用程序函数 findComplicationSlotsOptionForUserStyle 添加到 UserStyleSchema，以帮助查找活动 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 添加了对饼图和类似的简单数据细分支持。
• 我们已将对 ColorRamps 的可选支持添加到 RangedValueComplicationData。
• 对于 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）

错误修复

• 将 isForScreenShot 包含在 equals 和哈希码中。确保 onRenderParametersChanged 获取正确的 isForScreenshot 值（I04a41）
• 修复了无头客户端中 WatchFaceControlService 泄漏的问题。（e90e00）

版本 1.2.0-alpha03

2022 年 10 月 5 日

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

新功能

• 没有新功能，但我们修复了几个表盘编辑器错误。

API 更改

• 弃用 UserStyleSchema.userStyleSettings，因为 rootUserStyleSettings 变为非实验性（Ie96e3）。
• 将 rootUserStyleSettings 移出实验性（I8d6b3）。
• 我们将 WatchFaceColors 标记为实验性，因为它不受所有系统的支持（I6d75d）。
• 在公共 API 中公开 DisconnectReasons，使其与 IntDef 协同工作。（I791f8）。

错误修复

• 如果 SysUI 停止运行，则关闭手表编辑器中的任何打开的选项卡。如果 SysUI 停止运行且手表编辑器未关闭，则表盘可能会处于不一致状态，因为系统依赖 SysUI 来持久保存任何用户样式更改。（ba762a）。
• 修复了 ComplicationDataSourceInfoRetriever 中的内存泄漏问题，其中 Kotlin 协程延续充当 GC 根并保留了编辑器活动。（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 的新重载的 guava 包装器 getOrCreateInteractiveWatchFaceClient。（Ic31f0）。
• 我们添加了 Renderer.sendPreviewImageNeedsUpdateRequest，这对具有 UserStyleSchema 之外影响其外观状态的表盘（例如，具有可选择背景图像的表盘）很有用。在客户端，我们将 PreviewImageUpdateRequestedListener 添加为 getOrCreateInteractiveWatchFaceClient 的可选参数，以观察这些请求。（Iff44a）。
• 我们简化了公开 WatchFaceColors 的 API，现在在 Renderer 上有一个名为 watchFaceColors 的简单属性，表盘可以设置该属性，应根据需要在响应任何样式更改时更新该属性。我们添加了 OnWatchFaceColorsListener 到 InteractiveWatchFaceClient，而不是使用 WallpaperManager 来观察颜色变化。（I490bc）。
• 我们添加了一个 WatchFaceColors 类，它包含三个最突出的表盘颜色，并向 Renderer 添加了开放方法 watchfaceColors 和 notifyWatchFaceColorsChanged，这些方法允许系统通过 WallpaperManager.getWallpaperColors 获取表盘的颜色。（I3d611）。
• ShortTextComplicationData、RangedValueComplicationData、NoPermissionComplicationData（以及实验性的 DiscreteRangedValueComplicationData、GoalProgressComplicationData 和 WeightedElementsComplicationData）现在都支持 SmallImages。如果表盘选择以多种颜色渲染复杂项，它现在可以选择使用多色 SmallImage，而以前它必须使用单色图像。（I257df）。
• 将 PreviewImageUpdateRequestedListener 重构为 Consumer<>。（Ia875d）。
• 使用通用 Java SAM 类型（Consumer）替换自定义单抽象方法 (SAM) 类型 OnWatchfaceColorsListener。（I0c489）。
• 我们弃用了旧的 getOrCreateInteractiveWatchFaceClient 和 listenableGetOrCreateInteractiveWatchFaceClient 方法，这些方法不指定 PreviewImageUpdateRequestedListener。（Iec502）。

错误修复

• 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）。
• 我们在 WatchFaceService.getComplicationSlotInflationFactory 方法中添加了 currentUserStyleRepository 参数，以与 createComplicationSlotsManager 保持一致。（I2ddd2）。
• UserStyleFlavors 已成为非实验性功能。（I69cdc）。
• 我们从 RangedValueComplicationData 中删除了实验性的 ValueType，并改为引入了实验性的 DiscreteRangedValueComplicationData，它与 RangedValueComplicationData 类似，但使用整数范围和值。我们还引入了实验性的 GoalProgressComplicationData，它与 RangedValueComplicationData 类似，但它用于针对目标的进度，其中最小值隐式为零，并且允许该值大于 targetValue。请注意，对于所有 RangedValue 变体，必须至少指定单色图像、文本或标题之一。（I9590c）。
• 我们从 ComplicationSlotState 中删除了 boundsWithMargins，因为系统软件没有使用该方法。（I42e26）。
• 我们添加了对 WeightedElementsComplicationData 的实验性支持，它包含一个元素数组（权重和颜色的对），以及可选的文本/标题/图像。这些可能显示为饼图，其中颜色需要根据上下文具有意义，因为复杂项中通常没有足够的空间来渲染标签。（I87eea）。
• 实验性的 ColorRamps 可选地用于 RangedValueComplicationData 和 GoalProgressComplicationData，现在允许您指定最多七种颜色和一个标志，该标志表示颜色应该是平滑过渡的，还是应该渲染大小相同的实心颜色步骤。（I9f5bf）。
• RangedValueComplicationData.drawSegmented 已更改为 valueType，它是一个 int，具有相应的 ValueType IntDef，它为范围值提供语义含义，并可能被复杂项渲染器用来影响样式。（I0616b）。
• 我们添加了对 RangedValueComplicationData 的可选 ColorRanges 的实验性支持。通常，复杂项会以表盘选择的颜色进行渲染，但有时 ComplicationDataSource 最适合设置颜色，例如当它们具有特定的语义含义时。例如，红色到蓝色表示温度。（I5153a）。
• 我们在 RangedValueComplicationData 中添加了一个实验性的 drawSegmented 提示。这表示渲染器以段的形式绘制范围值指示器，其中 1 个段 = 1 个单位。（I7d7c1）。

错误修复

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

版本 1.1。

版本 1.1.1。

2022 年 8 月 10 日。

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

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

错误修复

• 表盘初始化是异步的，如果在表盘准备好之前收到复杂项，它将被放在 pendingInitialComplications 列表中，并在稍后应用。不幸的是，pendingInitialComplications 应用得太早，这意味着在表盘初始化期间有一个时间窗口，在此期间复杂项仍会放在 pendingInitialComplications 中并被忽略。这现在已修复。此外，此补丁修复了一个错误，即 ComplicationRenderer 错误地尝试异步加载占位符，这会导致失败，从而导致编译图形永远不会更新。最后，此补丁修复了一个希望是理论上的错误，即需要合并多个 pendingInitialComplications。（0d03ba3）。

• 修复InteractiveInstanceManager中潜在的死锁问题，其中getExistingInstanceOrSetPendingWallpaperInteractiveWatchFaceInstance保持锁的时间过长。通常我们期望engine.setUserStyle执行速度很快，但如果由于某种原因它没有那么快，我们可能会遇到死锁/ANR。此补丁将不必要的操作移出锁，消除了潜在的死锁。(5a2adca)

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

• 为awaitDeferredWatchFace* 添加超时，并修复 watchfaceOverlayStyle NullPointerException。在正常情况下，这应该不会超时，包括在全新安装和DirectBoot场景中，即使 CPU 负载很高。我们还修复了在 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，它提供了一系列时间门控数据，这些数据将传递到表盘，可以缓存并自动更新。例如，今天不同时间段的天气预报或多个即将到来的日历事件。
• ComplicationData中包含复杂功能提供程序的ComponentName。
• 复杂功能现在已缓存，这在表盘之间切换时提供了更好的体验。

其他变更

• 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)

错误修复

• 修复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。目前，这两种类型都没有渲染支持，并且 WearOS 目前不识别这些类型，即使它们已添加到 ComplicationDataSource 的清单中。(I1811c)

错误修复

• 修复 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)

错误修复

• WatchFaceMetadataClient 在收到部分 ComplicationSlotBounds 时将不再崩溃。(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），因此我们扩展了 NoDataComplication，它带有一个可选的占位符 ComplicationData，并添加了 ComplicationText.PLACEHOLDER、MonochromaticImage.PLACEHOLDER、SmallImage.PLACEHOLDER、PhotoImage.PLACEHOLDER，这些仅允许在 NoDataComplicationData 占位符的上下文中使用。如果选中，建议使用灰色框/弧线渲染这些占位符。 (I6285d)
• 我们添加了 ComplicationData.getNextChangeInstant，它告诉您在参考瞬间之后，复杂组件的任何字段可能会发生变化的下一个瞬间。这在内部用于安排复杂组件更新的帧。例如，如果手表界面通常每分钟更新一次，则设置秒表复杂组件将导致它每秒更新一次。 (I7ceb2)
• EditorSession.watchFaceId 现在可以在所有 API 级别使用。此外，它的值现在将始终与 WatchState.watchFaceInstanceId 保持一致。 (I323b9)
• getPendingIntentForTouchEvent API 不再需要，因为底层问题已在框架中修复，因此所有相关 API 都已删除。手表界面无需为 PendingIntents 触发执行任何特殊操作，即使最近按下了主页按钮。 (I1f2e8)
• 我们添加了 RendererParameters.isForScreenShot，如果渲染是为了截图，则该参数将为 true。一些带有动画的手表界面需要知道这一点，以便做出调整以确保最佳效果。 (I96d99)
• 我们添加了 WatchFaceExceptionReason 到 WatchFaceException 中，以提供一些关于错误原因的上下文信息。 (I01d15)
• ComplicationDataSourceService.onImmediateComplicationRequest 已删除，取而代之的是添加了 ComplicationRequest.immediateResponseRequired，以指示提供者需要快速响应（理想情况下在 < 100ms 内响应）。请注意，此功能受特权 com.google.android.wearable.permission.USE_IMMEDIATE_COMPLICATION_UPDATE 权限保护。 (Ie6b23)
• 更新了核心和 appcompat 中的可空性，以匹配 Tiramisu DP2 (I0cbb7)

错误修复

• 现在，如果模式验证失败，手表界面应用将使用异常崩溃 (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)
• 我们添加了 setNameResourceId 和 setScreenReaderNameResourceId（它们引用字符串资源）到 ComplicationSlot.Builder 中，以及 androidx.wear.watchface.client.ComplicationSlotState 中的相应 getter。这允许系统获取复杂组件插槽的名称，以供编辑器和屏幕阅读器使用。 (If6c6a)
• WatchFaceMetadataClient.getUserStyleSchema 和 getComplicationSlotMetadataMap 现在抛出 WatchFaceException 而不是 RemoteException。 (I86f11)
• onSynchronousComplicationRequest 和 ComplicationDataSourceService 中的相关函数已重命名为 onImmediateComplicationRequest 等。 (I87ba0)
• 手表界面编辑器的屏幕空间远小于配套编辑器，因此支持在手表界面编辑器中使用不同的图标是有意义的。此补丁将 OnWatchEditorData（目前仅包含一个图标）添加到所有 UserStyleSettings 中，并在适当的情况下将其添加到它们的 Option 类中。 (If1886)
• 我们添加了 @JvmOverloads 到 ListenableGlesRenderer 的构造函数中，以便更好地与 Java 交互。 (I2974a)

错误修复

• ListenableGlesRenderer 的构造函数现在正确地标记为 @Throws(GlesException::class)，现在可以在 Java 中扩展此类。 (Iac6d0)
• 修复了 PhotoImageComplicationData 点击操作未被正确处理的错误 (I1cc30)

版本 1.1.0-alpha02

2022 年 1 月 12 日

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

新功能

• 为了帮助调试和测试，ComplicationData 及其相关子类现在具有覆盖的哈希码、相等性和 toString 方法，使它们更容易使用。

API 更改

• WatchFaceMetadataClient 方法再次抛出 RemoteExceptions（在适当的情况下），使客户端代码更容易捕获来自手表界面的错误。 (I78785)
• ComplicationData 及其子类现在具有哈希码、相等性和 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 会被系统缓存在内存中，有时会由手表界面库序列化。序列化时，任何关联的点击操作都将丢失，如果发生这种情况，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。这可以帮助表盘在响应点击启动 Intent 时解决框架在按下主页按钮后阻止启动新活动 5 秒的问题。 (I98074)
• 引入了每个表盘的 ComplicationData 缓存。这样做是为了允许表盘在加载时显示最新的复杂功能数据值，直到系统有机会更新它们。有一个新的 API 方法 WatchFaceControlClient.hasComplicationCache 供 OEM 使用。这可能会影响系统将复杂功能发送到表盘的策略。此外，ComplicationData 具有一个 isCached 属性，建议对缓存的复杂功能进行不同的渲染，因为 tapAction 无法缓存，并且在缓存的复杂功能中将为 null。 (I404b0)
• 表盘的实例 ID 现在可通过 WatchState.watchFaceInstanceId 获得。大多数表盘不需要使用它，但是如果存在未存储在架构中的每个表盘状态，那么这就是用于标识表盘实例的键。为了帮助支持这一点，您现在可以在调用 WatchFaceControlClient.createHeadlessWatchFaceClient 时提供 ID。 (I1ff98)
• 扩展了 DefaultComplicationDataSourcePolicy，使其能够为主要、次要提供商以及后备系统提供商设置默认的 ComplicationTypes。 ComplicationSlot.defaultDataSourceType 现在已弃用。 (If0ce3)
• ComplicationSlot.configExtras 现在是可变的，可以在调用 EditorSession.openComplicationDataSourceChooser() 之前更新。 (I6f852)
• 添加了 WatchFace.setComplicationDeniedDialogIntent 和 setComplicationRationaleDialogIntent。这些 Intent 用于在请求复杂功能权限之前显示理由对话框，以及在尝试编辑复杂功能时解释需要复杂功能权限的另一个对话框（提供商选择器将无法打开，因此需要对话框）。 (I3a29c)
• UserStyleSchema 和 ComplicationSlots 现在可以在 XML 中定义。这简化了表盘构建，并使 WatchFaceMetadataClient 查询更快，因为它们不需要绑定到服务以获取元数据。 (I85bfa)
• 添加了 InteractiveWatchFaceClient.supportsPendingIntentForTouchEvent，以便客户端可以确定表盘是否支持 getPendingIntentForTouchEvent。 (I0b917)
• WatchFaceMetadataClient 和 ListenableWatchFaceMetadataClient 不再是实验性的。它们可用于有效地获取表盘元数据，在不打开到表盘的绑定器的情况下，尽可能做到这一点。 (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 包含这些提交。

错误修复

• 修复了 PhotoImageComplicationData 点击操作未被正确处理的错误 (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 支持库相比，它具有许多新功能。

• 库直接支持用户样式（例如，更改调色板、表盘指针的样式、时标的外观等）（请参阅 androidx.wear.watchface.style）。现在，使用 androidx.wear.watchface.editor 开发表盘上的编辑器变得更加容易，并且您的表盘可以在系统配套应用程序中进行编辑，而无需您编写任何额外的代码。
• 将最佳实践烘焙进去。该库会自动为复杂功能生成屏幕阅读器内容标签（您也可以添加自己的标签），并且当电池电量不足且未充电时，帧速率会自动下降，以延长电池续航时间。
• 开发表盘所需的代码更少，尤其是对于复杂功能而言，因为许多样板代码已迁移到库中。

错误修复

• 修复 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 包含这些提交。

错误修复

• 修复 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 不再是挂起函数，而是 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 表盘库和复杂功能库迁移到 androidx.wear.watchface 库组。 (b25f3c0)
• 新增了 EditorRequest.canWatchFaceSupportHeadlessEditing，让客户端知道表盘编辑器是否支持无头编辑。注意，由于在 asop/1756809 中添加了支持，因此此项可能会出现一些误报，但对于所有未来的表盘，它将返回正确的值。 (ca55590)
• 渲染器现在有一个 dump() 方法，该方法可以被重写以将自定义数据添加到 ABD shell dumpsys activity service WatchFaceService 生成的信息中。 (95235f9)
• InteractiveWatchFaceClient.addWatchFaceReadyListener 现在首先指定执行器。 (563ac2f)
• StateFlowCompatHelper 已被删除。应使用 asLiveData (androidx.lifecycle.asLiveData) 代替。 (bd35d3)
• CurrentUserStyleRepository.userStyle 现在不再是可变的。 (I44889)
• WatchFaceReadyListener 已重命名为 OnWatchFaceReadyListener。 (Ic12a9)

错误修复

• InteractiveInstanceManager.deleteInstance 调用 onDestroy 这对于确保 InteractiveWatchFaceImpl 被垃圾回收是必要的。 (fce4af8, b/199485839)