表盘格式

注意 ：若要将表盘安装到预安装了 Wear OS 5 或更高版本的设备上，以及在 Google Play 上发布所有新表盘，都必须使用表盘格式。

自 2026 年 1 月起，所有 Wear OS 设备都要求表盘采用表盘格式。

如需详细了解面向用户的变更，请参阅这篇帮助中心文章。

表盘是用户查看手表时最先看到的内容，因此是 Wear OS 最常用的界面。用户主要通过表盘来自定义手表，以彰显个人风格并提供一目了然的信息。

受众群体

借助全新的表盘格式 (WFF)，构建表盘变得前所未有地简单。 我们与三星合作推出了 Watch Face Studio，这是一款“所见即所得”风格的工具，可让您直接设计表盘。

如果您希望手动管理手表配置，还可以使用 XML 定义表盘。这些指南面向使用 XML 或构建自定义工具以使用表盘格式创建表盘的开发者。Android Studio 还支持构建和运行使用表盘格式的表盘。

表盘格式是与三星合作打造的声明式 XML 格式，用于配置表盘的外观和行为。与其他表盘 API 不同（在这些 API 中，您的 APK 必须包含用于渲染表盘的代码），表盘格式仅需要资源和声明式说明。Wear OS 平台负责处理呈现表盘所需的逻辑，这有助于您专注于创意构想，而非代码优化或电池性能。

与使用旧版 Jetpack 表盘库构建的表盘相比，使用这种新格式构建表盘能够减少必要的维护和更新工作。例如，您无需更新表盘，即可受益于性能提升或耗电量优化，甚至无需获取最新的 bug 修复。

格式简介

表盘格式 (WFF) 表盘的核心是定义表盘布局和行为的文档。本文档采用 XML 编写，符合 WFF 规范。

Wear OS 系统包含表盘渲染程序组件。此组件会解析您的 WFF XML 文档，并根据该文档呈现表盘。系统会根据需要提取其他资源，例如图片和字体。

这种方法意味着，您只需花时间描述表盘应有的外观，Wear OS 会处理用于绘制表盘的所有代码。

如需将表盘格式表盘部署到设备，请将 XML 文档打包到标准 AAB 或 APK 软件包中。

下图简要介绍了该方法：

WFF 中的版本控制

随着 WFF 的不断发展，我们会添加新功能，这些功能以格式中的新元素、属性、数据源等表示。

例如，WFF 版本 2 引入了天气作为数据源的支持，而 WFF 版本 1 不支持此功能。

在设计表盘时，请注意您要使用的功能及其版本。参考指南会标记所有功能及其可用性。

每个 WFF 版本都与 Wear OS 版本保持一致：

WFF 版本	Wear OS 最低版本	最低 API 级别
1	4	33
2	5	34
3	5.1	35
4	6	36

请参阅此指南，了解如何正确配置 AndroidManifest.xml 和 Gradle build 文件。

了解详情

如需详细了解表盘格式，请参阅以下指南：

• 可用功能：探索各个版本的表盘格式支持的表盘功能。
• 设计准则：了解表盘布局和用户体验的最佳实践。
• 设置：配置支持表盘格式的 Android App Bundle。
• GitHub 示例：开始构建示例表盘，并将其部署在 Wear OS 模拟器或实体设备上。
• 优化内存用量：了解如何配置表盘，使系统在渲染表盘时消耗尽可能少的内存。
• XML 参考文档：探索属于表盘格式文件的各个元素。根元素始终为 WatchFace。注意：如需在 XML 参考文档中查看特定表盘格式版本的功能，请检查文档页面顶部是否已选择相应的版本按钮。
• 发布指南：了解如何通过 Play 商店和其他方法发布表盘主题并通过其创收。
• WFF 和内存验证工具：在提交到 Google Play 之前，请使用这些开源工具检查表盘格式文件是否存在错误，并确认内存用量是否在可接受范围内。