Wear Watchface

打造适用于 Wear OS by Google 谷歌智能手表的应用。
最近更新时间 当前稳定版 下一候选版 Beta 版 Alpha 版
2022 年 1 月 12 日 1.0.0 - - 1.1.0-alpha02

声明依赖项

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

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

Groovy

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

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

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

Kotlin

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

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

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

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

反馈

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

创建新问题

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

版本 1.1

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