手表表盘格式设置

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

先决条件

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

  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

可编辑

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

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

构建手表表盘应用包

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

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