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

建構小工具主機

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

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

以下概述實作自訂 AppWidgetHost 時涉及的主要類別和概念：

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

繫結小工具

當使用者在主機上新增小工具時，系統會執行稱為「繫結」的程序。繫結是指將特定應用程式小工具 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> 套件，其中包含小工具例項可在選項套件中採用的可能大小清單。提供的尺寸數量取決於主機實作方式。主機通常會為手機提供兩種尺寸 (直向和橫向)，為折疊式裝置提供四種尺寸。

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

Android 12 也推出了 DPS 中的 maxResizeWidth 和 maxResizeHeight 屬性。建議使用至少一個以上這些屬性的小工具，不得超過屬性指定的大小。

其他資源

請參閱 Glance 參考說明文件。