创建简单的 widget

尝试使用 Compose 方式

Jetpack Compose 是推荐用于 Android 的界面工具包。了解如何使用 Compose 样式的 API 构建 widget。

Jetpack Glance →

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

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

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

widget 组件

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

AppWidgetProviderInfo 对象

描述 widget 的元数据，如 widget 的布局、更新 频率和 AppWidgetProvider 类。 AppWidgetProviderInfo 在 XML 中定义，如 本文档中所述。

AppWidgetProvider 类

定义允许您以编程方式与 widget 连接的基本方法。通过它，您会在更新、启用、停用或删除 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

AppWidgetProviderInfo 对象定义了 widget 的基本特性。您可以使用单个 <appwidget-provider> 元素在 XML 资源文件中定义 AppWidgetProviderInfo 对象，并将其保存在项目的 res/xml/ 文件夹中。

具体可见以下示例：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

widget 大小设置属性

默认的主屏幕根据定义了高度和宽度的单元格的网格在其窗口中放置 widget。大多数主屏幕仅允许 widget 采用网格单元格的整数倍大小，例如水平方向上两个单元格，垂直方向上三个单元格。

widget 大小设置属性可让您为 widget 指定默认大小，并提供 widget 大小的下限和上限。在此上下文中，widget 的默认大小是指 widget 首次添加到主屏幕时采用的大小。

下表介绍了与 widget 大小设置相关的 <appwidget-provider> 属性：

示例

为了说明上表中属性对 widget 大小设置的影响，假设有以下规范：

• 网格单元格的宽度为 30 dp，高度为 50 dp。
• 提供了以下属性规范：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

从 Android 12 开始：

使用 targetCellWidth 和 targetCellHeight 属性作为 widget 的默认大小。

widget 的默认大小为 2x2。widget 的大小可以调整为最小 2x1 或最大 4x3。

Android 11 及更低版本：

使用 minWidth 和 minHeight 属性计算 widget 的默认大小。

默认宽度 = Math.ceil(80 / 30) = 3

默认高度 = Math.ceil(80 / 50) = 2

widget 的默认大小为 3x2。widget 的大小可以调整为最小 2x1 或最大全屏。

其他 widget 属性

下表介绍了与 widget 大小设置以外的特性相关的 <appwidget-provider> 属性。

使用 AppWidgetProvider 类处理 widget 广播

AppWidgetProvider 类处理 widget 广播，并响应 widget 生命周期事件更新 widget。以下部分介绍了如何在清单中声明 AppWidgetProvider，然后实现它。

在清单中声明 widget

首先，在应用的 AndroidManifest.xml 文件中声明 AppWidgetProvider 类，如以下示例所示：

<receiver android:name="ExampleAppWidgetProvider"
                 android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

<receiver> 元素需要 android:name 属性，该属性指定 widget 使用的 AppWidgetProvider。除非单独的进程需要向您的 AppWidgetProvider 广播，否则不得导出该组件，通常情况下不会出现这种情况。

<intent-filter> 元素必须包含带有 android:name 属性的 <action> 元素。此属性指定 AppWidgetProvider 接受 ACTION_APPWIDGET_UPDATE 广播。这是您必须明确声明的唯一一项广播。 AppWidgetManager 会根据需要自动将其他所有 widget 广播发送到 AppWidgetProvider。

<meta-data> 元素指定 AppWidgetProviderInfo 资源，并且 需要以下属性：

• android:name：指定元数据名称。使用 android.appwidget.provider 将数据标识为 AppWidgetProviderInfo 描述符。
• android:resource：指定 AppWidgetProviderInfo 资源位置。

实现 AppWidgetProvider 类

The AppWidgetProvider 类扩展了 BroadcastReceiver 作为一个 辅助类来处理 widget 广播。它仅接收与 widget 有关的事件广播，例如当更新、删除、启用和停用 widget 时发出的广播。当这些广播事件发生时，系统会调用以下 AppWidgetProvider 方法：

onUpdate()

系统会调用此方法，以按照 AppWidgetProviderInfo 中 updatePeriodMillis 属性定义的间隔更新 widget。如需了解详情，请参阅本页中介绍其他 widget 属性的表格 。

当用户添加 widget 时也会调用此方法，因此它会执行 基本设置，例如定义 View 对象的事件处理脚本或启动作业以加载要在 widget 中显示的数据。不过，如果您声明的配置 activity 没有 configuration_optional 标志，则当用户 添加 widget 时不会调用此方法，但会调用它来执行后续更新。由配置 activity 负责在配置完成后执行首次更新。如需了解详情，请参阅允许用户配置应用 widget。

最重要的回调是 onUpdate()。如需了解详情，请参阅本页中使用 处理事件 onUpdate() 类。

onAppWidgetOptionsChanged()

当首次放置 widget 时以及每当调整 widget 的大小时，会调用此方法。您可以使用此回调来根据 widget 的大小范围显示或隐藏内容。您可以通过调用getAppWidgetOptions()来获取大小范围，并且从 Android 12 开始，还可以获取 widget 实例可以采用的可能大小的列表，该方法会返回包含以下各项的 Bundle：

• OPTION_APPWIDGET_MIN_WIDTH：包含 widget 实例的宽度的下限（以 dp 为单位）。
• OPTION_APPWIDGET_MIN_HEIGHT：包含 widget 实例的高度下限（以 dp 为单位）。
• OPTION_APPWIDGET_MAX_WIDTH：包含 widget 实例的宽度上限（以 dp 为单位）。
• OPTION_APPWIDGET_MAX_HEIGHT：包含 widget 实例的高度上限（以 dp 为单位）。
• OPTION_APPWIDGET_SIZES：包含 widget 实例可以采用的可能大小 (List<SizeF>) 的列表，以 dp 为单位。此属性是在 Android 12 中引入的。

onDeleted(Context, int[])

每次从 widget 托管应用中删除 widget 时，都会调用此方法。

onEnabled(Context)

首次创建 widget 的实例时，会调用此方法。 例如，如果用户添加 widget 的两个实例，只有首次添加时会调用此方法。如果您需要打开一个新的数据库或执行只需要对所有 widget 实例执行一次的其他设置，则此方法非常合适。

onDisabled(Context)

从 widget 托管应用中删除了 widget 的最后一个实例时，会调用此方法。您应使用此方法来清理在 onEnabled(Context) 中完成的所有工作，如删除临时数据库。

onReceive(Context, Intent)

针对每个广播调用此方法，并且是在上述各个回调方法之前调用。您通常不需要实现此方法，因为默认的 AppWidgetProvider 实现会过滤所有 widget 广播并视情况调用上述方法。

您必须在 AndroidManifest 中使用 <receiver> 元素将您的 AppWidgetProvider 类实现声明为广播 接收器。如需了解详情，请参阅本页中的在清单中声明 widget。

使用 onUpdate() 类处理事件

最重要的 AppWidgetProvider 回调是 onUpdate()，因为向托管应用添加每个 widget 时都会调用它，除非您使用没有 configuration_optional 标志的配置 activity。如果您的微件接受任何用户互动事件，请在此回调中注册事件处理脚本。如果您的 widget 不会创建临时文件或数据库，或者执行需要清理的其他工作，则 onUpdate() 可能是您需要定义的唯一回调方法。

例如，如果您希望 widget 具有一个在用户点按时会启动 activity 的按钮，则可以使用以下 AppWidgetProvider 实现：

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

此 AppWidgetProvider 仅定义了 onUpdate() 方法，目的是为了使用它来 创建用于启动 Activity 的 PendingIntent，并使用 setOnClickPendingIntent(int, PendingIntent) 将其附加到 widget 的 按钮。它包含一个遍历 appWidgetIds（这是一个 ID 数组，标识由此提供程序创建的每个微件）中每个条目的循环。如果用户创建了 widget 的多个实例，则它们会全部同时更新。不过，对于 widget 的所有实例，只管理一个 updatePeriodMillis 时间表。例如，如果更新时间表定义为每两小时更新一次，并且在添加 widget 的第一个实例一小时后添加了第二个实例，则这两个实例都会按照第一个实例定义的周期进行更新，而第二个更新周期会被忽略。这两个实例都是每两小时更新一次，而不是每小时更新一次。

如需了解详情，请参阅 ExampleAppWidgetProvider.java 示例类。

接收 widget 广播 intent

AppWidgetProvider 是一个辅助类。如果您希望直接接收 widget 广播，您可以实现自己的 BroadcastReceiver 或替换 the onReceive(Context,Intent) 回调。您需要关注的 intent 如下所示：

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

创建 widget 布局

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

如果您熟悉 布局，那么创建 widget 布局非常简单。不过，请注意，widget 布局基于 RemoteViews, 并不是每种布局或视图 widget 都受其支持。您无法使用自定义视图或 RemoteViews 支持的视图的子类。

RemoteViews 还支持 ViewStub， 它是一个大小为零的不可见 View，您可以使用它在运行时以懒散的方式扩充布局 资源。

支持有状态行为

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

• CheckBox

• Switch

• RadioButton

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

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

// 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)
)

// 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));

提供两个布局：一个的目标设备搭载 Android 12 或 更高版本（在 res/layout-v31 中），另一个的目标设备搭载以前的 Android 11 或更低版本（在默认的 res/layout 文件夹中）。

实现圆角

Android 12 引入了以下系统参数来设置 widget 圆角的半径：

• system_app_widget_background_radius：widget 背景的角半径，绝不会大于 28 dp。

• 内半径，可以根据外半径和内边距计算得出。 请参阅以下代码段：

  /**
   * Applies corner radius for views that are visually positioned [widgetPadding]dp inside of the
   * widget background.
   */
  @Composable
  fun GlanceModifier.appWidgetInnerCornerRadius(widgetPadding: Dp): GlanceModifier {
  
      if (Build.VERSION.SDK_INT < 31) {
          return this
      }
  
      val resources = LocalContext.current.resources
      // get dimension in float (without rounding).
      val px = resources.getDimension(android.R.dimen.system_app_widget_background_radius)
      val widgetBackgroundRadiusDpValue = px / resources.displayMetrics.density
      if (widgetBackgroundRadiusDpValue < widgetPadding.value) {
          return this
      }
      return this.cornerRadius(Dp(widgetBackgroundRadiusDpValue - widgetPadding.value))
  }
  GlanceSnippets.kt

如需计算 widget 内部内容的合适半径，请使用以下公式： systemRadiusValue - widgetPadding

将其内容剪辑为非矩形形状的 widget 应使用 @android:id/background 作为背景视图的视图 ID，该背景视图的 android:clipToOutline 设置为 true。

有关圆角的重要注意事项

• 第三方启动器和设备制造商可以将 system_app_widget_background_radius 参数替换为小于 28 dp。

• 如果您的 widget 不使用 @android:id/background 或定义根据轮廓剪辑其内容的背景（android:clipToOutline 设置为 true），启动器会自动识别背景并使用设置为系统半径的圆角矩形剪辑 widget。

• 非矩形形状需要包含在圆角矩形 调整大小容器中，以免被剪辑。

• 从 Android 16 开始，system_app_widget_background_radius 的 AOSP 系统值为 24dp。启动器和设备制造商可以将 widget 剪辑为 system_app_widget_background_radius。

• widget 的内部内容必须具有足够的内边距，以支持高达 28dp 的 system_app_widget_background_radius 半径值，以避免圆角剪辑内容。

为了确保 widget 与以前的 Android 版本兼容，我们建议您为 Android 12 定义自定义属性并使用自定义主题替换它们，如以下示例 XML 文件所示：

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />