表盘格式设置

注意：本页面向您展示了手动管理表盘配置过程中的一个步骤。如果您希望改用所见即所得 (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。

创建表盘 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>

此文件中的字段表示以下详细信息：

预览
引用包含表盘预览图像的可绘制资源。
类别

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

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

AvailableInRetail

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

默认值：false

MultipleInstancesAllowed

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

默认值：false

可编辑

表盘是否可编辑，这意味着表盘具有设置或至少一个非固定复杂功能。这用于在收藏夹列表中显示或隐藏表盘的编辑按钮。

默认值：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 之前，请使用验证工具检查您的表盘是否没有错误，以及是否符合内存使用建议。

构建您的表盘应用 Bundle

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

这在GitHub 示例中有所演示。