此页面由 Cloud Translation API 翻译。

构建 widget 托管应用

大多数 Android 设备都提供 Android 主屏幕，用户可在该屏幕上嵌入应用微件（或微件），以便快速访问内容。如果您要打造主屏幕替换项或还可以通过实现 AppWidgetHost。大多数应用都不需要这样做，但如果您要创建自己的托管应用，请务必了解托管应用默许的约定义务。

本页重点介绍实现自定义 AppWidgetHost。如需查看有关如何实现 AppWidgetHost 的具体示例，请参阅 Android 主屏幕 LauncherAppWidgetHost 的源代码。

下面简要介绍了实现自定义 AppWidgetHost 所涉及的关键类和概念：

应用 widget 宿主：AppWidgetHost 提供与应用 widget 的互动， AppWidget 服务，适用于在界面中嵌入 widget 的应用。AppWidgetHost 必须具有一个在托管应用自己的软件包中独一无二的 ID。此 ID 会永久保留主机的所有使用中。ID 通常是分配。
应用微件 ID：每个微件实例在绑定时都分配有一个唯一 ID。请参阅 bindAppWidgetIdIfAllowed() 以及后面的绑定微件部分，了解更多详情。通过托管商使用 allocateAppWidgetId()。此 ID 会在微件的整个生命周期内持续有效，直到它从主机。任何主机特定的状态，例如微件必须由托管软件包保留，并与应用微件 ID。
应用微件托管应用视图：您可以考虑使用 AppWidgetHostView以框架形式显示该 widget 会在需要显示时被封装。每当微件由托管应用膨胀时，微件都会与 AppWidgetHostView 相关联。
- 默认情况下，系统会创建一个 AppWidgetHostView，但主机可以通过扩展 AppWidgetHostView 来创建自己的 AppWidgetHostView 子类。
- 从 Android 12（API 级别 31）开始，AppWidgetHostView 引入了该 setColorResources() 和 resetColorResources() 用于处理动态过载颜色的方法。托管应用负责向这些方法提供颜色。
选项包：AppWidgetHost 使用选项包将有关如何显示微件的信息（例如大小范围列表）以及微件是在锁定屏幕上还是在主屏幕上的信息传达给 AppWidgetProvider。利用此信息，AppWidgetProvider 可以根据微件的显示方式和显示位置来量身定制微件的内容和外观。您可以使用 updateAppWidgetOptions() 和 updateAppWidgetSize() 来修改微件的软件包。这两种方法都会触发 onAppWidgetOptionsChanged() 对 AppWidgetProvider 进行回调。

绑定 widget

当用户向托管应用添加 widget 时，会发生一个称为“绑定”的过程。绑定是指将特定应用微件 ID 与特定托管应用及具体的 AppWidgetProvider。

绑定 API 还使托管应用能够提供用于绑定的自定义界面。如需使用此流程，您的应用必须在宿主清单中声明 BIND_APPWIDGET 权限：

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

但是，这只是第一步。在运行时，用户必须明确向您的应用授予权限，才能让它将微件添加到托管应用。如需测试您的应用是否具有添加微件的权限，请使用 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 与 widget 提供程序相关联的对象。

无论您以哪个 Android 版本为目标平台，所有托管应用都有以下责任：

添加微件时，请按上文所述分配微件 ID。从托管应用中移除微件后，调用 deleteAppWidgetId() 来取消分配相应的微件 ID。
添加微件时，请检查是否需要启动配置 activity。通常，托管应用需要启动 widget 的配置（如果存在）且未通过同时指定 configuration_optional 和 reconfigurable 标志。请参阅从配置 activity 更新 widget 了解详情。对于许多微件来说，这是一个必要的步骤，执行此步骤后，才能显示这些微件。

注意：处理配置 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 还引入了 maxResizeWidth 和 maxResizeHeight 属性（以 dps 为单位）。我们建议使用其中至少一个属性的 widget 不超过这些属性指定的大小。

其他资源

请参阅 Glance 参考文档。