本頁面由 Cloud Translation API 翻譯而成。

WindowManager 擴充功能

Jetpack WindowManager 程式庫可讓應用程式開發人員支援新的裝置板型規格，多視窗模式的自動化功能

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

擴充功能模組發布管道

擴充功能會編譯至 .jar 程式庫，並放在 system_ext 中則會在裝置 makefile 中啟用擴充功能。

如要在裝置上啟用擴充功能，請將下列指令新增至產品裝置 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 模組是「擴充功能」模組，位於以下位置：積極開發應用程式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。

擴充功能和 Jetpack API

除了原有的 WindowManager 模組外，WindowManager 擴充功能也提供其專屬的 API 介面公開平台 APIExtensions 模組是公開在非開發人員適用的 androidx.window.extensions Jetpack 程式庫，因此 Jetpack WindowManager (androidx.window) 且能在編譯期間連結至該網址通常擴充功能 API 介面並提供較低階 API

擴充功能提供的 API 必須由 Jetpack 使用僅限 WindowManager 程式庫。Extensions API 不會應用程式開發人員無法將擴充功能程式庫新增為 Gradle 建構檔案中應用程式的依附元件，確保正確無誤功能。避免將擴充功能程式庫預先編譯到應用程式 directly;請依據執行階段載入，避免發生載入混合情形的情況預先編譯和執行階段提供的 Extensions 類別所組成

Jetpack WindowManager (androidx.window) 預計會新增為應用程式並提供向開發人員提供的公開 API，包括，瞭解 WindowManager 擴充功能有哪些功能WindowManager 程式庫會自動將擴充功能載入應用程式程序，並納入運用擴充功能 API 建構更高層次的抽象層存取 APIWindowManager Jetpack API 符合現代標準旨在提供簡便的 Android 應用程式開發介面與其他 AndroidX 的程式碼集完美整合，進而實現互通性程式庫

擴充功能版本和更新

擴充功能模組每年都會與 Android 平台一併更新，或是每季更新每季更新可讓 Extensions API 級別是隨著 Android 平台 API 更新增加的速率，能加快疊代速度並讓原始設備製造商 (OEM) 有機會為新功能加入官方 API 存取權會越來越接近硬體啟動

下表列出了以下項目的 androidx.window.extensions API 版本：各種 Android 版本

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

每次產生範本時，Extension API 級別 (中間欄) 就會增加以及現有的穩定 API 介面 (右欄)。

回溯與前瞻相容性

Jetpack WindowManager 可處理常見 API 級別的問題更新、快速 API 演進，以及回溯相容性。程式庫程式碼會在應用程式程序中執行，程式庫會檢查宣告的擴充功能 API 級別，並根據宣告第二，自訂角色只能套用至專案或機構

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

WindowManager 擴充功能會實作為 system_ext 模組，該模組會使用用來呼叫 WindowManager 核心的私人平台 API DeviceStateManager, 以及其他系統服務，藉此實作擴充功能功能。

擴充功能預先發布版可能無法維護相容性。最終版本如要查看 Extensions API 的完整記錄可在版本分支中找到 window:extensions:extensions API 文字檔案。

新版擴充功能必須繼續與舊版的 WindowManager 已編譯成應用程式，以便維持前瞻相容性。目的地：確定，任何新版本的 Extensions API 都只會加入新的 API，並不會移除較舊的檔案因此，具有舊版 WindowManager 的應用程式版本仍可繼續使用應用程式編譯的舊版 Extensions API 下定決心

CTS 驗證可確保裝置上任何宣告的 Extensions API 版本裝置，與該版本相關的所有 API 都會正常運作。

成效

根據預設，自 Android 14 (API 級別 34) 開始，擴充功能模組會在非 Bootclasspath 系統類別載入器中快取，因此不會因為在應用程式啟動時將模組載入記憶體而受到影響。在用戶端和伺服器之間執行其他處理序間通訊 (IPC) 呼叫時，使用個別模組功能可能會稍微影響應用程式的效能特性。

模組

活動嵌入

活動嵌入元件提供一系列功能，可讓應用程式父項應用程式邊界內的活動視窗呈現方式。這個包括在「標籤」中並排顯示兩個活動多窗格版面配置，有助於針對舊版舊版螢幕最佳化應用程式。

只要裝置具備大小等於或大於 sw600 dp 的內建顯示畫面。支援外部螢幕的裝置也必須啟用活動嵌入功能因為在外部存取應用程式時，應用程式可能會以較大尺寸顯示螢幕都會在執行階段連線。

裝置設定

啟用擴充功能後，不需要進行特定裝置設定如「擴充功能模組發布」中所述專區。建議您在所有支援裝置上啟用擴充功能多視窗模式。日後的 Android 版本可能會使用擴充功能常見的手持裝置和大螢幕裝置設定步驟。

視窗版面配置資訊

視窗版面配置資訊元件會指出轉軸跨應用程式視窗時，轉軸在折疊式裝置上。視窗版面配置資訊可讓應用程式回應並顯示最佳化的資訊折疊式裝置的桌面模式下的版面配置。詳情請見讓應用程式適用摺疊式裝置。

內含轉軸的摺疊式 Android 裝置，可分別連結不同或連續顯示面板區域必須呈現轉軸相關資訊提供給應用程式使用，期限為 WindowLayoutComponent。

轉軸位置和邊界必須依據應用程式回報由傳遞至 API 的 Context 識別的視窗。如果應用程式視窗邊界不會與轉軸邊界 (轉軸) 重疊 DisplayFeature敬上無法檢舉此外，如果不想回報顯示功能可能不準確地回報位置，例如應用程式使用者可在多視窗模式下自由移動視窗，或。

對於折疊功能當轉軸位置介於穩定狀態根據預設，API 必須回報螢幕狀態， FoldingFeature.State.FLAT。如果裝置硬體可處於半摺疊模式並保持穩定狀態， API 必須回報 FoldingFeature.State.HALF_OPENED。 API 中沒有關閉狀態，因為這種情況下應用程式視窗可能無法顯示，或是無法跨出轉軸邊界。

裝置設定

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

設定 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 是顯示座標空間中的整數像素座標。自然顯示方向設定字串可以包含多個顯示以分號分隔的顯示功能

例如：
```

<string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
```
定義應用程式內部裝置狀態 ID 之間的對應關係 DeviceStateManager，以及傳送給開發人員的公開狀態常數 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)。

例如：
```

<string-array name="config_device_state_postures" translatable="false">
    <item>0:1</item>    
    <item>1:2</item>    
    <item>2:3</item>    
    <item>3:1</item>    
    <item>4:1000</item> 
</string-array>
```

窗戶區域

視窗區域元件提供一組功能，可讓應用程式在某些摺疊式裝置上存取更多螢幕和顯示區域支援多螢幕裝置

後置顯示模式可讓應用程式使用者可以使用摺疊式裝置的封面螢幕，自拍和影片具備 Android 相容裝置 (根據 Android CDD 定義的屬性，如大小、密度和可用的導航功能) 對齊後置裝置的封面螢幕攝影機必須授予後置顯示模式的存取權。

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

裝置設定

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

設定 device_state_configuration.xml 中要使用的裝置狀態 DeviceStateManagerService。詳情請見 DeviceStateProviderImpl.java敬上瞭解詳情

如果預設實作 DeviceStateProvider敬上或 DeviceStatePolicy 不適用於裝置，則可使用自訂實作項目。
如果是支援開啟或平面模式的摺疊式裝置，請指定相應的狀態 ID (位於 com.android.internal.R.array.config_openDeviceStates 中)。
如果是支援折疊狀態的折疊式裝置，請列出對應的狀態 ID (位於 com.android.internal.R.array.config_foldedDeviceStates 中)。
適用於支援半折疊狀態的折疊式裝置 (轉軸為半開式) 將對應的狀態列成 com.android.internal.R.array.config_halfFoldedDeviceStates。
若是支援後置顯示模式的裝置：
- 列出 DeviceStateManager 的 com.android.internal.R.array.config_rearDisplayDeviceStates 中對應狀態。
- 指定後置顯示器的實際顯示地址 (位於 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 中)。
- 如果 ID 的目的是供應用程式使用，請在 com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay 中指定要讓擴充功能使用的狀態 ID。
- 在 com.android.internal.R.array.config_deviceStatesAvailableForAppRequests 中新增狀態 ID，以提供給應用程式。

驗證

原始設備製造商 (OEM) 必須驗證導入情況，確保預期的行為情境使用 Jetpack WindowManager 的 CTS 測試和測試，可供原始設備製造商 (OEM) 使用測試實作。

CTS 測試

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

WindowManager 測試

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

如要透過指令列執行 window:window 模組的裝置測試，請執行包括：

接上已啟用開發人員選項和 USB 偵錯功能的裝置。
允許電腦對裝置偵錯。
在 androidx 存放區的根目錄中開啟殼層。
將目錄變更為 framework/support。
執行下列指令：./gradlew window:window:connectedAndroidTest。
分析結果。

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

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

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

查看殼層的輸出內容，即可手動分析結果。只有部分通知系統就會略過測試。搜尋結果為儲存在標準位置中，分析人員就能編寫指令碼來自動執行分析結果。