本頁面由 Cloud Translation API 翻譯而成。

建構小工具主機

Android 主畫面適用於大多數 Android 裝置，可讓使用者嵌入應用程式小工具 (或小工具)，以便快速存取內容。如要建構主畫面替換項目或類似的應用程式，也可以實作 AppWidgetHost 讓使用者嵌入小工具。這並非大多數應用程式需要執行的操作，但如果您建立自己的主機，就必須瞭解主機默示同意的合約義務。

本頁主要說明導入自訂 AppWidgetHost 的相關責任。如需如何實作 AppWidgetHost 的具體範例，請查看 Android 主畫面 LauncherAppWidgetHost 的原始碼。

以下概述實作自訂 AppWidgetHost 的相關重要類別和概念：

應用程式小工具主機：對於在 UI 中嵌入小工具的應用程式，AppWidgetHost 會提供與 AppWidget 服務的互動。AppWidgetHost 必須有在主機自有套件中不重複的 ID。這個 ID 會在所有使用主機時使用。ID 通常是您在應用程式中指派的硬式編碼值。
應用程式小工具 ID：系統會在繫結時指派專屬 ID 給每個小工具執行個體。詳情請參閱 bindAppWidgetIdIfAllowed()，以及下文的「繫結小工具」一節。主機使用 allocateAppWidgetId() 取得專屬 ID。這個 ID 在小工具的生命週期內會持續存在，直到從主機刪除為止。任何主機特定狀態 (例如小工具的大小和位置) 都必須由代管套件保留，並與應用程式小工具 ID 建立關聯。
應用程式小工具主機檢視畫面：您可以將 AppWidgetHostView 視為需要顯示小工具時都會包裝的影格。每當主機加載小工具時，小工具就會與 AppWidgetHostView 建立關聯。
- 根據預設，系統會建立 AppWidgetHostView，但主機可以擴充以建立自己的 AppWidgetHostView 子類別。
- 從 Android 12 (API 級別 31) 開始，AppWidgetHostView 導入了 setColorResources() 和 resetColorResources() 方法，用於處理動態超載的顏色。主機負責為這些方法提供顏色。
選項組合：AppWidgetHost 會使用選項組合與 AppWidgetProvider 傳達小工具顯示方式的相關資訊 (例如大小範圍清單)，以及小工具是否在螢幕鎖定畫面或主畫面上。這項資訊可讓 AppWidgetProvider 根據小工具顯示的方式和位置，自訂小工具的內容和外觀。您可以使用 updateAppWidgetOptions() 和 updateAppWidgetSize() 修改小工具的套件。這兩種方法都會觸發對 AppWidgetProvider 的 onAppWidgetOptionsChanged() 回呼。

繫結小工具

當使用者在主機中新增小工具時，便會發生名為 binding 的程序。繫結是指將特定應用程式小工具 ID 與特定主機和特定 AppWidgetProvider 建立關聯。

繫結 API 也能讓主機提供用於繫結的自訂 UI。如要使用這項程序，應用程式必須在主機資訊清單中宣告 BIND_APPWIDGET 權限：

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

但這只是第一步。在執行階段，使用者必須明確授予應用程式權限，應用程式才能在主機中新增小工具。如要測試應用程式是否具備新增小工具的權限，請使用 bindAppWidgetIdIfAllowed() 方法。如果 bindAppWidgetIdIfAllowed() 傳回 false，應用程式必須顯示對話方塊，提示使用者授予權限：「允許」代表目前小工具新增項目，或設為「一律允許」，涵蓋日後所有新增的小工具。

下列程式碼片段說明如何顯示對話方塊：

Kotlin

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

主機必須檢查使用者新增的小工具是否需要設定。詳情請參閱「允許使用者設定應用程式小工具」。

主辦人責任

您可以使用 AppWidgetProviderInfo 中繼資料指定小工具的多項配置設定。您可以透過與小工具提供者相關聯的 AppWidgetProviderInfo 物件擷取這些設定選項，詳情請參閱下列各節。

無論您指定的 Android 版本為何，所有主機都有下列責任：

新增小工具時，請按照前述步驟分配小工具 ID。從主機中移除小工具時，請呼叫 deleteAppWidgetId() 來取消分配小工具 ID。
新增小工具時，請檢查是否需要啟動設定活動。一般來說，主機需要啟動小工具的設定活動 (如果有的話)，但未同時指定 configuration_optional 和 reconfigurable 旗標，將其標示為選用活動。詳情請參閱「透過設定活動更新小工具」。小工具必須先完成這個步驟，才能顯示。

注意： 在異常情況發生時，設定活動未傳回或完成並發生錯誤。
小工具會在 AppWidgetProviderInfo 中繼資料中指定預設寬度和高度。這些值是在儲存格中定義，從 Android 12 開始 (如果指定了 targetCellWidth 和 targetCellHeight 的話)；如果只指定 minWidth 和 minHeight，則會在儲存格中定義 dp。請參閱「小工具大小屬性」。

確認小工具的配置至少達到這個 dp。舉例來說，許多主機會讓格狀空間中的圖示和小工具對齊。在此情況下，根據預設，主機會根據符合 minWidth 和 minHeight 限制條件的最小儲存格數量，新增小工具。

除了上一節列出的需求外，特定平台版本還導入了為主機設置新責任的功能。

根據目標 Android 版本決定做法

Android 12

Android 12 (API 級別 31) 隨附額外的 List<SizeF>，其中包含小工具執行個體可在選項套件中採用的可用大小清單 (以 dp 為單位)。提供的大小數量取決於主機導入方式。主機通常為手機提供兩種尺寸 (直向和橫向)，而折疊式裝置則提供四種尺寸。

AppWidgetProvider 可以提供給 RemoteViews 的不同 RemoteViews 數量限制為 MAX_INIT_VIEW_COUNT (16)。由於 AppWidgetProvider 物件會將 RemoteViews 物件對應至 List<SizeF> 中的每個大小，因此請勿提供超過 MAX_INIT_VIEW_COUNT 的大小。

Android 12 也會以 dp 為單位，推出 maxResizeWidth 和 maxResizeHeight 屬性。我們建議使用至少其中一項屬性的小工具，不要超過屬性指定的大小。

其他資源

請參閱 Glance 參考說明文件。