表盘格式设置

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

前提条件

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

  1. 安装适用于 Android 13(API 级别 33)或更高版本的 SDK。该 SDK 中包含其他所需工具,包括 aapt2android.jar
  2. 安装 bundletool 命令行程序。
  3. 为包含表盘设计的应用的调试版本签名。您可以在 Android Studio 中生成签名的 Android App Bundle,也可以手动对调试 build 进行签名

项目结构

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

创建表盘软件包

如需创建包含表盘文件的 Android App Bundle,请完成以下各部分中介绍的步骤。

声明表盘格式的使用

在新应用的清单文件 (AndroidManifest.xml) 中,添加一个应用属性以表明您使用的是表盘格式:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest ...>
    <application ...>
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="1" />
    </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>

该文件中各字段的含义具体如下:

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

声明对表盘形状的支持

在应用的 res/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 属性值相对应的文件。您可以在此处定义每个表盘形状的表盘外观和行为。

使用本页中的示例,原始 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>

构建表盘的 app bundle

如需构建包含表盘的 Android App Bundle,请使用 bundletool。详细了解如何使用 bundletool 构建应用

请参阅 GitHub 示例,查看准备 app bundle 以供发布的示例,以及用于在提交到 Google Play 之前检查正确性的验证工具