构建表盘服务

表盘是一种服务,封装在 Wear OS 应用中。当用户选择可用的表盘时,表盘会显示,并且会调用服务回调方法。

当用户安装包含表盘的 Wear 应用时,这些表盘可以通过手表上的表盘选择器进行选择。另外,用户也可以通过配对手机上的配套应用选择表盘。

本页面介绍了如何配置 Wear OS 项目以包含表盘,以及如何实现表盘服务。

创建表盘项目

注意:我们建议您使用 Android Studio 进行 Wear OS 开发,因为它提供了项目设置、库包含和打包方面的便利。

请按照以下步骤在 Android Studio 中为您的表盘创建项目

  1. 点击文件 > 新建 > 新建项目
  2. 选择项目模板窗口中,选择 Wear 标签页,然后从选项列表中选择表盘,并点击下一步
  3. 配置您的项目窗口中,接受默认值并点击完成

Android Studio 会创建一个包含 app 模块的项目,用于您的表盘服务。

依赖项

Android Studio 会自动在您的 build.gradle 文件中添加所需的依赖项。这些依赖项中包含 AndroidX 表盘库;如需详细了解此库,请参阅 GitHub 上的代码示例

可穿戴设备支持库 API 参考

参考文档详细介绍了用于实现表盘的类。请浏览可穿戴设备支持库的 API 参考文档

声明权限

表盘需要 WAKE_LOCK 权限。将以下权限添加到 Wear OS 应用和手机应用的清单文件中的 manifest 元素下:

<manifest ...>
    <uses-permission
        android:name="android.permission.WAKE_LOCK" />

    <!-- Required for complications to receive complication data and open the provider chooser. -->
    <uses-permission
        android:name="com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA"/>
    ...
</manifest>

支持直接启动

您必须遵循直接启动指南,在用户解锁设备之前提供您的表盘。

  1. 在您的清单文件中,将服务的 android:directBootAware 属性设置为 true
  2. 您的表盘应将信息存储在设备加密存储中。

实现服务和回调方法

Wear OS 中的表盘是作为 WatchFaceService 实现的。实现 WatchFaceService 需要创建三个对象:UserStyleSchemaComplicationSlotsManagerWatchFace

这三个对象通过重写 WatchFaceService 中的三个抽象方法来指定,如下例所示:

Kotlin

class CustomWatchFaceService : WatchFaceService() {

    /**
     * The specification of settings the watch face supports.
     * This is similar to a database schema.
     */
    override fun createUserStyleSchema(): UserStyleSchema = // ...

    /**
     * The complication slot configuration for the watchface.
     */
    override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager = // ...

    /**
     * The watch face itself, which includes the renderer for drawing.
     */
    override suspend fun createWatchFace(
        surfaceHolder: SurfaceHolder,
        watchState: WatchState,
        complicationSlotsManager: ComplicationSlotsManager,
        currentUserStyleRepository: CurrentUserStyleRepository
    ): WatchFace = // ...

}

注册表盘服务

实现表盘服务后,请在可穿戴应用清单文件中注册该实现。当用户安装此应用时,系统会使用有关服务的信息,使表盘在Wear OS 配套应用和可穿戴设备上的表盘选择器中可用。

以下示例展示了如何在 <application> 元素下注册表盘实现:

<service
    android:name=".AnalogWatchFaceService"
    android:label="@string/analog_name"
    android:permission="android.permission.BIND_WALLPAPER" >
    <meta-data
        android:name="android.service.wallpaper"
        android:resource="@xml/watch_face" />
    <meta-data
        android:name="com.google.android.wearable.watchface.preview_circular"
        android:resource="@drawable/preview_analog_circular" />
    <intent-filter>
        <action android:name="android.service.wallpaper.WallpaperService" />
        <category
            android:name=
            "com.google.android.wearable.watchface.category.WATCH_FACE" />
    </intent-filter>
</service>

Google 提供的 Wear OS 配套应用和可穿戴设备上的表盘选择器在向用户显示设备上安装的所有表盘时,会使用由 com.google.android.wearable.watchface.preview_circular 元数据条目定义的预览图片。要获取此可绘制资源,请在您的 Wear OS 设备或模拟器实例中运行表盘并截取屏幕截图。在配备 hdpi 屏幕的 Wear 设备上,预览图片通常为 320x320 像素。

android.service.wallpaper 元数据条目指定了 watch_face.xml 资源文件,其中包含一个 wallpaper 元素,如下例所示:

<?xml version="1.0" encoding="UTF-8"?>
<wallpaper xmlns:android="http://schemas.android.com/apk/res/android" />

您的可穿戴应用可以包含多个表盘。您必须为每个表盘实现在可穿戴应用的清单文件中添加一个服务条目。

请参阅以下相关资源: