widget 是可自定义的主屏幕元素，它们会显示一个清晰且可操作的应用内容或操作视图。此内容可能会定期刷新。
widget 可以直接在 widget 中与应用内容互动，也可以提供完整的应用体验，帮助用户更轻松地实现目标。
图 1. 左图：任务应用可在主屏幕中添加杂货购物清单，从而提高工作效率。右图：音乐应用提供了播放控件和专辑封面，因此用户无需导航到该应用。
widget 还可以突出显示内容，从而吸引用户打开您的应用。
图 2. 突出显示最新发布的有声读物应用 widget。
断球数
创建 widget 时，请注意以下几点：
- 确保内容和功能保持简单。
- 选择合适的 widget 形状、布局和内容类型。
- 您可以为一个应用创建多个 widget，以展示不同的操作或信息。
- 不妨考虑创建一个可调整大小的布局。
- 确保内容新鲜而简短。
- 尽量减少控件的相关性和相关性。
- 尽可能填满主屏幕上分配的网格空间，以最大限度地减少 widget 之间的尴尬间隙。
- 请为 widget 提供有意义的说明和预览，以便用户可以在 widget 选择器中做出更明智的决策。
- 如果您的 widget 支持交互式手势，请勿干扰常见的主屏幕手势。
开始使用
创建 widget 时，请完成以下步骤：
- 选择要在 widget 中突出显示的一个主要用户案例。
- 请查看 Figma 上的 widget 模板示例。
- 按照手势和大小调整 widget 准则设计界面。
- 针对多种屏幕尺寸进行测试。
添加 widget
通常可以通过以下方式之一从主屏幕添加 widget：
1. 通过 widget 选择器，长按主屏幕壁纸即可访问。
微件选择器会显示预览和说明。widget 按应用分组，并应包含有意义的说明。为了帮助用户直观地了解 widget 如何显示信息，请使用单独的预览布局和预览数据。如需详细了解如何改进应用的 widget 预览，请参阅改进应用的 widget 预览。
2. 通过快捷方式（通常是长按应用图标）。
3. 通过固定应用，这是一种将 widget 添加到主屏幕的应用内体验。
您可以将微件拖动到主屏幕上的可用空间。“添加 widget”体验可能因设备制造商而异，但不需要额外考虑。放置后，用户可以通过长按来移动和调整 widget 的大小。
微件配置
您可以配置 widget 来显示应用中的选定内容或数据。提供配置步骤，以便用户根据一组多个类别（例如基于通信的应用的一组联系人）自定义一目了然的内容。配置发生在 widget 选择和显示在主屏幕上之间。
图 3. 用于选择要在微件中显示的文件夹的邮件配置步骤。
引导用户完成配置，并提供明确的反馈。
完成现有的关键用户历程
由于 widget 是应用在主屏幕上的扩展，因此 widget 的用途应与核心应用中的现有用户历程相一致。widget 遵循与 Wear OS 上的功能块类似的设计原则，让用户能够一目了然地获取信息，从而实现其目标并快速采取行动。
让 widget 只包含一些操作和内容类型，以防止 widget 过多。
图 4. “邮件”应用会显示最新的收件箱和“写邮件”按钮。
正确做法
用例
以下是基于微件包含的内容类型的用例。
基于信息的 widget 通常显示关键信息元素，并跟踪该信息随时间的变化。下面列举了一些能在 widget 上正常显示的信息示例：
- 可轻松以紧凑的形式汇总的用户健康数据。
- 健身跟踪数据和健康相关统计信息。
- 天气信息（可快速浏览）。
- 库存数据，可在用户的主屏幕上提供快速读取信息。
- 时钟和时间信息（您可针对自己的主屏幕进行自定义）。
某些 widget 可能是一系列相似内容类型。 此类内容包括：
- 允许用户滚动浏览所选影集的照片图库微件。
- 通信微件，显示所选文件夹中的最新电子邮件。
- 一款新闻应用，可为您提供您喜爱的类别的报道。
控制 widget 显示常用功能，以便用户可以从主屏幕触发它们，而无需打开应用。这方面的一些示例如下：
- 无线耳机的控件。
- 用于开启/关闭和控制亮度的智能灯泡控件。
widget 可以包含不同类型的内容并实现多种用途。这种混合功能有助于完成相互补充的关键用户历程。此类内容包括：
- 一个媒体应用 widget，用于显示简短的歌曲元数据和播放控件。
- 主屏幕 widget，可让用户切换家居控件并提供小型图库。
何时不应使用 widget
微件并不适用于所有用例。由于 widget 显示在主屏幕上，因此它们不应依赖于敏感信息或安全信息。例如，银行应用不应具有在锁定的屏幕上显示帐号余额数据的 widget。相反，它可以提供访问银行服务的快捷链接。
widget 也不应处理复杂的用户流。例如，对于具有大量登记流程且可能含有私密数据的医疗保健相关应用，您最好通过核心应用体验（而不是通过 widget）访问该应用。
虽然 widget 和通知在核心应用之外同样占用空间小，但某些用例更适合使用 widget。例如，通过显示应用中最新发布的五篇文章的集合 widget 可以快速查看最新内容，并允许用户选择一篇文章以继续阅读。此 widget 比通知用户有五篇未读文章要阅读的通知更有用。同一应用应在新文章发布时显示通知，以提供及时信息。
正确做法
错误做法
如需详细了解何时使用通知而不是 widget，请参阅通知。
手势
widget 不支持水平滑动和长按手势，以防止其他主屏幕手势受到干扰。请仅对 widget 使用点按和垂直滑动手势。此约束条件限制了在 widget 中使用某些依赖于手势的组件（例如轮播界面）。
主题
虽然您可以表达应用的品牌，但 widget 仍然是用户主屏幕的一部分。通过遵循用户的系统界面设置，在您的品牌和用户自定义之间取得平衡。尽可能遵循 Material 3 的形状、颜色、排版和组件设计准则。
为了更好地适应用户的主屏幕，请允许 widget 进行调整以适应系统设备主题。这样一来，您的 widget 便可以利用浅色/深色主题和对比度设置等功能，但 widget 的界面在不同设备制造商中的显示效果可能会略有不同。圆角默认不大于 28 dp，但也可能因设备制造商实现而异。为了适当地填充主屏幕网格，请不要在您的 widget 上设置角半径。
widget 使用通过启动器提供的系统字体，这意味着应用的自定义字体不适用于 widget。如需引用系统字体，请使用 FontFamily。
动态配色
从 Android 12 开始，widget 可以为按钮、背景和其他组件使用设备主题颜色。这样一来，不同的 widget、图标和壁纸将具有更流畅的视觉一致性和个性化效果。
使用 Material 颜色角色和令牌来实现无障碍功能对比度指南并支持动态颜色功能，例如用户生成的颜色、深色主题和对比度主题。如需了解详情，请参阅 Material Design 颜色指南。
图 5. 一个采用动态配色的 widget。
widget 形状
使用包含行和列的矩形背景容器，或使用 Box 创建自由形状的 widget。矩形 widget 具有圆角，应适应系统界面并填充其分配的网格空间。自由格式的 widget 具有各种 Material 形状可供选择，包括药丸和馅饼。无论形状如何，布局都应响应尺寸调整。
图 6. 答：矩形图库 widget。B. 一个自由样式的天气 widget。
错误做法
如需详细了解 widget 布局，请参阅使用 Glance 构建界面。
解剖学
图 8. 基本的 widget 剖析。
1 应用图标 2 应用名称标题 3 操作 4 内容
应用图标、操作和标题是可选的，但应固定在顶部（如果存在）。
标题栏是矩形 widget 的可选组件，其中包含应用图标和应用名称。它们应固定在 widget 顶部。请勿将应用名称替换为其他名称。
应用图标是一个代表您的应用的单色图标。您可以使用与自适应彩色图标相同的单色图标。
内容
一目了然的密度较低的内容最适合使用 widget。请根据数据的及时性为内容使用适当的刷新率。
图 7. 天气微件可能会偶尔刷新，但天气微件会更频繁地刷新。
大小
默认主屏幕根据单元格网格定位 widget。单元格的数量、大小和间距可能因设备和启动器与启动器的不同而有很大差异。因此，务必要让 widget 保持灵活性，并能容纳比预期更多或更少的网格停靠点。考虑使用横向模式和大屏幕尺寸类别的设备。
在确定 widget 的大小时，请注意以下几点：
- 您可以为 widget 指定默认大小，并提供其大小的下限和上限。
- 使用矩形微件填充主屏幕网格上的空间。使用 Glance 进行设计时，
appWidgetBackground会提供适当的默认值来填充空间。 - 即使自由形式的 widget 是不规则的形状，也请将它们设计为在垂直和/或水平方向填充网格边界上的所有可用空间，以填充平面图。为此，请使用 [
fillMaxSize()][/reference/kotlin/androidx/glance/GlanceModifier#(androidx.glance.GlanceModifier).fillMaxSize()] 方法。
正确做法
错误做法
在设计可调整大小的 widget 时，请注意以下几点：
- 为了保持文本内容的可读性，请谨慎截断文本。
- 请考虑设置最小尺寸限制。
- 考虑如何剪裁图片以及调整图片大小。
正确做法
错误做法
图标
图标对于 widget 来说可能是关键元素，有助于在小 Surface 内实现信息和操作的有效通信。利用一组 Material 符号中提供的庞大图标库，让 widget 和主屏幕上的其他 widget 具有更高的设计一致性。
如果您的应用已包含您希望在 widget 中使用的自定义图标，请遵循设计图标原则。确保图标在小尺寸下经过简化且清晰易读。
无障碍功能
在设计 widget 时，请牢记以下无障碍功能注意事项：
- 请勿在图片上放置文字，除非文字较大且与图片背景的色彩对比度很高。
- 微件文字大小应与系统设置中的字体大小一致。
- 请勿试图通过使用较小的字体在 widget 中容纳更多内容。
- 视觉容器应反映触摸目标的实际大小。
如需更多 Android 无障碍功能提示，请访问无障碍功能。
导航
虽然用户浏览 widget 的方式与应用不同，但可以使用 widget 导航到应用中的常用操作或目的地。允许用户点按信息或内容进入应用视图以获取更多详细信息，如下图所示。
包括生成函数，或用于在应用中创建新内容（例如撰写或添加）和创建对关键用户历程的直接访问的函数，如以下电子邮件微件所示。
图 9. 邮件应用微件会显示最新的收件箱和一个撰写电子邮件的按钮。
固定
widget 固定可让用户从应用中将 widget 添加到主屏幕。启动器会显示 widget 的预览，您可以根据应用自定义该预览。这样，您就可以询问用户是否希望在应用工作流中的特定位置或任务中添加您的 widget。例如，当用户在天气应用中添加新城市时，您可以提示用户在其主屏幕上添加该城市的天气 widget。
状态
像在核心应用中一样为 widget 添加独有状态。一些可能的唯一状态包括：
- 空状态：添加提示来填充 widget 或指向生成函数的链接。空状态可以作为向新用户展示价值的机会，可以将其视为应用新手入门的类似处理方式。
图 10. 一个预填充了项的列表微件，可为新用户显示值而不是为空。
- 加载状态：添加加载状态，以指明 widget 的更新内容将很快完成加载。
- 错误状态：提供一种解决错误且传达明确消息的方式。
图 11. 包含错误消息和错误解决方法的 widget。
请勿为数据配置添加界面流。而应创建配置 activity，以允许用户访问和调整 widget 设置。
支持
准备好构建 widget 了吗？使用 Glance 创建应用 widget。