Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

创建基本 widget

应用 widget 是可以嵌入到其他应用（例如主屏幕）中并接收定期更新的微型应用视图。这些视图在界面中称为微件，您可以使用应用微件提供程序（或微件提供程序）发布微件。容纳其他 widget 的应用组件称为应用 widget 托管应用（或 widget 托管应用）。图 1 显示了一个音乐 widget 示例：

本文档介绍了如何使用 widget 提供程序发布 widget。如需详细了解如何创建自己的 AppWidgetHost 来托管应用 widget，请参阅构建 widget 托管应用。

如需了解如何设计微件，请参阅应用微件概览。

微件组件

如需创建 widget，您需要以下基本组件：

AppWidgetProviderInfo 对象: 描述 widget 的元数据，例如 widget 的布局、更新频率和 AppWidgetProvider 类。AppWidgetProviderInfo 在 XML 中定义，如本文档中所述。
AppWidgetProvider 类: 定义了可让您以编程方式与 widget 交互的基本方法。通过它，您可以在微件更新、启用、停用或删除时接收广播。您在清单中声明 AppWidgetProvider，然后实现它，如本文档中所述。
查看布局: 定义 widget 的初始布局。布局在 XML 中定义，如本文档中所述。

图 2 展示了这些组件如何融入整体应用 widget 处理流程。

如果您的 widget 需要用户配置，请实现应用 widget 配置 activity。此 activity 可让用户修改 widget 设置，例如时钟 widget 的时区。

从 Android 12（API 级别 31）开始，您可以提供默认配置，并允许用户稍后重新配置 widget。如需了解详情，请参阅使用 widget 的默认配置和允许用户重新配置已放置的 widget。
在 Android 11（API 级别 30）或更低版本中，每次用户将 widget 添加到其主屏幕时，都会启动此 activity。

我们还建议您进行以下改进：灵活的 widget 布局、其他增强功能、高级 widget、集合 widget 以及构建 widget 宿主。

声明 AppWidgetProviderInfo XML

在传统 View 和基于 Glance 的 widget 中，定义元数据设置（例如默认单元格大小、大小调整限制和更新频率）的方式完全相同。

如需了解如何定义和配置元数据 XML 文件，请参阅 Glance 文档中的 Compose 优先声明 AppWidgetProviderInfo XML 部分。

平台的广播接收器机制、清单声明过滤器和生命周期事件循环在平台下统一。在 Compose 优先开发中，这些广播是使用 GlanceAppWidgetReceiver 封装容器进行编排的。

如需了解如何在清单中注册接收器并实现与 Hilt 兼容的生命周期替换，请参阅 Glance 文档中 Compose 优先的使用 AppWidgetProvider 类处理广播部分。

创建 widget 布局

您必须在 XML 中为微件定义初始布局，并将其保存在项目的 res/layout/ 目录中。如需了解详情，请参阅设计准则。

如果您熟悉布局，那么创建 widget 布局会非常简单。不过，请注意，微件布局基于 RemoteViews，后者不支持所有类型的布局或视图微件。您不能使用 RemoteViews 支持的视图的自定义视图或子类。

RemoteViews 还支持 ViewStub，这是一个不可见、零大小的 View，可用于在运行时延迟膨胀布局资源。

支持有状态行为

Android 12 使用以下现有组件添加了对有状态行为的支持：

微件仍然无状态。您的应用必须存储状态并注册状态更改事件。

显示有状态行为的购物清单 widget 示例 — **图 3.** 有状态行为示例。

以下代码示例展示了如何实现这些组件。

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)AppWidget.kt

提供两种布局：一种布局在 res/layout-v31 中，针对搭载 Android 12 或更高版本的设备；另一种布局在默认的 res/layout 文件夹中，针对搭载 Android 11 或更低版本的设备。

实现圆角

计算外部背景和内部比例半径是标准且共享的。在 Compose 优先开发中，可以在 Kotlin 中与自定义主题资源一起动态设置。

如需为旧版 Android 设备实现圆角半径或设置动态样式，请参阅 Glance 文档中的 Compose 优先实现圆角部分。