應用程式小工具可進行設定。舉例來說,時鐘小工具可讓使用者設定要顯示的時區。
如果您想讓使用者調整小工具設定,請建立小工具設定 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()
進行後續更新,但只會第一次略過。
如需瞭解如何從設定傳回結果並更新小工具的範例,請參閱下一節的程式碼片段。
從設定活動中更新小工具
如果小工具使用設定活動,則在設定完成時,活動應負責更新小工具。您可以直接透過 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);
呼叫
updateAppWidget(int,RemoteViews)
,以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();
如需範例,請參閱 GitHub 上的 ListWidgetConfigureActivity.kt
範例類別。
小工具設定選項
根據預設,應用程式小工具主機只會在使用者將小工具新增至主畫面後,立即啟動設定活動一次。不過,您可以指定相關選項,讓使用者能重新設定現有的小工具,或藉由提供預設的小工具設定來略過初始小工具設定。
允許使用者重新設定放置的小工具
如要允許使用者重新設定現有的小工具,請在 appwidget-provider
的 widgetFeatures
屬性中指定 reconfigurable
標記。詳情請參閱宣告 AppWidgetProviderInfo.xml
檔案指南。舉例來說:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
使用者只要按住小工具,然後輕觸「重新設定」按鈕 (如圖 1 所示的 1),即可重新設定小工具。
使用小工具的預設設定
您可以讓使用者略過初始設定步驟,打造更流暢的小工具體驗。如要執行此操作,請在 widgetFeatures
欄位中同時指定 configuration_optional
和 reconfigurable
標記。這樣一來,就不會在使用者新增小工具後啟動設定活動。如上所述,使用者之後仍可重新設定小工具。舉例來說,時鐘小工具可以略過初始設定,並預設顯示裝置時區。
以下範例說明如何將設定活動標示為可重新設定和選用:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>