表盘格式设置

本指南包含有关配置使用表盘格式的表盘所需的工具的步骤、一些关于项目结构的建议，以及一个逐步指南，说明如何应用这些工具来创建该结构。

先决条件

要为使用表盘格式准备您的开发环境，请完成以下设置步骤

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

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

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

项目结构

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

创建表盘包

要创建具有表盘文件的 Android 应用包，请完成以下部分中显示的步骤。

声明使用表盘格式

在您新应用的清单文件（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>

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

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

定义表盘的类别。必须是字符串或对字符串的引用，例如 @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属性值相对应的文件。

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

使用此页面中的示例，原始 XML 文件将是

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

根元素始终是WatchFace

<WatchFace width="450" height="450" shape="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 之前，使用验证工具检查表盘是否没有错误，以及它是否符合内存使用建议。

构建表盘应用包

要构建包含表盘的 Android 应用包，请使用 Gradle 构建系统。了解有关如何使用 Gradle 构建应用的更多信息。

这在GitHub 示例中进行了演示。