建構小工具主機

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() 回呼。

繫結小工具

當使用者在主機上新增小工具時,系統會執行稱為「繫結」的程序。繫結是指將特定應用程式小工具 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,則會從 dps 開始。詳情請見 小工具尺寸屬性

    請確認小工具的版面配置至少有這麼多 dp。舉例來說,許多主機會將圖示和小工具排列在格子中。在這種情況下,主機預設會使用可滿足 minWidthminHeight 限制的資料欄最小數量來新增小工具。

除了前述章節列出的規定外,特定平台版本還會推出功能,將新的責任交給主機。

根據目標 Android 版本決定做法

Android 12

Android 12 (API 級別 31) 會將額外的 List<SizeF> 套件,其中包含小工具例項可在選項套件中採用的可能大小清單。提供的尺寸數量取決於主機實作方式。一般主辦人 提供兩種尺寸的手機 (直向和橫向) 及四種尺寸 適用於摺疊式裝置

不同的MAX_INIT_VIEW_COUNT RemoteViewsAppWidgetProvider提供 RemoteViews。 由於 AppWidgetProvider 物件會將 RemoteViews 物件對應至 List<SizeF> 中的每個大小,請勿提供超過 MAX_INIT_VIEW_COUNT 個大小。

Android 12 還導入了 maxResizeWidthmaxResizeHeight 以 dp 為單位建議使用至少一項屬性的小工具,不得超過屬性指定的大小。

其他資源

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