构建表盘服务

表盘主题是封装在 Wear OS 应用中的一种服务。当用户选择可用的表盘主题时，系统会显示该表盘主题并调用服务回调方法。

如果用户安装了包含表盘主题的 Wear OS 应用，可使用表盘主题选择器进行选择，在手表上显示相应表盘主题。或者也可以通过配对手机上的配套应用选择表盘。

本页将介绍如何配置 Wear OS 项目来包含表盘，以及如何实现表盘服务。

创建表盘项目

注意：我们建议您使用 Android Studio 开展 Wear OS 开发，因为使用它可以方便地进行项目设置、库收录和打包。

如需在 Android Studio 中为您的表盘主题创建项目，请完成以下步骤：

  1. 依次点击 File > New > New project。
  2. 在 Select a project template 窗口中，选择 Wear 标签页，再从选项列表中选择 Watch Face，然后点击 Next。
  3. 在 Configure your project 窗口中，接受默认值，然后点击 Finish。

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>

支持 direct-boot

您必须按照直接启动指南中的说明，在用户解锁之前使表盘可用：

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

实现服务和回调方法

Wear OS 中的表盘主题以 WatchFaceService 的形式实现。实现 WatchFaceService 需要创建三个对象：UserStyleSchema、ComplicationSlotsManager 和 WatchFace。

您可以通过替换 WatchFaceService 中的 3 个抽象方法来指定这 3 个对象，如下方示例所示：

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>

在向用户显示设备上安装的所有表盘主题时，Wear OS by Google 谷歌配套应用和穿戴式设备上的表盘主题选择器会使用 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" />

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

您还可以参阅以下相关资源：