Wear Watchface

打造适用于 Wear OS by Google 谷歌智能手表的应用。
最近更新时间 稳定版 候选版本 Beta 版 Alpha 版
2022 年 11 月 9 日 1.1.1 - - 1.2.0-alpha04

声明依赖项

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

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

Groovy

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

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

    // Use to implement a watchface style and complication editor
    implementation "androidx.wear.watchface:watchface-editor:1.1.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.1.1"
}

Kotlin

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

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

    // Use to implement a watchface style and complication editor
    implementation("androidx.wear.watchface:watchface-editor:1.1.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.1.1"
}

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

反馈

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

创建新问题

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

版本 1.2

版本 1.2.0-alpha04

2022 年 11 月 9 日

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

新功能

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

API 变更

  • GoalProgressComplicationDataWeightedElementsComplicationDataColorRamp 不再是实验性功能。(Ica9e2)
  • ComplicationPersistencePolicyComplicationDisplayPolicy 现在已正确标记为 T API。(I31d88)
  • 已废弃的 ComplicationSlotOverlay 构造函数现在具有 DeprecationLevel.WARNING,允许再次通过 Java 进行调用。(Ib308c)
  • 通过使用 @JvmDefaultWithCompatibilityComplicationRequestListenerCanvasComplicationComplicationTapFilter 以及 InteractiveWatchFaceClient 添加注解,我们解决了它们存在的一些 Java 兼容性问题 (Id94fc)
  • 移除了实验性 ProtoLayoutComplicationDataListComplicationData。我们不太清楚相关的开发者故事,希望以后能提供。(I9df05)
  • 已将 ValueType 重新添加到 RangedValueComplicationDataWeightedElementsComplicationData 现在支持背景颜色。移除了 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 构造函数添加了两个可选参数 nameResourceIdscreenReaderResourceId (I157e8)
  • 为带有 PreviewImageUpdateRequestedListener 的新 getOrCreateInteractiveWatchFaceClient 重载添加了 guava 封装容器。(Ic31f0)
  • 我们添加了 Renderer.sendPreviewImageNeedsUpdateRequest,当表盘具有会影响外观的 UserStyleSchema 之外的状态时(例如,具有可选择背景图片的表盘),此方法会很有用。在客户端,我们将 PreviewImageUpdateRequestedListener 作为可选参数添加到了 getOrCreateInteractiveWatchFaceClient,以观察这些请求。(Iff44a)
  • 我们简化了用于公开 WatchFaceColors 的 API,现在 Renderer 中有一个名为 watchFaceColors 的简单属性,表盘可以设置此属性。必要时,此属性应随着样式的变化而更新。我们向 InteractiveWatchFaceClient 添加了 OnWatchFaceColorsListener,不再使用 WallpaperManager 观察颜色变化。(I490bc)
  • 我们添加了一个 WatchFaceColors 类,用于保存三种最显眼的表盘颜色;还向渲染程序添加了 watchfaceColorsnotifyWatchFaceColorsChanged open 方法,这些方法可让系统通过 WallpaperManager.getWallpaperColors 获取表盘的颜色。(I3d611)
  • ShortTextComplicationDataRangedValueComplicationDataNoPermissionComplicationData(以及实验性的 DiscreteRangedValueComplicationDataGoalProgressComplicationDataWeightedElementsComplicationData)现在均支持 SmallImages。如果表盘选择渲染具有多种颜色的复杂功能,它现在可以选择使用多色 SmallImage,而以前则必须使用单色图片。(I257df)
  • PreviewImageUpdateRequestedListener 重构为 Consumer<> (Ia875d)
  • 将自定义单一抽象方法 (SAM) 类型 OnWatchfaceColorsListener 替换为通用 Java SAM 类型(使用方)(I0c489)
  • 我们废弃了未指定 PreviewImageUpdateRequestedListener 的旧版 getOrCreateInteractiveWatchFaceClientlistenableGetOrCreateInteractiveWatchFaceClient 方法。(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)
  • 现在,借助可由 RangedValueComplicationDataGoalProgressComplicationData 选择性使用的实验性 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,用于为表盘提供一系列有时间限制的数据,这些数据可自动缓存和更新。例如,今天不同时间的天气预报或多个即将发生的日历活动。
  • 复杂功能提供程序的 ComponentNameComplicationData 的一部分。
  • 系统现在会缓存复杂功能,以便在切换表盘时提供更好的体验。

其他变更:

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

版本 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,并会被传送到 ComplicationSlotStateWatchFaceMetadataClient。(I61a40)
  • 我们添加了在 UserStyleSetting XML 中继承设置的功能。这样一来,您就可以降低详细程度,并在表盘之间共享一个设置。(Ief841)
  • 我们添加了两种新的实验性 ComplicationData 类型:ListComplicationDataProtoLayoutComplicationData。目前,这两种类型都不支持渲染,如果这些类型添加到 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 方法(getUserStyleSchemagetComplicationSlotMetadataMapgetUserStyleFlavors)和 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.CanvasRendererRenderer.GlesRenderer,取而代之的是 Renderer.CanvasRenderer2Renderer.GlesRenderer2,后者支持传递给呈现方法的 SharedAssets。为了 Java 互操作性,我们引入了 ListenableCanvasRenderer2ListenableGlesRenderer2。(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.PLACEHOLDERMonochromaticImage.PLACEHOLDERSmallImage.PLACEHOLDERPhotoImage.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.setEglConfigGlesRenderer.setEglDisplay,我们从未打算使其可设置,因为这样做会导致出现未定义的行为。(I0d9e7)
  • androidx.wear.watchface.client.ComplicationSlotState 中为 ComplicationSlot.Builder 和相应的 getter 添加了 setNameResourceIdsetScreenReaderNameResourceId(引用字符串资源)。这样一来,系统便可以提取 ComplicationSlot 的名称,以便在编辑器和屏幕阅读器中使用。(If6c6a)
  • WatchfaceMetadataClient.getUserStyleSchemagetComplicationSlotMetadataMap 现在会抛出 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 定义 UserStyleSchemaComplicationSlots。这有助于简化表盘构造。此外,WatchFaceMetadataClient 查询会更快,因为它不需要绑定到服务,即可获取元数据。WatchFaceMetadataClientListenableWatchFaceMetadataClient 不再是实验性功能,而是将成为稳定 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)
  • 添加了 PendingIntentTapListenerWatchFaceControlClient.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,现在它能够为主要提供程序、辅助提供程序和后备系统提供程序设置默认的 ComplicationTypesComplicationSlot.defaultDataSourceType 现已被废弃。(If0ce3)
  • ComplicationSlot.configExtras 现在是可变的,可以在调用 EditorSession.openComplicationDataSourceChooser() 之前进行更新。(I6f852)
  • 添加了 WatchFace.setComplicationDeniedDialogIntentsetComplicationRationaleDialogIntent。启动这些 intent 是为了在请求复杂功能权限之前显示一个理由对话框,以及在权限已被拒的情况下,在尝试修改复杂功能时显示另一个对话框来解释为什么需要相应的复杂功能权限(提供程序选择器将无法打开,因此需要显示该对话框)。(I3a29c)
  • 现在,您可以使用 XML 定义 UserStyleSchemaComplicationSlots。这有助于简化表盘构造,并提高 WatchFaceMetadataClient 查询的速度,因为它们不需要绑定到服务,即可获取元数据。(I85bfa)
  • 添加了 InteractiveWatchFaceClient.supportsPendingIntentForTouchEvent,以便客户端可以确定表盘是否支持 getPendingIntentForTouchEvent。(I0b917)
  • WatchFaceMetadataClientListenableWatchFaceMetadataClient 不再是实验性功能。它们可用于高效获取表盘元数据,在可能的情况下,甚至无需打开表盘的 binder。(Ibb827)
  • 添加了对同步复杂功能提供程序的支持,在此类提供程序中,复杂功能的更新频率高于正常频率,当表盘可见且处于非氛围模式时,最高更新频率可达到每秒一次。要使用此类提供程序,必须在其清单中添加新的 androidx.wear.watchface.complications.data.source.SYNCHRONOUS_UPDATE_PERIOD_SECONDS 元数据标记,并替换 onSynchronousComplicationRequest。您可能还需要替换 onStartSynchronousComplicationRequestsonStopInteractiveComplicationRequests,以便在复杂功能进入和退出互动模式时收到通知,具体取决于数据源的性质。(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中的 getComplicationsPreviewDatagetComplicationsDataSourceInfo 不再是挂起函数,而是初始值为 null 的 StateFlow<> 属性。移除了 ListenableEditorSession 中的 getListenableComplicationPreviewDatagetListenableComplicationsProviderInfo,取而代之的是基类中的新 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 回收垃圾的关键(fce4af8b/199485839