表盘格式设置

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

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

Android Studio 使用入门

如需开始手动开发表盘，最简单的方法是使用 Android Studio。Canary 渠道中提供了表盘主题支持。

  1. 依次点击 File > New Project
  2. 在 Wear OS 下，选择基本表盘

这会为功能齐全的表盘创建必要的结构。

项目结构

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

声明表盘格式版本

在新应用的清单文件 (AndroidManifest.xml) 中，检查表明您使用的是表盘格式的应用属性。

表盘格式的部分功能仅在后续版本中提供。将此属性设置为支持所需功能的最低值，以最大限度地提高设备兼容性，同时将 minSdkVersion 设置为匹配的值。详细了解如何配置应用的版本。

<manifest ...>
    <!--
        Use SDK version 33 to support Watch Face Format (WFF) version 1 and
        higher, SDK version 34 to support WFF version 2 and higher, and so on.
    -->
    <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>

Android Studio 模板在 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"/>
<WatchFaces>

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

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

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

识别表盘发布商（可选）

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

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

检查表盘的正确性和性能

在开发期间以及上传到 Google Play 之前，请使用 Android Studio 中的内置表盘格式验证功能，检查表盘是否没有语法错误。此功能可自动突出显示代码中的错误，并且能够识别版本。

您还应运行内存占用工具，检查表盘是否满足内存使用要求。

构建表盘 app bundle

构建和部署表盘的最简单方法是通过 Android Studio，该工具内置了对表盘运行配置的支持。点击运行按钮后，Android Studio 会将表盘主题部署到设备或模拟器，并将其设置为有效表盘主题。

表盘主题示例

如需查看更多表盘格式项目示例，请访问 GitHub。