构建表盘服务

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

如果用户安装了包含表盘的 Wear 应用,可以使用手表上的表盘选择器选择要使用的表盘,或者也可以通过配对手机上的配套应用选择表盘。

本页将介绍如何配置 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 参考文档

注意Android Studio 提供了项目设置、库集成和打包功能,因此建议使用 Android Studio 进行 Wear OS 开发。

声明权限

表盘需要 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>

支持矩形设备

默认情况下,为了支持针对圆形和方形设备构建的表盘,矩形设备上的表盘会在方形模拟模式下运行。如果您想完全支持矩形设备,请在 manifest 的表盘 service 中创建 meta-data 标记并将 android.service.wallpaper.square_mode 设置为 false 以替换此行为,如以下代码示例所示:

<manifest ...>
    <application ...>
        <service
            android:name=".MyWatchFace"
            android:label="My Watch Face"
            android:permission="android.permission.BIND_WALLPAPER">

            ...

            <meta-data
                android:name="android.service.wallpaper.square_mode"
                android:value="false" />
            ...
        </service>
    ...
    </application>
    ...
</manifest>

实现服务和回调方法

Wear OS 中的表盘以 WatchFaceService 的形式实现。实现 WatchFaceService 需要创建三个对象:UserStyleSchemaComplicationSlotsManagerWatchFace

您可以通过替换 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"
        android:resource="@drawable/preview_analog" />
    <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 元数据条目定义的预览图片。为了获取这一可绘制对象,请在 Wear OS 设备上或模拟器实例中运行表盘并截取屏幕截图。在屏幕的像素密度为 hdpi 的 Wear 设备上,预览图片的大小一般为 320x320 像素。

在圆形设备上看起来截然不同的表盘可同时提供圆形和方形预览图片。如需指定圆形预览图片,请使用 com.google.android.wearable.watchface.preview_circular 元数据条目。如果表盘同时包含两种预览图片,配套应用和穿戴式设备上的表盘选择器会根据手表的形状显示合适的图片。如果不包含圆形预览图片,那么方形和圆形设备都会使用方形预览图片。对于圆形设备,会将方形预览图片剪裁为圆形。

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

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

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

请参阅以下相关资源: