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