借助生成的 widget 预览，您可以为 widget 创建动态的个性化预览，准确反映它们在用户主屏幕上的显示方式。它们通过推送 API 提供，这意味着您的应用可以在其生命周期的任何时间点提供预览，而无需接收来自 widget 主机的明确请求。
本指南介绍了如何为基于 Glance 的 widget 提供预览。如果您的 widget 是使用 RemoteViews 实现的，请参阅向 widget 选择器添加预览。
为了改进 Glance widget 的应用 widget 选择器体验，请在 Android 15 及更高版本的设备上使用 GlanceAppWidget.providePreview 提供生成的 widget 预览，并为较低版本指定 previewImage，如果生成的预览不可用，则在 Android 15 及更高版本上作为后备方案。
如需了解详情，请观看 YouTube 上的利用实时更新和 widget 丰富您的应用视频。
设置应用以进行生成的 widget 预览
如需在 Android 15 或更高版本的设备上显示生成的微件预览，请先在模块 build.gradle 文件中将 compileSdk 值设置为 35 或更高值，以便能够向微件选择器提供 RemoteViews
然后，应用可以在 GlanceAppWidgetManager 中使用 setWidgetPreview。为防止滥用并缓解系统健康问题，setWidgetPreview 是一个受速率限制的 API。默认限制为每小时大约两次。
使用 Jetpack Glance 生成更新后的预览
对于使用 Jetpack Glance 构建的 widget，请执行以下操作：
替换
GlanceAppWidget.providePreview函数以提供预览的可组合内容。与在provideGlance中一样，加载应用的数据并将其传递给 widget 的内容 composable，以使预览显示准确的数据。与provideGlance不同，这是一个没有重组或效果的单一组合。调用
GlanceAppWidgetManager.setWidgetPreviews以生成并发布预览。
系统没有提供预览的回调，因此您的应用必须决定何时调用 setWidgetPreviews。更新策略取决于微件的使用场景：
- 如果 widget 包含静态信息或属于快速操作，请在应用首次启动时设置预览。
- 您可以在应用拥有数据后（例如，在用户登录或完成初始设置后）设置预览。
- 您可以设置定期任务，以按所选频率更新预览。
排查“生成的预览”功能的相关问题
一个常见的问题是，在生成预览后，相对于 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 以实现向后兼容性。您可以在widget 设计指南中找到不同网格大小对应的适当最小 DP 值。
微件预览的向后兼容性
如需让搭载低于 Android 15 版本的设备上的 widget 选择器显示 widget 的预览，或者作为 Android 15 及更高版本上生成的预览的后备方案，请指定 previewImage 属性。
如果您更改了微件的外观，请更新预览图片。