建構小工具主機

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() 修改小工具的套件。這兩種方法都會觸發對 AppWidgetProvideronAppWidgetOptionsChanged() 回呼。

繫結小工具

使用者將小工具新增至主機時,系統會顯示名為 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_optionalreconfigurable 標記,而未標示為可選用。詳情請參閱「透過設定活動更新小工具」。對於許多小工具而言,這是必要步驟。

  • 小工具會在 AppWidgetProviderInfo 中繼資料內指定預設寬度和高度。如果已指定 targetCellWidthtargetCellHeight,則這些值會在儲存格中定義 (從 Android 12 開始);如果只指定 minWidthminHeight,則為 dp。請參閱「小工具大小屬性」。

    確認小工具至少配置了這個 dp 的大小。舉例來說,許多主機會對齊格狀中的圖示和小工具。在這種情況下,主機預設會使用符合 minWidthminHeight 限制條件的儲存格數量下限來新增小工具。

除了上一節列出的要求外,特定平台版本還導入了一些功能,可在主機上放置新工作。

根據指定的 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 為單位導入 maxResizeWidthmaxResizeHeight 屬性。建議,如果小工具使用至少一項這類屬性,就不會超過屬性指定的大小。

其他資源

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