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
參考說明文件。