Android 12(API 级别 31)修订了现有的小部件 API,以改进平台和启动器中的用户和开发者体验。本指南将帮助您了解如何确保您的小部件与 Android 12 兼容,并可作为刷新现有小部件 API 的参考。
确保您的小部件与 Android 12 兼容
Android 12 中的小部件具有圆角。当应用小部件在运行 Android 12 或更高版本的设备上使用时,启动器会自动识别小部件的背景并将其裁剪为圆角。
在此场景中,在以下任一情况下,您的小部件可能无法正常显示:
小部件角落包含内容:这可能导致角落区域的一些内容被裁剪。
小部件使用不易裁剪的背景:这包括透明背景、空视图或布局,或任何其他不易裁剪的特殊背景。系统可能无法正确识别要使用的背景。
如果您的小部件会受到此变更的影响,我们建议使用圆角(如以下部分所述)刷新它,以确保其正确显示。
使用示例
要查看所有这些 API 的实际应用,请查看我们的示例列表小部件。
实现圆角
Android 12 引入了system_app_widget_background_radius
和 system_app_widget_inner_radius
系统参数,用于设置您的小部件圆角半径。

1 小部件的角。
2 小部件内部视图的角。
有关详细信息,请参阅实现圆角。
添加设备主题
从 Android 12 开始,小部件可以使用设备主题颜色来显示按钮、背景和其他组件,包括浅色和深色主题。这使得不同小部件之间的过渡更平滑,一致性更高。
有关更多信息,请参阅添加设备主题。


更轻松地个性化小部件
如果您使用 appwidget-provider
的 configure
属性指定了配置 Activity,则 App Widget 主机将在用户将小部件添加到主屏幕后立即启动该 Activity。
Android 12 增加了新选项,让您为用户提供更好的配置体验。有关详细信息,请参阅让用户配置小部件。
添加新的复合按钮
Android 12 使用以下现有组件增加了对有状态行为的新支持:
小部件仍然是无状态的。您的应用必须存储状态并注册状态更改事件。

有关详细信息,请参阅支持有状态行为。
使用改进的小部件尺寸和布局 API
从 Android 12 开始,通过指定额外的小部件尺寸约束以及提供响应式布局和精确布局,您可以利用更精细的尺寸属性和更灵活的布局。
有关详细信息,请参阅提供灵活的小部件布局。
改进您应用的部件选择器体验
Android 12 通过添加动态小部件预览和小部件描述,让您能够改善应用的小部件选择器体验。有关详细信息,请参阅向小部件选择器添加可缩放的小部件预览和添加小部件描述。
实现更平滑的过渡
从 Android 12 开始,当用户从小部件启动您的应用时,启动器会提供更平滑的过渡。有关详细信息,请参阅实现更平滑的过渡。
使用简化的 RemoteViews
集合
Android 12 添加了 setRemoteAdapter(int viewId, RemoteViews.RemoteCollectionItems items)
方法,该方法允许您的应用在填充 ListView
时直接传递集合。以前,在使用 ListView
时,需要实现并声明一个 RemoteViewsService
来返回 RemoteViewsFactory
。
有关详细信息,请参阅使用 RemoteViews
集合。
使用 RemoteViews
的运行时修改
Android 12 添加了几个 RemoteViews
方法,允许在运行时修改 RemoteViews
属性。有关添加方法的完整列表,请参阅 RemoteViews
API 参考。
有关详细信息,请参阅使用 RemoteViews
的运行时修改。