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