规范 widget 布局

首先确定核心内容，然后设计有效的微件布局。布局决定了信息和互动元素在 widget 中的组织方式。Android 提供了多种预构建的布局，用于工具栏、文本、列表和网格类型的 widget，以简化此流程。

文本

文字布局非常适合显示简洁明了的信息。您可以选择在文字旁边添加图片，以增强 widget 的视觉吸引力。

纯文字

非常适合用于标题、状态更新、简短说明，或任何单行文字即可有效传达信息的场景。

文字和图片

添加图片以增强视觉效果。如需了解详情，请参阅断点，了解如何使此布局适应不同的屏幕尺寸。

工具栏

使用工具栏布局，以灵活的布局（可适应各种 widget 大小）为用户提供对应用中常用任务的快速访问。

搜索工具栏

搜索工具栏布局旨在将焦点吸引到工具栏中的主要操作（即搜索）上。其他实用按钮可让您快速访问常用功能。

工具栏

工具栏显示应用品牌，后跟最常用任务的按钮，非常适合用于可切换的设置或任务链接。调整大小后，系统会隐藏不太常用的选项，以便显示更常用的操作。使用断点在有空间时添加新的最小 48dp 可点按按钮。

列表

使用列表布局以清晰、可扫描的格式整理多个项目。这非常适合新闻标题、待办事项列表或消息。将内容整理成结构化的列表，方便浏览。根据内容需求，选择容器化或无容器的演示。

文本和图片列表

可扫描的文字和图片列表非常适合展示多种类型的内容，例如新闻标题、带有专辑封面的播放列表或消息。

核对清单

核对清单布局非常适合显示任务，可为用户提供清晰的点按目标，以便用户快速将项目标记为完成。

操作列表

通过操作列表提供直观的控制分组，其中视觉上的开启/关闭状态可针对项目状态提供即时反馈。

全出血图片

此布局非常适合在 Android 17 及更高版本上展示沉浸式全出血图片，它使用贴靠滚动来确保每个子元素都与 widget 容器的高度完美对齐。

网格

以紧凑、灵活且视觉效果丰富的网格形式呈现图片，并提供可选标签。 使用可适应不同屏幕尺寸的列和行。

仅限图片

使用纯图片网格创建具有视觉冲击力的可滚动图片库。行和列会自动适应各种屏幕尺寸，以实现最佳展示效果。

图片和文字

您还可以添加文字标签和说明，为图片网格内容提供更多背景信息和内容。

代码示例

下表将每个规范布局映射到 Android 平台示例 GitHub 代码库中对应的 Jetpack Glance 实现。

规范布局 参考文件 指南
操作列表布局
  • 使用 Glance 操作回调处理列表项操作，并确保状态更新正确。
检查列表布局
  • 使用操作参数或回调实现复选框状态切换，以更新集合项。
  • 使用 Glance 操作回调（例如 `actionRunCallback`、`ActionCallback(actionParametersOf(…))` 或 `actionStartActivity(…)`）作为 widget 的 `onClick` 参数来处理点击事件，例如点按复选框。
直观的工具栏布局
  • 避免出现“ColorProvider”导入错误：导入 `androidx.glance.unit.ColorProvider` 并使用 `androidx.glance.color.ColorProvider(dayColor, nightColor)`。
  • 直接使用 `GlanceModifier.background(Color)` 设置纯色背景，而不是使用 `ColorProvider`。
图片网格布局
  • 除非已配置或请求图片加载库，否则请为图片项使用纯色 (`GlanceModifier.background`) 或本地可绘制对象。
图片文字列表布局
  • 常见应用场景：新闻 Feed、文章列表、锻炼历史记录、消息 Feed 和垂直缩略图列表。
  • 在将缩略图与主要/次要文本结合使用时，平衡列表行高和文本剪裁。
长文本布局
  • 如果您要将 `Dp` 值相乘（例如 `2 * padding`），请导入 `androidx.compose.ui.unit.times`。
  • 遵循尺寸调整规则：确保使用 `dimens.xml` 中的尺寸进行内边距和排版缩放。
搜索工具栏布局
  • 避免出现“ColorProvider”导入错误：导入 `androidx.glance.unit.ColorProvider` 并使用 `androidx.glance.color.ColorProvider(dayColor, nightColor)`。
  • 直接使用 `GlanceModifier.background(Color)` 设置纯色背景，而不是使用 ColorProvider。
全出血图片布局 / 贴靠滚动
  • 在 LazyColumn 上设置 `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` 以实现贴靠滚动。
  • 如果您实现贴靠滚动，则需要使用 Glance 1.3.0-alpha02 或更高版本、编译 SDK 37 (Baklava) 或更高版本，以及 Android Gradle 插件 (AGP) 9.1.0 或更高版本。
  • 在 widget 提供程序类中设置 `override val sizeMode: SizeMode = SizeMode.Exact`。
标准工具栏布局
  • 请参阅问题排查，避免出现“ColorProvider”导入错误：使用“androidx.glance.color.ColorProvider(dayColor, nightColor)”。
  • 直接使用 `GlanceModifier.background(Color)` 设置纯色背景，而不是使用 `ColorProvider`。
含图片的文字布局
  • 遵循自适应布局尺寸调整规则，根据可用的 widget 尺寸并排或堆叠放置文字和图片。