表盘格式设置

本指南包含以下内容：使用表盘格式配置表盘所需的工具；一些有关项目结构的建议；以及有关如何使用这些工具创建该结构的分步指南。

前提条件

为了使开发环境为使用表盘格式做好准备，请完成以下设置步骤：

  1. 安装适用于 Android 14（API 级别 34）或更高版本的 SDK。如果您的表盘不依赖于特定于版本 2 的功能或行为，您可以改为安装适用于 Android 13（API 级别 33）的 SDK。

    该 SDK 中包含其他所需工具，包括 aapt2 和 android.jar。

  2. 或者，安装 Android Studio，它也可以提供这些工具。

项目结构

创建使用表盘格式的自定义表盘时，包含自定义表盘文件的 Android App Bundle 必须与包含 Wear OS 应用逻辑的 Android App Bundle 完全分开。有些应用商店（包括 Google Play）会阻止您上传同时包含 Wear OS 逻辑和自定义表盘的 Android App Bundle。

创建表盘软件包

如需创建包含表盘文件的 Android App Bundle，请完成以下各部分中介绍的步骤。

声明表盘格式的使用

在新应用的清单文件 (AndroidManifest.xml) 中，添加一个应用属性，用于指明您使用了表盘格式。除非您想限制搭载 Wear OS 5 或更高版本的设备访问表盘，否则请创建 2 个不同的表盘 APK，一个支持版本 2，另一个支持版本 1。详细了解如何配置应用版本。

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest ...>
    <!--
        Use SDK version 34 for version 2 of WFF, and SDK version 33 for version
        1 of WFF
    -->
    <uses-sdk
        android:minSdkVersion="34"
        android:targetSdkVersion="34" />

    <!--
        WFF is a resource-only format, so the hasCode attribute should be set to
        false to reflect this.
    -->
    <application
        android:label="@string/watch_face_name"
        android:hasCode="false"
        ...>
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="2" />
    </application>
</manifest>

声明表盘元数据

在应用的 res/xml 资源目录中，创建一个名为 watch_face_info.xml 的新文件。您可以在该文件中定义表盘的元数据：

<?xml version="1.0" encoding="utf-8"?>
<WatchFaceInfo>
    <!-- Only "Preview" is required. -->
    <Preview value="@drawable/watch_face_preview" />
    <Category value="CATEGORY_EMPTY" />
    <AvailableInRetail value="true" />
    <MultipleInstancesAllowed value="true" />
    <Editable value="true" />
</WatchFaceInfo>

该文件中各字段的含义具体如下：

Preview
引用包含表盘预览图像的可绘制对象。
Category

定义表盘的类别。必须是字符串或对字符串的引用，例如 @string/ref_name。每个设备制造商都可以定义自己的一组表盘类别。

默认值：empty_category_meta，用于将此表盘与表盘选择器视图底部的其他“空类别”表盘分组在一起。

AvailableInRetail

表盘在设备的零售演示模式下是否可用。 必须是布尔值，或者是对布尔值的引用（例如 @bool/watch_face_available_in_retail）。

默认值：false

MultipleInstancesAllowed

表盘是否可以具有多个收藏夹。必须是布尔值，或者是对布尔值的引用（例如 @bool/watch_face_multiple_instances_allowed）。

默认值：false

Editable

表盘是否可修改，即表盘是否具有设置或至少一个非固定复杂功能。此字段用于在收藏夹列表中针对表盘显示或隐藏修改按钮。

默认值：false

声明表盘名称

在应用的清单文件 (AndroidManifest.xml) 中，将 android:label 属性设置为表盘的名称：

<application android:label="@string/watch_face_name" >

声明对表盘形状的支持（可选）

仅当您希望针对不同尺寸的表盘支持不同的行为时，才需要执行此步骤。如果您希望表盘能够根据手表的尺寸进行缩放，可以跳过此步骤。

在应用的 res/xml 资源目录中，在 watch_face_shapes.xml 中声明支持的表盘形状集：

<WatchFaces>
    <!-- The default shape is "CIRCLE". -->
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

声明表盘详细信息

在应用的 res/raw 资源目录中，创建与您声明对表盘形状的支持时使用的 file 属性值相对应的文件。

您可以在此处定义每个表盘形状的表盘外观和行为。如果您没有定义 Shapefile 文件，则只需创建一个文件，即 watchface.xml。

使用本页中的示例，原始 XML 文件将如下所示：

  • res/raw/watchface.xml
  • res/raw/watchface_large_circle.xml
  • res/raw/watchface_rectangle.xml

根元素始终为 WatchFace：

<WatchFace width="450" height="450" clipShape="CIRCLE">
    <!-- Remainder of your Watch Face Format definition here. -->
    <!-- If this file defines a watch face for a circular device shape, place
         resources used in this file in the "/res/drawable-nodpi" directory. -->
    <!-- If this file defines a watch face for a rectangular or other
         non-circular shape, place resources ued in this file in the
         "/res/drawable-notround-nodpi" directory. -->
</WatchFace>

识别表盘发布商（可选）

（可选）在应用的清单文件中，声明一个可用于识别表盘发布商的任意字符串，或声明您使用的工具名称和版本：

<application ...>
    ...
    <property
        android:name="com.google.wear.watchface.format.publisher"
        android:value="{toolName}-{toolVersion}" />
</application>

检查表盘的正确性和性能

在开发期间以及上传到 Google Play 之前，请使用验证器工具检查表盘是否没有错误，以及是否符合内存用量建议。

构建表盘 app bundle

如需构建包含表盘的 Android App Bundle，请使用 Gradle 构建系统。详细了解如何使用 Gradle 构建应用。

GitHub 示例中演示了这一点。