大多数 Android 设备都支持 Android 主屏幕,因此
用户嵌入的应用微件(或 widget)
快速访问内容。如果您要打造主屏幕替换项或
还可以通过实现
AppWidgetHost
。大多数应用都不需要这样做,但如果您要创建自己的托管应用,请务必了解托管应用默许的约定义务。
本页重点介绍实现自定义 AppWidgetHost
所涉及的责任。有关如何实现 AppWidgetHost
的具体示例,
查看 Android 主屏幕的源代码
LauncherAppWidgetHost
。
下面简要介绍了实现自定义 AppWidgetHost
所涉及的关键类和概念:
应用微件托管应用:
AppWidgetHost
可以为要在界面中嵌入微件的应用提供与 AppWidget 服务的交互。AppWidgetHost
具有的 ID 在托管商自己的包中必须是唯一的。此 ID 会永久保留 主机的所有使用中。ID 通常是 分配。应用微件 ID:每个微件实例在绑定时都分配有一个唯一 ID。请参阅
bindAppWidgetIdIfAllowed()
以及后面的绑定微件部分,了解更多详情。托管应用使用allocateAppWidgetId()
获取此唯一 ID。此 ID 会在微件的整个生命周期内持续有效,直到它从 主机。任何主机特定的状态,例如 微件必须由托管软件包保留,并与 应用微件 ID。应用微件托管应用视图:您可以将
AppWidgetHostView
看作一个框架,每当微件需要显示时,都会封装到该框架中。每当微件由托管应用膨胀时,微件都会与AppWidgetHostView
相关联。- 默认情况下,系统会创建
AppWidgetHostView
,但主机可以通过扩展AppWidgetHostView
来创建自己的AppWidgetHostView
子类。 - 从 Android 12(API 级别 31)开始,
AppWidgetHostView
引入了setColorResources()
和resetColorResources()
方法来处理动态过载的颜色。主机是 负责为这些方法提供颜色。
- 默认情况下,系统会创建
选项包:
AppWidgetHost
使用选项包 将信息传达给AppWidgetProvider
微件的显示方式,例如 尺寸范围列表,以及 位于锁定屏幕或主屏幕上。通过这些信息,AppWidgetProvider
可根据方式和 以及它的显示位置您可以使用updateAppWidgetOptions()
和updateAppWidgetSize()
来修改 widget 的 bundle。这两种方法都会触发对AppWidgetProvider
的onAppWidgetOptionsChanged()
回调。
绑定 widget
当用户向托管应用添加 widget 时,会发生一个称为“绑定”的过程。绑定是指将特定应用微件 ID 与特定托管应用以及特定 AppWidgetProvider
关联。
通过绑定 API,主机还可以为
绑定。要使用此流程,您的应用必须声明
BIND_APPWIDGET
权限:
<uses-permission android:name="android.permission.BIND_APPWIDGET" />
但是,这只是第一步。在运行时,用户必须明确授予
权限,以允许其将 widget 添加到托管应用。要测试您的
应用有权添加 widget,请使用
bindAppWidgetIdIfAllowed()
方法。如果 bindAppWidgetIdIfAllowed()
返回 false
,则您的应用必须显示一个对话框来提示用户授予权限:对于当前添加的 widget,选择“允许”;对于将来添加的所有 widget,选择“始终允许”。
以下代码段举例说明了如何显示该对话框:
Kotlin
val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply { putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName) // This is the options bundle described in the preceding section. putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options) } startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Java
Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName); // This is the options bundle described in the preceding section. intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options); startActivityForResult(intent, REQUEST_BIND_APPWIDGET);
托管应用必须检查用户添加的微件是否需要配置。如需了解详情,请参阅允许用户配置应用微件。
托管应用的责任
您可以使用
AppWidgetProviderInfo
元数据。
您可以从与微件提供程序关联的 AppWidgetProviderInfo
对象检索这些配置选项(下文对此进行了更详细的说明)。
无论您适配的 Android 版本是什么,所有托管应用都有 以下职责:
添加微件时,请按上文所述分配微件 ID。从托管应用中移除微件后,调用
deleteAppWidgetId()
来取消分配相应的微件 ID。添加 widget 时,检查是否需要配置 activity 。通常,如果微件的配置 activity 存在且未通过同时指定
configuration_optional
和reconfigurable
标志标记为可选,则主机需要启动该 activity。如需了解详情,请参阅通过配置 activity 更新微件。对于许多微件来说,这是显示前必不可少的步骤。widget 会在
AppWidgetProviderInfo
中指定默认宽度和高度 元数据。这些值在单元格中定义,从 Android 12(如果targetCellWidth
和targetCellHeight
) 或 dps(如果仅指定了minWidth
和minHeight
)。请参阅 微件大小调整属性。请确保微件的布局中至少包含这么多 dp。例如,许多托管应用在网格中将图标与微件对齐。在这种情况下 默认情况下,托管应用会以最少数量的单元格 它们满足
minWidth
和minHeight
约束条件。
除了上一部分中列出的要求之外,特定平台版本引入的一些功能还要求托管应用承担新的责任。
根据目标 Android 版本确定方法
Android 12
Android 12(API 级别 31)捆绑了一个额外的 List<SizeF>
,其中包含微件实例在选项软件包中可以采用的可能尺寸(以 dp 为单位)的列表。所提供的尺寸数量取决于主机的实现情况。托管者通常会为手机提供两种尺寸(纵向和横向),为可折叠设备提供四种尺寸。
每个 Google 账号的MAX_INIT_VIEW_COUNT
AppWidgetProvider
可以提供的 RemoteViews
值
RemoteViews
。
由于 AppWidgetProvider
对象会将 RemoteViews
对象映射到
List<SizeF>
,则不要提供超过 MAX_INIT_VIEW_COUNT
个尺寸。
Android 12 还在 dps 中引入了 maxResizeWidth
和 maxResizeHeight
属性。我们建议使用其中至少一个属性的 widget 不超过这些属性指定的大小。
其他资源
- 请参阅
Glance
参考文档。