WindowManager 擴充功能

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

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

擴充功能模組發布

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

如要在裝置上啟用擴充功能，請將下列項目新增至產品裝置的 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 程式庫使用，這使得模組的運作方式與用戶端架構程式碼類似，如下圖所示：

androidx.window.extensions 模組是目前積極開發的擴充功能模組。androidx.window.sidecar 模組是舊版模組，包含在內是為了與最早版本的 Jetpack WindowManager 相容，但側車已不再積極維護。

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

擴充功能模組

擴充功能可為折疊式大螢幕裝置，以及支援外接螢幕分割視窗的裝置提供視窗功能。功能領域包括：

• 活動嵌入
• 視窗版面配置資訊
• 視窗區域

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

擴充功能和 Jetpack API

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

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

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

擴充功能版本和更新

擴充功能模組可隨 Android 平台每年或每季更新。透過每季更新，Android 平台 API 更新之間可增加 Extensions API 級別，加快疊代速度，並讓原始設備製造商有機會在硬體推出前，為新功能新增官方 API 存取權。

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

每當現有穩定版 API 介面 (右欄) 新增內容時，擴充功能 API 級別 (中間欄) 就會提高。

回溯和前瞻相容性

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

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

WindowManager Extensions 會實作 system_ext 模組，使用私有平台 API 呼叫 WindowManager 核心 DeviceStateManager，以及實作 Extensions 功能時的其他系統服務。

如果擴充功能是預先發布版本，且對應的 Android 平台版本尚未在季度或年度發布，則可能無法維持相容性。如要查看 Extensions API 的完整記錄，請參閱發布分支 window:extensions:extensions API 文字檔。

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

CTS 驗證可確保裝置上宣告的 Extensions API 版本，以及該版本和先前版本的所有 API 都存在且可正常運作。

效能

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

模組

活動嵌入

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

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

裝置設定

除了啟用「擴充功能」模組 (如「擴充功能模組發布」一節所述) 之外，您不必進行任何特定裝置設定。建議在支援多視窗模式的所有裝置上啟用擴充功能。在日後的 Android 版本中，常見的手持式裝置和大螢幕裝置設定可能需要使用擴充功能。

視窗版面配置資訊

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

如果可折疊式 Android 裝置的轉軸連接獨立或連續的螢幕面板區域，則必須透過 WindowLayoutComponent 向應用程式提供轉軸資訊。

鉸鏈位置和界線必須相對於應用程式視窗回報，該視窗由傳遞至 API 的 Context 識別。如果應用程式視窗的邊界與螢幕轉軸的邊界沒有交集，則不得回報螢幕轉軸 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>
  

視窗區域

視窗區域元件提供一系列功能，讓應用程式在部分摺疊式和多螢幕裝置上存取額外的螢幕和顯示區域。

後置顯示模式可讓應用程式在摺疊式裝置的封面螢幕上顯示相機預覽使用者介面，方便使用者透過主要裝置的相機自拍和錄製影片。如果裝置的螢幕與後置鏡頭對齊，且與 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 中指定狀態 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 中指定後方螢幕的實際顯示地址。
  • 如果識別碼要提供給應用程式使用，請在 com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay 中指定擴充功能要使用的狀態識別碼。
  • 在 com.android.internal.R.array.config_deviceStatesAvailableForAppRequests 中新增狀態 ID，供應用程式使用。

驗證

原始設備製造商必須驗證實作項目，確保常見情境中的行為符合預期。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 存放區的根目錄中開啟殼層。
4. 將目錄變更為 framework/support。
5. 執行下列指令：./gradlew window:window:connectedAndroidTest。
6. 分析結果。

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

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

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

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