建構小工具主機

Android 主畫面適用於大多數 Android 裝置，可讓使用者嵌入應用程式小工具 (或小工具)，以便快速存取內容。如果您要建構主畫面替代應用程式或類似應用程式，也可以實作 AppWidgetHost，讓使用者嵌入小工具。大多數應用程式都不需要這麼做，但如果您要建立自己的主機，請務必瞭解主機隱含同意的合約義務。

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

以下簡要說明實作自訂 AppWidgetHost 時涉及的重要類別和概念：

  • 應用程式小工具主機：AppWidgetHost 可與 AppWidget 服務互動，適用於在 UI 中嵌入小工具的應用程式。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() 修改小工具的套件。這兩種方法都會觸發 onAppWidgetOptionsChanged() 回呼至 AppWidgetProvider。

繫結小工具

使用者將小工具新增至主機時，系統會執行「繫結」程序。繫結是指將特定應用程式小工具 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。舉例來說，許多主機會將圖示和 Widget 排列成格狀。在這個情境中，主機會預設新增小工具，並使用滿足 minWidth 和 minHeight 限制的最小儲存格數。

除了前一節列出的規定外，特定平台版本還會推出新功能，讓主機承擔新的責任。

根據目標 Android 版本決定方法

Android 12

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

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

Android 12 也會在 dps 中導入 maxResizeWidth 和 maxResizeHeight 屬性。建議使用至少一個這類屬性的動態小工具，不要超過屬性指定的尺寸。

其他資源

  • 請參閱 Glance 參考說明文件。