Wear Watchface

打造适用于 Wear OS by Google 谷歌智能手表的应用。
最近更新时间 稳定版 候选版本 Beta 版 Alpha 版
2022 年 4 月 20 日 1.0.1 - 1.1.0-beta01 -

声明依赖项

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

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

Groovy

dependencies {
    // Use to implement wear watchfaces
    implementation "androidx.wear.watchface:watchface:1.1.0-beta01"

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

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

Kotlin

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

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

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

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

反馈

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

创建新问题

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

版本 1.1

版本 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