WindowManager 擴充功能

Jetpack WindowManager 程式庫可讓應用程式開發人員支援新的裝置板型規格和多視窗環境。

WindowManager Extensions (Extensions) 是可選擇加入的 Android 平台模組，可啟用各種 Jetpack WindowManager 功能。這個模組已在 frameworks/base/libs/WindowManager/Jetpack 的 Android 開放原始碼計畫中實作，並在支援 WindowManager 功能的裝置上發布。

擴充功能模組分發

如果裝置 makefile 中已啟用擴充功能，系統會將擴充功能編譯為 .jar 程式庫，並放置在裝置的 system_ext 分區中。

如要在裝置上啟用 Extensions，請將下列內容加入產品裝置的 makefile：

$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)

這會在裝置上啟用 androidx.window.extensions 和 androidx.window.sidecar 套件，並設定 persist.wm.extensions.enabled 屬性。在 makefile 中加入這些套件也會在 etc/permissions/ 中放置宣告，讓應用程式程序可以使用這些宣告。一般來說，當 Jetpack WindowManager 程式庫使用模組時，會在執行階段將模組載入並執行，做為應用程式程序的一部分，這會使其運作方式類似於用戶端程式庫程式碼，如以下圖所示：

圖 1. 類似於平台程式碼，WindowManager 擴充功能會載入至應用程式程序。

androidx.window.extensions 模組是目前正在積極開發中的 Extensions 模組。androidx.window.sidecar 模組是為了與最早期的 Jetpack WindowManager 版本相容而納入的舊版模組，但副駕駛已不再積極維護。

下圖顯示決定使用 androidx.window.extensions 或 androidx.window.sidecar 的邏輯。

圖 2. 用於存取 androidx.window.extensions 或 androidx.window.sidecar 的決策樹。

擴充功能模組

擴充功能可為摺疊式大螢幕裝置和支援在外接螢幕上執行視窗功能的裝置提供視窗功能。這些功能領域包括：

如果裝置硬體不支援對應的功能，擴充功能的 OEM 實作可以提供空值元件，或是在 WindowExtensions 介面中實作方法的預設或存根目錄實作，除非該功能是根據 相容性定義文件 (CDD) 7.1.1.1 的規定特別要求。

Extensions 和 Jetpack API

除了公開平台 API 之外，WindowManager Extensions 模組也會提供自己的 API 介面。擴充功能模組是在非開發人員專用的 androidx.window.extensions Jetpack 程式庫中公開開發，因此 Jetpack WindowManager (androidx.window) 可以在編譯時連結至該程式庫。Extensions API 介面通常會提供較低層級的 API。

擴充功能提供的 API 僅供 Jetpack WindowManager 程式庫使用。應用程式開發人員不應直接呼叫 Extensions API。為確保功能正確運作，請勿在 Gradle 建構檔案中將 Extensions 程式庫新增為應用程式的依附元件。請勿直接將 Extensions 程式庫預先編譯到應用程式中，而是請依賴執行階段載入作業，以免載入預先編譯和執行階段提供的 Extensions 類別混合情況。

Jetpack WindowManager (androidx.window) 應新增為應用程式依附元件，並提供面向開發人員的公開 API，包括 WindowManager 擴充功能功能的 API。WindowManager 程式庫會自動將 Extensions 載入應用程式程序，並將較低層級的 Extensions API 包裝為較高層級的抽象項目和更專注的介面。WindowManager Jetpack API 遵循現代 Android 應用程式開發標準，旨在與使用其他 AndroidX 程式庫的程式碼集完美整合，提供便利的互通性。

擴充功能版本和更新

擴充功能模組可隨著 Android 平台的年度或季度更新一併更新。季度更新可讓 Extensions API 級別在 Android 平台 API 更新之間提升，加快迭代作業，並讓原始設備製造商有時間在硬體推出前，為新功能新增官方 API 存取權。

下表列出各種 Android 版本的 androidx.window.extensions API 版本。

Android 平台版本 WindowManager Extensions API 級別 androidx.window.extensions API 版本
Android 15 6 1.5.0 (即將推出)
Android 14 QPR3 5 1.4.0 (即將推出)
Android 14 QPR1 4 1.3.0
Android 14 3 1.2.0
Android 13 QPR3 2 1.1.0
Android 13 1 1.0.0
Android 12L 1 1.0.0

每當現有穩定 API 途徑 (右欄) 新增內容，Extensions API 級別 (中間欄) 就會提升。

回溯相容性和前瞻相容性

Jetpack WindowManager 可處理頻繁的 API 級別更新、快速的 API 演進，以及回溯相容性等複雜問題。在應用程式程序中執行程式庫程式碼時，程式庫會檢查宣告的 Extensions API 級別，並根據宣告的級別提供功能存取權。

為避免應用程式在執行階段發生當機情形，WindowManager 也會根據宣告的 Extensions API 級別，對可用的 Extensions API 執行執行階段 Java 反射檢查。如果不相符，WindowManager 可以停用 (部分或完全) 使用擴充功能，並回報相關功能無法供應用程式使用。

WindowManager Extensions 會以 system_ext 模組的形式實作，該模組會使用私人平台 API 呼叫 WindowManager 核心、DeviceStateManager 和其他系統服務，以實作 Extensions 功能。

在相應的季度或年度 Android 平台版本發布前，Extensions 的預先發布版可能無法維持相容性，因為這些版本會在該版本定案後發布。如要查看 Extensions API 的完整歷程記錄，請前往發布分支的 window:extensions:extensions API 文字檔案。

新版 Extensions 必須繼續與編譯至應用程式的舊版 WindowManager 搭配運作，以維持向前相容性。為確保這項功能，Extensions API 的任何新版本都只會新增新的 API，不會移除舊版 API。因此，採用舊版 WindowManager 的應用程式可以繼續使用應用程式編譯時所用的舊版 Extensions API。

CTS 驗證可確保裝置上任何已宣告的 Extensions API 版本，都包含該版本和先前版本的所有 API，且這些 API 都能正常運作。

成效

從 Android 14 (API 級別 34) 開始，系統預設會在非啟動類別路徑的系統類別載入器中快取 Extensions 模組，因此在應用程式啟動時將模組載入記憶體，不會對效能造成影響。在用戶端和伺服器之間執行額外的 IPC 呼叫時，使用個別模組功能可能會對應用程式的效能特性造成輕微影響。

模組

活動嵌入

活動嵌入元件可讓應用程式針對大螢幕裝置和外接螢幕最佳化使用者介面。活動嵌入功能可讓兩個活動在多窗格版面中並排顯示，方便為舊版應用程式開發自動調整式應用程式。

活動嵌入元件必須可用於所有內建螢幕尺寸等於或大於 sw600dp 的裝置。在支援外接螢幕連線的裝置上，也必須啟用活動嵌入功能，因為在執行階段連線外接螢幕時，應用程式可能會以較大的尺寸顯示。

裝置設定

除了啟用「擴充功能模組」一節所述的擴充功能模組，您不需要進行其他裝置設定。在支援多視窗模式的所有裝置上啟用擴充功能是合理的做法。日後的 Android 版本可能會要求在常見的手持裝置和大螢幕裝置設定中使用擴充功能。

視窗版面配置資訊

當折疊式裝置的轉軸跨越應用程式視窗時，視窗版面配置資訊元件會識別轉軸的位置和狀態。窗格版面配置資訊可讓應用程式在折疊式裝置的桌面模式中，回應並顯示最佳化的版面配置。如要瞭解使用詳情，請參閱「讓應用程式適用摺疊式裝置」。

折疊式 Android 裝置如果包含可連接分離或連續顯示面板區域的轉軸，則必須透過 WindowLayoutComponent 將轉軸資訊提供給應用程式。

樞紐位置和邊界必須相對於由 Context 傳遞至 API 的應用程式視窗來回報。如果應用程式視窗邊界未與樞紐邊界相交，則樞紐 DisplayFeature 不得回報。如果位置無法可靠地回報，例如使用者可在多視窗模式或相容性上下黑邊模式下自由移動應用程式視窗，則也可以選擇不回報顯示功能。

對於折疊功能，當轉軸位置在穩定狀態之間變更時，必須回報狀態更新。根據預設，在平面顯示狀態下，API 必須回報 FoldingFeature.State.FLAT。如果裝置硬體可在穩定狀態下處於半摺疊模式，API 就必須回報 FoldingFeature.State.HALF_OPENED。API 中沒有關閉狀態，因為在這種情況下，應用程式視窗將不會顯示，或不會跨越樞紐邊界。

裝置設定

如要支援折疊功能的實作，原始設備製造商必須執行下列操作：

  • 將 device_state_configuration.xml 中的裝置狀態設為由 DeviceStateManagerService 使用。請參閱 DeviceStateProviderImpl.java 相關說明。

    如果 DeviceStateProvider 或 DeviceStatePolicy 的預設實作方式不適合裝置，您可以使用自訂實作方式。

  • 按照「擴充功能模組發布」一節的說明啟用擴充功能模組。

  • 在 com.android.internal.R.string.config_display_features 字串資源中指定顯示功能的位置 (通常是裝置疊加畫面的 frameworks/base/core/res/res/values/config.xml)。

    字串的預期格式為：

    <type>-[<left>,<top>,<right>,<bottom>]

    type 可以是 fold 或 hinge。left、top、right 和 bottom 的值是自然顯示方向的顯示座標空間中的整數像素座標。設定字串可包含多個顯示功能，並以分號分隔。

    例如：

    <!-- Jetpack WindowManager display features -->
<string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>

  • 定義 DeviceStateManager 中使用的裝置內部狀態 ID 與 com.android.internal.R.array.config_device_state_postures 中傳送給開發人員的公開狀態常數之間的對應關係。

    每個項目的預期格式如下：

    <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

    支援的狀態 ID 如下：

    • COMMON_STATE_NO_FOLDING_FEATURES = 1：狀態沒有可回報的摺疊功能。例如，這是典型內折裝置的關閉狀態，主螢幕位於內側。
    • COMMON_STATE_HALF_OPENED = 2：折疊功能處於半開狀態。
    • COMMON_STATE_FLAT = 3：折疊功能是平的。舉例來說，這可以是典型內折式裝置的開啟狀態，內側有主螢幕。
    • COMMON_STATE_USE_BASE_STATE = 1000：在 Android 14 中，這個值可用於模擬狀態，其中鉸鏈狀態是使用基本狀態衍生而來，如 CommonFoldingFeature.java 中所定義

    詳情請參閱 DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int)。

    例如：

    <!-- Map of System DeviceState supplied by DeviceStateManager to WindowManager posture.-->
<string-array name="config_device_state_postures" translatable="false">
  <item>0:1</item>    <!-- CLOSED       : COMMON_STATE_NO_FOLDING_FEATURES -->
  <item>1:2</item>    <!-- HALF_OPENED  : COMMON_STATE_HALF_OPENED -->
  <item>2:3</item>    <!-- OPENED       : COMMON_STATE_FLAT -->
  <item>3:1</item>    <!-- REAR_DISPLAY : COMMON_STATE_NO_FOLDING_FEATURES -->
  <item>4:1000</item> <!-- CONCURRENT   : COMMON_STATE_USE_BASE_STATE -->
</string-array>

視窗區域

視窗區域元件提供一組功能，可讓應用程式存取部分摺疊式和多螢幕裝置的其他螢幕和顯示區域。

後置顯示模式可讓應用程式在摺疊式裝置的封面螢幕上顯示相機預覽 UI，以便使用裝置的主要相機拍攝自拍照和影片。如果裝置具有與 Android 相容 (根據 Android CDD 定義的屬性，例如大小、密度和可用的導覽操作元素) 的封面螢幕，且與後置裝置相機對齊，則必須提供後置顯示模式存取權。

在 Android 14 中，雙螢幕模式可讓在摺疊式裝置內螢幕上執行的應用程式，在面向其他使用者的封面螢幕上顯示額外內容；舉例來說，封面螢幕可以向正在拍照或錄影的使用者顯示相機預覽畫面。

裝置設定

如要支援折疊功能的實作，原始設備製造商必須執行下列操作：

  • 將 device_state_configuration.xml 中的裝置狀態設為由 DeviceStateManagerService 使用。詳情請參閱 DeviceStateProviderImpl.java。

    如果 DeviceStateProvider 或 DeviceStatePolicy 的預設實作方式不適合裝置，您可以使用自訂實作方式。

  • 針對支援開啟或平放模式的可折疊式裝置，請在 com.android.internal.R.array.config_openDeviceStates 中指定對應的狀態 ID。

  • 對於支援折疊狀態的折疊式裝置，請在 com.android.internal.R.array.config_foldedDeviceStates 中列出對應的狀態 ID。

  • 如果是支援半折疊狀態的折疊式裝置 (轉軸處處於半開狀態，如同筆記型電腦)，請在 com.android.internal.R.array.config_halfFoldedDeviceStates 中列出對應狀態。

  • 針對支援後置顯示模式的裝置：

    • 在 com.android.internal.R.array.config_rearDisplayDeviceStates 中列出 DeviceStateManager 的對應狀態。
    • 在 com.android.internal.R.string.config_rearDisplayPhysicalAddress 中指定後置顯示器的實際顯示位址。
    • 在 com.android.internal.R.integer.config_deviceStateRearDisplay 中指定要供 Extensions 使用的狀態 ID。
    • 在 com.android.internal.R.array.config_deviceStatesAvailableForAppRequests 中新增狀態 ID，讓應用程式可以使用。

  • 在 Android 14 上，如果裝置支援雙重 (並行) 顯示模式：

    • 將 com.android.internal.R.bool.config_supportsConcurrentInternalDisplays 設為 true。
    • 在 com.android.internal.R.config_deviceStateConcurrentRearDisplay 中指定後置顯示器的實際顯示位址。
    • 如果 ID 可供應用程式使用，請在 com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay 中指定要由擴充功能使用的狀態 ID。
    • 在 com.android.internal.R.array.config_deviceStatesAvailableForAppRequests 中新增狀態 ID，讓應用程式可以使用。

驗證

原始設備製造商 (OEM) 必須驗證其實作方式，確保在常見情境中顯示預期行為。原始設備製造商 (OEM) 可使用 CTS 測試和使用 Jetpack WindowManager 的測試來測試實作。

CTS 測試

如要執行 CTS 測試，請參閱「執行 CTS 測試」。與 Jetpack WindowManager 相關的 CTS 測試位於 cts/tests/framework/base/windowmanager/jetpack/ 下方。測試模組名稱為 CtsWindowManagerJetpackTestCases。

WindowManager 測試

如要下載 Jetpack WindowManager 測試，請按照 Android Jetpack 操作說明操作。這些測試位於 window:window 模組下的視窗程式庫中：window/window/src/androidTest/。

如要透過指令列為 window:window 模組執行裝置測試，請執行下列操作：

  1. 插入已啟用開發人員選項和 USB 偵錯功能的裝置。
  2. 允許電腦偵錯裝置。
  3. 在 androidx 存放區的根目錄中開啟 Shell。
  4. 將目錄變更為 framework/support。
  5. 執行下列指令：./gradlew window:window:connectedAndroidTest。
  6. 分析結果。

如要透過 Android Studio 執行測試，請按照下列步驟操作：

  1. 開啟 Android Studio。
  2. 插入已啟用開發人員選項和 USB 偵錯功能的裝置。
  3. 允許電腦偵錯裝置。
  4. 前往視窗模組的視窗程式庫中進行測試。
  5. 開啟測試類別，然後使用編輯器右側的綠色箭頭執行測試。

或者，您也可以在 Android Studio 中建立設定，以便執行測試方法、測試類別或模組中的所有測試。

您可以查看殼層的輸出內容，手動分析結果。如果裝置不符合特定假設，系統會略過部分測試。結果會儲存在標準位置，分析師可以編寫指令碼，自動分析結果。