应用微件可进行配置。例如,时钟微件可让用户配置要显示的时区。
如果您希望允许用户配置 widget 的设置,请创建 widget 配置 Activity
。此 activity 会在创建 widget 时或之后由应用 widget 宿主自动启动,具体取决于您指定的配置选项。
声明配置 activity
在 Android 清单文件中将配置 activity 声明为常规 activity。应用 widget 宿主会通过 ACTION_APPWIDGET_CONFIGURE
操作启动它,因此 activity 需要接受此 intent。例如:
<activity android:name=".ExampleAppWidgetConfigurationActivity">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
</intent-filter>
</activity>
使用 android:configure
属性在 AppWidgetProviderInfo.xml
文件中声明 activity。如需了解详情,请参阅声明此文件。以下示例展示了如何声明配置 activity:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
...
android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
... >
</appwidget-provider>
该 activity 是使用完全限定的命名空间声明的,因为启动器从您的软件包范围之外引用它。
这就是启动配置 activity 所需的全部内容。接下来,您需要实现实际 activity。
实现配置 activity
实现 activity 时需要记住两个要点:
- 应用 widget 宿主会调用配置 activity,并且配置 activity 必须始终返回结果。结果必须包含由启动 activity 的 intent 传递的应用 widget ID(在 intent extra 中保存为
EXTRA_APPWIDGET_ID
)。 - 当配置 activity 启动时,系统不会发送
ACTION_APPWIDGET_UPDATE
广播,这意味着,在创建 widget 时,它不会调用onUpdate()
方法。首次创建 widget 时,配置 activity 负责从AppWidgetManager
请求更新。不过,后续更新会调用onUpdate()
,只有在首次更新时才会跳过。
如需查看有关如何从配置返回结果并更新 widget 的示例,请参阅下一部分中的代码段。
从配置 activity 更新 widget
当 widget 使用配置 activity 时,由该 activity 负责在配置完成后更新 widget。为此,您可以直接从 AppWidgetManager
请求更新。
下面总结了正确更新 widget 并关闭配置 activity 的过程:
从启动 Activity 的 intent 中获取应用微件 ID:
Kotlin
val appWidgetId = intent?.extras?.getInt( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
Java
Intent intent = getIntent(); Bundle extras = intent.getExtras(); int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID; if (extras != null) { appWidgetId = extras.getInt( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID); }
将 activity 结果设置为
RESULT_CANCELED
。这样,如果用户在到达结束位置之前退出 activity,则系统会通知应用 widget 宿主配置已取消,且宿主不会添加 widget:
Kotlin
val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) setResult(Activity.RESULT_CANCELED, resultValue)
Java
int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); setResult(Activity.RESULT_CANCELED, resultValue);
根据用户的偏好设置配置 widget。
配置完成后,通过调用
getInstance(Context)
获取AppWidgetManager
的实例:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
通过调用
updateAppWidget(int,RemoteViews)
使用RemoteViews
布局更新 widget:Kotlin
val views = RemoteViews(context.packageName, R.layout.example_appwidget) appWidgetManager.updateAppWidget(appWidgetId, views)
Java
RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget); appWidgetManager.updateAppWidget(appWidgetId, views);
创建返回 intent,使用 activity 结果对其进行设置,然后结束 activity:
Kotlin
val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) setResult(Activity.RESULT_OK, resultValue) finish()
Java
Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); setResult(RESULT_OK, resultValue); finish();
如需查看示例,请参阅 GitHub 上的 ListWidgetConfigureActivity.kt
示例类。
widget 配置选项
默认情况下,应用 widget 宿主只会在用户将 widget 添加到其主屏幕后立即启动配置 activity 一次。但是,您可以指定选项,使用户能够重新配置现有的 widget 或通过提供默认 widget 配置跳过初始 widget 配置。
允许用户重新配置已放置的微件
如需允许用户重新配置现有 widget,请在 appwidget-provider
的 widgetFeatures
属性中指定 reconfigurable
标志。如需了解详情,请参阅有关声明 AppWidgetProviderInfo.xml
文件的指南。例如:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
用户可以通过轻触并按住相应 widget 并点按 Reconfigure 按钮(图 1 中标记为 1)来重新配置其 widget。
使用微件的默认配置
您可以通过让用户跳过初始配置步骤来提供更顺畅的 widget 体验。为此,请在 widgetFeatures
字段中同时指定 configuration_optional
和 reconfigurable
标志。这样会在用户添加微件后绕过启动配置 activity。如前所述,用户之后仍可重新配置 widget。例如,默认情况下,时钟微件可以绕过初始配置并显示设备时区。
以下示例展示了如何将配置 activity 标记为可重新配置和可选:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>