建構小工具主機

Android 主畫面適用於大多數 Android 裝置 使用者嵌入應用程式小工具 (或小工具)， 快速存取內容。如果您要更換主畫面 但也可以讓使用者嵌入小工具 AppWidgetHost。這並不是 大部分應用程式需要執行的作業，但如果您是自行建立主機， 請務必瞭解主辦人隱含同意的合約義務。

本頁重點說明導入自訂機器類型的相關責任 AppWidgetHost。如需如何實作 AppWidgetHost 的特定範例 請查看 Android 主畫面的原始碼 LauncherAppWidgetHost。

以下簡要說明導入 自訂 AppWidgetHost：

  • 應用程式小工具主機：AppWidgetHost 會提供與 AppWidget 服務，適用於在 UI 中嵌入小工具的應用程式。AppWidgetHost 必須在主機自有套件中取得專屬的 ID。這個 ID 仍然存在 跨主機的運作這個 ID 通常是硬式編碼值 為應用程式指派專屬角色

  • 應用程式小工具 ID：系統會在每次小工具執行個體指派專屬 ID 具有約束力詳情請見 bindAppWidgetIdIfAllowed()敬上 詳情請參閱後面的「繫結小工具」部分。 主機取得專屬 ID allocateAppWidgetId()。 這個 ID 在整個小工俱生命週期內持續存在，直到您從 主機。任何特定主機的狀態，例如 小工具，必須由代管套件持續存在，並與 應用程式小工具 ID。

  • 應用程式小工具代管檢視畫面： AppWidgetHostView 為頁框 每當需要顯示小工具時，就會包入小工具。小工具是 與 AppWidgetHostView 關聯 主機。

    • 根據預設，系統會建立 AppWidgetHostView，但主機可以 透過擴充來建立自己的 AppWidgetHostView 子類別。
    • 從 Android 12 (API 級別 31) 開始，AppWidgetHostView 會導入 這個 setColorResources() 和 resetColorResources() 處理動態超載顏色的方法。主機 負責為這些方法提供顏色

  • 選項套裝組合：AppWidgetHost 會使用選項套裝組合： 將資訊提供給 AppWidgetProvider。 關於小工具的顯示方式 (例如 大小範圍清單，以及 。有了這些資訊 AppWidgetProvider 可根據如何自訂小工具的內容和外觀 顯示這些資訊的位置。別擔心！您可以使用 updateAppWidgetOptions()敬上 和 updateAppWidgetSize()。 修改小工具的套裝組合。這兩種方法都會觸發 onAppWidgetOptionsChanged()敬上 AppWidgetProvider 回呼。

繫結小工具

當使用者在主機中新增小工具時，便會發生名為 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 中指定預設寬度和高度 中繼資料。這些值已在儲存格中定義，從 Android 12 (如果 targetCellWidth 和 targetCellHeight 為 ；如果僅指定 minWidth 和 minHeight，則為 dp。詳情請見 小工具尺寸屬性：

    確認小工具的配置至少達到這個 dp。適用對象 例如，許多主機會對齊格狀中的圖示和小工具。在這個範例中 預設主機會新增小工具時，採用的儲存格數量下限 滿足 minWidth 和 minHeight 限制條件。

除了上一節列出的規定外， 平台版本導入的功能，在 主機。

根據目標 Android 版本決定做法

Android 12

Android 12 (API 級別 31) 會隨附含有清單的額外 List<SizeF> 小工具執行個體可在選項套件中使用的可用大小 (以 dp 為單位)。 提供的大小數量取決於主機導入方式。一般主辦人 提供兩種尺寸的手機 (直向和橫向) 及四種尺寸 適用於摺疊式裝置

不同的MAX_INIT_VIEW_COUNT RemoteViews，AppWidgetProvider可提供給 RemoteViews。 由於 AppWidgetProvider 物件會將 RemoteViews 物件對應至 List<SizeF>，請勿提供超過 MAX_INIT_VIEW_COUNT 種大小。

Android 12 還導入了 maxResizeWidth敬上 和 maxResizeHeight。 以 dp 為單位我們建議小工具至少使用下列其中一個 屬性不超出屬性指定的大小。

其他資源

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