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()
回呼。
繫結小工具
使用者將小工具新增至主機時,系統會顯示名為 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
中繼資料內指定預設寬度和高度。如果已指定targetCellWidth
和targetCellHeight
,則這些值會在儲存格中定義 (從 Android 12 開始);如果只指定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
參考說明文件。