應用程式小工具可進行設定。舉例來說,時鐘小工具可讓使用者 設定要顯示的時區。
如要允許使用者調整小工具設定,請建立小工具
「設定」圖示 Activity
。這是
應用程式小工具主機會在建立小工具時自動啟動
或之後 (視您選用的設定選項而定)
物件
宣告設定活動
在 Android 資訊清單中將設定活動宣告為一般活動
檔案。應用程式小工具主機會使用
ACTION_APPWIDGET_CONFIGURE
敬上
動作,因此活動必須接受此意圖。例如:
<activity android:name=".ExampleAppWidgetConfigurationActivity">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
</intent-filter>
</activity>
使用AppWidgetProviderInfo.xml
android:configure
屬性。進一步瞭解
宣告此檔案。這裡舉例說明
如何宣告設定活動:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
...
android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
... >
</appwidget-provider>
由於啟動器,使用完整的命名空間宣告活動 來自套件範圍之外
這就是開始設定活動所需的一切。接著需要 實際活動
實作設定活動
實作活動時,請牢記兩個重點:
- 應用程式小工具主機會呼叫設定活動以及設定
活動必須一律傳回結果。搜尋結果必須包含應用程式小工具
啟動活動的意圖所傳遞的 ID 會儲存在意圖中
附加功能
EXTRA_APPWIDGET_ID
。 - 系統不會將
ACTION_APPWIDGET_UPDATE
敬上 當系統啟動設定活動時播送,因此不會 建立小工具時,呼叫onUpdate()
方法。 設定活動負責AppWidgetManager
。不過 後續更新會被呼叫onUpdate()
,而且只會略過 一切都是從 0 開始
請參閱下一節的程式碼片段範例,瞭解如何傳回 然後更新小工具
從設定活動中更新小工具
當小工具使用設定活動時,
設定完成後,要更新小工具的活動。您可以這麼做
直接從
AppWidgetManager
。
以下簡要說明正確更新小工具並關閉 設定活動:
從啟動活動的意圖取得應用程式小工具 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); }
將活動結果設為
RESULT_CANCELED
。這樣一來,如果使用者在活動結束前退出活動, 系統會通知應用程式小工具主機,指出設定已取消,並 主機不會新增小工具:
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);
根據使用者偏好設定設定小工具。
設定完成後,請取得 呼叫
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);
建立傳回意圖,並使用活動結果設定,然後 完成活動:
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
敬上
查看範例
小工具設定選項
根據預設,應用程式小工具主機只會啟動設定活動一次。 。不過, 可指定相關選項,讓使用者重新設定現有的小工具或 提供預設的小工具設定,藉此略過初始小工具設定。
允許使用者重新設定放置的小工具
如要讓使用者重新設定現有的小工具,請指定
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=19&hl=zh-tw)
使用小工具的預設設定
您可以讓使用者略過
設定初始設定步驟方法是指定
configuration_optional
敬上
和 reconfigurable
標記。widgetFeatures
略過這個步驟
在使用者新增小工具後啟動設定活動如先前所述
先前,使用者仍可重新設定小工具
。例如,時鐘小工具可以略過初始設定,並
預設顯示裝置時區。
以下範例說明如何將設定活動標示為 可重新設定和選用:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>