规范 widget 布局

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

文本

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

纯文本

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

文本和图片

添加图片以增强视觉冲击力。如需了解详情，请参阅 断点 ，了解如何针对不同的屏幕尺寸调整此布局。

工具栏

使用工具栏布局，让用户可以在灵活的布局中快速访问应用中常用的任务，该布局可适应各种 widget 尺寸。

搜索工具栏

搜索工具栏布局旨在将焦点吸引到搜索 作为工具栏中的主要操作。其他便捷按钮可让用户快速访问常用功能。

工具栏

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

列表

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

文本和图片列表

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

核对清单

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

操作列表

通过操作列表提供直观的控件分组，其中视觉上的开/关 状态可立即反馈项状态。

全出血图片

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

网格

以紧凑、灵活、视觉效果丰富的网格（带有可选标签）呈现图片。 使用可适应不同屏幕尺寸的列和行。

仅图片

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

图片和文本

您还可以添加文本标签和说明，通过额外的背景信息和信息来丰富您的 图片网格内容。

代码示例

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

规范布局 参考文件 指南
操作列表布局
  • 使用 Glance 操作回调处理列表项操作，并确保正确更新状态。
列表布局
  • 使用操作参数或回调实现复选框状态切换，以更新集合项。
  • 对于 widget `onClick` 参数，使用 Glance 操作回调（例如 `actionRunCallback`、 `ActionCallback(actionParametersOf(...))` 或 `actionStartActivity(...)`）来处理点击事件，例如点按复选框。
声情工具栏布局
  • 避免 `ColorProvider` 导入错误：导入 `androidx.glance.unit.ColorProvider` 并使用 `androidx.glance.color.ColorProvider(dayColor, nightColor)`。
  • 对于纯色背景，直接使用 `GlanceModifier.background(Color)`，而不是 `ColorProvider`。
图片网格布局
  • 除非配置或请求了图片加载库，否则请对图片项使用纯色 (`GlanceModifier.background`) 或本地可绘制对象。
图片文本列表布局
  • 常见用例：新闻信息流、文章列表、锻炼历史记录、消息 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 尺寸并排或堆叠文本和图片。