借助生成的 widget 预览，您可以为 widget 创建动态的个性化预览，准确反映它们在用户主屏幕上的显示效果。它们通过推送 API 提供，这意味着您的应用可在其生命周期内的任何时间点提供预览，而无需收到来自 widget 主机的明确请求。
本指南介绍了如何为基于 Glance 的 widget 提供预览。如果您的 widget 是使用 RemoteViews 实现的，请参阅向 widget 选择器添加预览。
如需在 Android 15 及更高版本的设备上改进 Glance widget 的 widget 选择器体验，请使用 GlanceAppWidget.providePreview 提供生成的 widget 预览，并为较低版本指定 previewImage，以及在 Android 15 及更高版本上作为后备方案（如果生成的预览不可用）。
如需了解详情，请观看 YouTube 上的通过实时动态和微件丰富应用。
设置应用以生成微件预览
如需在搭载 Android 15 或更高版本的设备上显示生成的 widget 预览，请先在模块 build.gradle 文件中将 compileSdk 值设置为 35 或更高，以便在 widget 选择器中启用生成的预览。
然后，应用可以使用 GlanceAppWidgetManager 中的 setWidgetPreview。为防止滥用并缓解系统运行状况问题，setWidgetPreview 是一个速率受限的 API。默认限制为每小时大约两次调用。
使用 Jetpack Glance 生成更新后的预览
对于使用 Jetpack Glance 构建的小组件，请执行以下操作：
替换
GlanceAppWidget.providePreview函数，以便为预览提供可组合内容。与在provideGlance中一样，加载应用的数据并将其传递给 widget 的内容可组合项，使预览显示准确的数据。与provideGlance不同，这是一个单一组合，没有重组或效应。调用
GlanceAppWidgetManager.setWidgetPreviews以生成并发布预览。
系统不会通过回调来提供预览，因此您的应用必须决定何时调用 setWidgetPreviews。更新策略取决于微件的使用场景：
- 如果 widget 包含静态信息或属于快速操作，请在应用首次启动时设置预览。
- 您可以在应用有数据后（例如，在用户登录或初始设置后）设置预览。
- 您可以设置一个周期性任务，以所选频率更新预览。
排查生成的预览问题
一个常见问题是，生成预览后，预览图片中可能会缺少图片、图标或其他可组合项（相对于微件的放置尺寸）。此放置大小由 targetCellWidth 和 targetCellHeight（如果已指定）定义，或由应用 widget 提供程序信息文件中的 minWidth 和 minHeight 定义。
发生这种情况的原因是，默认情况下，Android 仅呈现以微件最小尺寸显示的可组合项。换句话说，Android 默认将 previewSizeMode 设置为 SizeMode.Single。它使用应用 widget 提供程序信息 XML 中的 android:minHeight 和 android:minWidth 来确定要绘制哪些可组合项。
如需解决此问题，请在 GlanceAppWidget 中替换 previewSizeMode 并将其设置为 SizeMode.Responsive，从而提供一组 DpSize 值。这会告知 Android 需要为预览渲染的所有布局尺寸，从而确保所有元素都能正确显示。
针对特定设备规格进行优化。请提供一到两个尺寸，从最小尺寸开始，并遵循 widget 的断点。请至少指定一个 previewImage 以支持较低的 Android 版本。您可以在微件设计指南中找到适合不同网格大小的最小 DP 值。
支持较低的 Android 版本
如需在搭载 Android 14 及更低版本的设备上显示 widget 预览，或者在搭载 Android 15 及更高版本的设备上无法生成预览时，请指定 previewImage 属性。
如果您更改了 widget 的外观，请更新预览图片。