建構小工具主機

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，建立自己的子類別。
    • 自 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，應用程式必須顯示對話方塊，提示使用者授予權限：針對目前新增的小工具「允許」，或「一律允許」涵蓋日後新增的所有小工具。

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

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

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

主辦人責任

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

所有主辦人都必須負責下列事項：

  • 新增小工具時，請按照前述步驟分配小工具 ID。從主機移除小工具時，請呼叫 deleteAppWidgetId() 取消分配小工具 ID。

  • 新增小工具時，請檢查是否需要啟動設定活動。一般來說，如果小工具的設定活動存在，且未同時指定 configuration_optional 和 reconfigurable 標記，標示為選用，主機就必須啟動該活動。詳情請參閱「透過設定活動更新小工具」。許多小工具都必須完成這個步驟，才能顯示。

  • 小工具會在 AppWidgetProviderInfo 中繼資料中指定預設寬度和高度。這些值是以儲存格定義 (從 Android 12 開始，如果指定 targetCellWidth 和 targetCellHeight)，或以 dp 定義 (如果僅指定 minWidth 和 minHeight)。請參閱「小工具大小屬性」。

    請確保小工具的版面配置至少有這麼多 dp。舉例來說，許多主機都會在格狀檢視中對齊圖示和小工具。在這種情況下，主機預設會使用符合 minWidth 和 minHeight 限制的最小儲存格數量來新增小工具。

方法提示

除了上一節列出的規定外，請留意下列提示：

選項套件可包含 List<SizeF>，其中含有小工具例項可採用的可能大小清單 (以 dp 為單位)。提供的尺寸數量取決於主機實作。主機通常會為手機提供兩種大小 (直向和橫向)，並為折疊式裝置提供四種大小。

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

當小工具以 dp 指定 maxResizeWidth 和 maxResizeHeight 屬性時，建議使用至少其中一個屬性的小工具不要超過屬性指定的大小。

其他資源

  • 請參閱 Glance 參考文件。