表盘格式设置

注意：本页面介绍了手动管理表盘配置的流程之一。如果您想改用 WYSIWYG（所见即所得）风格的工具来设计表盘，请先查看 Watch Face Studio 指南。

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

前提条件

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

  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。详细了解如何配置应用的版本。

<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"
        ...>
        <meta-data android:name="com.google.android.wearable.standalone"
            android:value="true" />
        <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>

    <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" >

声明表盘详细信息

基本 WFF 表盘文档的结构如下：

<WatchFace width="450" height="450">
  <Scene>
    <!-- Content to be rendered -->
  </Scene>
</WatchFace>

构建表盘时，如果使用单个表盘，请将此 XML 文件创建为 res/raw/watchface.xml。如需支持不同的屏幕形状和尺寸，请声明支持多种形状和尺寸。

根元素始终为 WatchFace。height 和 width 用于定义表盘中坐标空间的范围，表盘会根据所用设备进行缩放；height 和 width 不代表实际像素。

表盘格式会整理表盘的多个详细信息：

  • 元数据，例如表盘预览图片中显示的时间和步数。
  • 用户配置，例如表盘的不同颜色主题、可供用户切换的元素，以及可供用户选择的多个元素。表盘格式版本 2 引入了变种，可显示在用户配置中。每个变种都指定了预设的用户配置，指定了与表盘中时间一起显示的元素的类型和样式。借助这些预设，您可以更轻松地创建视觉效果出色的元素群组。在 Wear OS 配套应用中，用户会在可滚动行中看到表盘的不同变体。
  • 包含表盘视觉元素的场景。靠近场景结尾处显示的元素会显示在其他元素之上，因此典型顺序如下：
    • 模拟时钟的时针或数字时钟的文本
    • 显示其他信息（例如星期几或用户的步数）的复杂功能
    • 为表盘提供视觉吸引力或装饰效果的其他图形，例如露营地的图片
  • 元素的组，可让您同时修改多个元素。您可以在场景中为这些组创建变体，以便在系统进入省电氛围模式时选择性隐藏或修改内容。

属性是强类型的，并且有关于频率和有效值的指南，以从源头避免在创建表盘时出现的大多数错误。

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

仅当您希望针对不同大小的表盘支持不同的行为时，才需要执行此步骤。如果您希望表盘随手表尺寸调整大小，则可以跳过此步骤。

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

<WatchFaces>

    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>

    <!-- Remove any references to rectangular watch faces -->
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

然后，为每个表盘形状定义表盘外观和行为。如果您未定义形状文件，则只需创建一个文件 watchface.xml。

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

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

识别表盘发布商（可选）

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

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

检查表盘的正确性和性能

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

构建表盘 app bundle

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

GitHub 示例中演示了这一点。