应用微件可进行配置。例如,时钟微件可让用户 配置要显示的时区。
如果您想允许用户配置微件的设置,请创建微件
配置 Activity
。此活动
在创建微件时由应用微件托管应用自动启动
或更高版本,具体取决于您之前选择的配置选项
指定。
声明配置 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>
使用AppWidgetProviderInfo.xml
android:configure
属性。查看更多信息
声明此文件。这里的示例
如何声明配置 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 传递的 ID(保存在 intent 中)
extras:
EXTRA_APPWIDGET_ID
。 - 系统不会发送
ACTION_APPWIDGET_UPDATE
并在配置 activity 启动时进行广播,这意味着它不会 在创建 widget 时调用onUpdate()
方法。 由配置 activity 负责从AppWidgetManager
。不过, 系统会针对后续更新调用onUpdate()
,只会跳过 。
有关如何返回 结果,并更新 widget。
从配置 activity 更新 widget
当 widget 使用配置 activity 时,负责
在配置完成后更新 widget 的 activity。您可以
直接从 Android Studio
AppWidgetManager
。
下面概要列出了正确更新该微件并关闭 配置活动:
从启动 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 宿主配置已取消,并 主持人未添加该微件:
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);
使用
RemoteViews
布局(通过调用updateAppWidget(int,RemoteViews)
: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();
请参阅
ListWidgetConfigureActivity.kt
获取示例。
widget 配置选项
默认情况下,应用 widget 宿主仅启动一次配置 activity, 。不过,您 可以指定相关选项,使用户能够重新配置现有的微件或 通过提供默认的 widget 配置来跳过初始 widget 配置。
允许用户重新配置已放置的微件
要允许用户重新配置现有的微件,请指定
reconfigurable
标记(位于
widgetFeatures
appwidget-provider
的属性。请参阅有关声明
AppWidgetProviderInfo.xml
文件了解详情
信息。例如:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
用户可通过触摸和按住微件并点按 重新配置按钮,该按钮标有 图 1 中的 1。
![按钮显示在右下角](https://developer.android.google.cn/static/images/appwidgets/widget-reconfigure-button.png?authuser=7&hl=fi)
使用微件的默认配置
您可以让用户跳过
初始配置步骤。为此,请指定
configuration_optional
widgetFeatures
字段中使用 reconfigurable
标志。这样会在用户添加微件后绕过启动配置 activity。如前所述
以前,用户仍然可以重新配置 widget
。例如,时钟微件可以绕过初始配置,
默认显示设备时区。
以下示例展示了如何将配置 activity 标记为 可重新配置且可选:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>