创建简单的 widget

应用 widget 是微型应用视图,您可以将其嵌入到其他应用(例如主屏幕)中并定期接收更新。这些视图在界面中称为 widget,您可以使用应用 widget 提供程序(或 widget 提供程序)发布一个视图。包含其他 widget 的应用组件称为应用 widget 宿主(或“widget 宿主”)。图 1 显示了一个示例音乐 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 处理流程
图 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> 属性:

属性和说明
targetCellWidthtargetCellHeight (Android 12)、minWidthminHeight
  • 从 Android 12 开始,targetCellWidthtargetCellHeight 属性会根据网格单元指定 widget 的默认大小。这些属性在 Android 11 及更低版本中会被忽略,如果主屏幕不支持基于网格的布局,则可以忽略这些属性。
  • minWidthminHeight 属性以 dp 为单位指定微件的默认大小。如果微件的最小宽度或高度的值与单元格的尺寸不匹配,则这些值将向上舍入为最接近的单元格大小。
我们建议您同时指定 targetCellWidthtargetCellHeight 以及 minWidthminHeight 这两组属性,这样,当用户的设备不支持 targetCellWidthtargetCellHeight 时,您的应用可以回退到使用 minWidthminHeight。如果支持,targetCellWidthtargetCellHeight 属性优先于 minWidthminHeight 属性。
minResizeWidthminResizeHeight 指定 widget 的绝对最小尺寸。这些值用于指定微件在多大程度上无法辨认或因其他原因而无法使用。使用这些属性,用户可以将 widget 的大小调整为小于默认 widget 大小。如果 minResizeWidth 属性大于 minWidth 或未启用水平大小调整,则系统会忽略该属性。请参阅 resizeMode。同样,如果 minResizeHeight 属性大于 minHeight 或未启用垂直大小调整,则会被忽略。
maxResizeWidthmaxResizeHeight 指定微件建议的大小上限。如果值不是网格单元格尺寸的倍数,则将其四舍五入为最接近的单元格大小。如果 maxResizeWidth 属性小于 minWidth 或者未启用水平大小调整,则会被忽略。请参阅 resizeMode。同样,如果 maxResizeHeight 属性大于 minHeight 或未启用垂直大小调整,则会被忽略。在 Android 12 中引入。
resizeMode 指定可以按什么规则调整微件的大小。您可以使用此属性让主屏幕微件在水平、垂直或两个轴上均可调整大小。用户轻触并按住某个 widget 以显示其大小调整手柄,然后拖动水平或垂直手柄以更改其在布局网格上的大小。resizeMode 属性的值包括 horizontalverticalnone。如需将 widget 声明为在水平和垂直方向上均可调整大小,请使用 horizontal|vertical

示例

为说明上表中的属性如何影响 widget 大小,假设以下规范:

  • 网格单元格的宽度为 30dp,高为 50dp。
  • 我们提供了以下属性规范:
<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 开始

使用 targetCellWidthtargetCellHeight 属性作为该 widget 的默认尺寸。

默认情况下,微件的大小为 2x2。该 widget 可以缩小到 2x1 或最大 4x3。

Android 11 及更低版本

使用 minWidthminHeight 属性计算 widget 的默认大小。

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

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

默认情况下,微件的大小为 3x2。该 widget 可以缩小到 2x1 或最大全屏。

其他微件属性

下表介绍了与 widget 大小调整以外的质量相关的 <appwidget-provider> 属性。

属性和说明
updatePeriodMillis 定义 widget 框架通过调用 onUpdate() 回调方法从 AppWidgetProvider 请求更新的频率。使用此值无法保证实际更新会准时进行,我们建议您尽可能降低更新频率(每小时不超过一次),以节省电量。 如需查看选择适当更新周期的注意事项的完整列表,请参阅更新微件内容的优化
initialLayout 指向定义 widget 布局的布局资源。
configure 定义在用户添加微件时启动的 activity,以便用户配置微件属性。请参阅允许用户配置 widget。 从 Android 12 开始,您的应用可以跳过初始配置。如需了解详情,请参阅使用微件的默认配置
description 指定为您的 widget 显示的 widget 选择器的说明。在 Android 12 中引入。
previewLayout (Android 12) 和 previewImage(Android 11 及更低版本)
  • 从 Android 12 开始,previewLayout 属性可指定可缩放的预览,并以 XML 布局形式提供该预览,并将其设置为微件的默认尺寸。理想情况下,指定为此属性的布局 XML 与具有真实默认值的实际 widget 具有相同的布局 XML。
  • 在 Android 11 或更低版本中,previewImage 属性指定微件在配置后的外观的预览,用户在选择应用微件时会看到该预览。如果未提供,则用户会看到应用的启动器图标。此字段对应于 AndroidManifest.xml 文件的 <receiver> 元素中的 android:previewImage 属性。
注意:我们建议您同时指定 previewImagepreviewLayout 属性,这样一来,当用户的设备不支持 previewLayout 时,您的应用可以回退到使用 previewImage。如需了解详情,请参阅与可缩放的 widget 预览的向后兼容性
autoAdvanceViewId 指定由 widget 托管应用自动前进的 widget 子视图的视图 ID。
widgetCategory 声明 widget 是否可以显示在主屏幕 (home_screen) 和/或锁定屏幕 (keyguard) 上。对于 Android 5.0 及更高版本,只有 home_screen 有效。
widgetFeatures 声明 widget 支持的功能。例如,如果您希望 widget 在用户添加它时使用其默认配置,请同时指定 configuration_optionalreconfigurable 标志。这样会绕过在用户添加 widget 后启动配置 activity。之后,用户仍然可以重新配置 widget

使用 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 类

AppWidgetProvider 类扩展了 BroadcastReceiver 作为处理 widget 广播的便捷类。它仅接收与 widget 相关的事件广播,例如当 widget 更新、删除、启用和停用时。当发生这些广播事件时,系统会调用以下 AppWidgetProvider 方法:

onUpdate()
调用此方法可按照 AppWidgetProviderInfo 中的 updatePeriodMillis 属性定义的间隔更新 widget。如需了解详情,请参阅本页中描述其他微件属性的表
用户添加 widget 时也会调用此方法,因此它会执行基本的设置,例如为 View 对象定义事件处理脚本,或启动作业以加载数据以在 widget 中显示。不过,如果您声明的配置 activity 不带 configuration_optional 标志,则当用户添加 widget 时,系统不会调用此方法,但会针对后续更新调用此方法。配置 activity 应负责在配置完成后执行首次更新。如需了解详情,请参阅允许用户配置应用微件
最重要的回调是 onUpdate()。如需了解详情,请参阅本页中的使用 onUpdate() 类处理事件
onAppWidgetOptionsChanged()

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

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(),因为除非您使用不带 configuration_optional 标志的配置 activity,否则在将每个 widget 添加到宿主时都会调用该回调。如果您的 widget 接受任何用户互动事件,请在此回调中注册事件处理脚本。如果您的 widget 不会创建临时文件或数据库,或执行其他需要清理的工作,那么 onUpdate() 可能是您需要定义的唯一回调方法。

例如,如果您需要一个带有按钮的 widget,该按钮可在点按时启动 activity,则可以使用以下 AppWidgetProvider 实现:

Kotlin

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

Java

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 并使用 setOnClickPendingIntent(int, PendingIntent) 将其附加到微件按钮的 PendingIntent。它包含一个循环遍历 appWidgetIds 中的每个条目,该循环是 ID 数组,用于标识此提供程序创建的每个 widget。如果用户创建多个 widget 实例,那么这些实例将全部同时更新。但是,只能为微件的所有实例管理一个 updatePeriodMillis 时间表。例如,如果将更新时间表定义为每两小时更新一次,并且在第一个实例一小时后添加了该 widget 的第二个实例,那么这两个实例都会根据第一个更新周期定义的更新周期进行更新,而忽略第二个更新周期。两者每两小时更新一次,而不是每小时更新一次。

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

接收 widget 广播 intent

AppWidgetProvider 是一个便捷类。如果您想直接接收 widget 广播,可以实现自己的 BroadcastReceiver 或替换 onReceive(Context,Intent) 回调。您需要关注的 intent 如下:

创建 widget 布局

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

如果您熟悉布局,那么创建 widget 布局将非常简单。但请注意,widget 布局基于 RemoteViews,并不支持所有类型的布局或视图 widget。您无法使用自定义视图或 RemoteViews 支持的视图子类。

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

支持有状态行为

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

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

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

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

Kotlin

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

Java

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

res/layout-v31 中提供两个布局:一个以搭载 Android 12 或更高版本的设备为目标平台,另一个以旧版 Android 11 或更低版本在默认的 res/layout 文件夹中提供。

实现圆角

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

以下示例展示了一个微件,为微件的角使用 system_app_widget_background_radius,而为微件内的视图使用 system_app_widget_inner_radius

显示 widget 背景和 widget 内视图的半径的 widget
图 4. 圆角。

1 微件的角。

2 微件内视图的角。

有关圆角的重要注意事项

  • 第三方启动器和设备制造商可以替换 system_app_widget_background_radius 参数,使其小于 28 dp。system_app_widget_inner_radius 参数始终比 system_app_widget_background_radius 的值小 8 dp。
  • 如果您的 widget 不使用 @android:id/background,也不定义根据轮廓裁剪其内容的背景(将 android:clipToOutline 设置为 true),则启动器会自动识别背景,并使用圆角不超过 16 dp 的矩形裁剪 widget。请参阅确保 widget 与 Android 12 兼容

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

/values/attrs.xml

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

/values/styles.xml

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

/values-31/styles.xml

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

/drawable/my_widget_background.xml

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

/layout/my_widget_layout.xml

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