WindowManager

程式碼範例程式碼研究室

API 參考資料
androidx.window
androidx.window.core
androidx.window.embedding
androidx.window.layout
androidx.window.testing.layout

Jetpack WindowManager 程式庫可讓應用程式開發人員支援新的裝置板型規格和多視窗環境。程式庫針對 API 14 以上版本提供通用的 API 介面。雖然初始版本是以折疊式裝置為指定目標，但日後推出的版本將延伸到更多顯示螢幕類型和視窗功能。

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2022 年 11 月 9 日	1.0.0	-	-	1.1.0-alpha04

宣告依附元件

如果要為 WindowManager 新增依附元件，您必須將 Google Maven 存放區新增至專案。詳情請參閱「Google 的 Maven 存放區」一節。

在應用程式或模組的 build.gradle 檔案中，新增您需要的構件依附元件：

Groovy

dependencies {
    implementation "androidx.window:window:1.0.0"

    // For Java-friendly APIs to register and unregister callbacks
    implementation "androidx.window:window-java:1.0.0"

    // For RxJava2 integration
    implementation "androidx.window:window-rxjava2:1.0.0"

    // For RxJava3 integration
    implementation "androidx.window:window-rxjava3:1.0.0"

    // For testing
    implementation "androidx.window:window-testing:1.0.0"
}

Kotlin

dependencies {
    implementation("androidx.window:window:1.0.0")

    // For Java-friendly APIs to register and unregister callbacks
    implementation("androidx.window:window-java:1.0.0")

    // For RxJava2 integration
    implementation("androidx.window:window-rxjava2:1.0.0")

    // For RxJava3 integration
    implementation("androidx.window:window-rxjava3:1.0.0")

    // For testing
    implementation("androidx.window:window-testing:1.0.0")
}

意見回饋

您的意見可協助我們改善 Jetpack。發現新的問題或想要提出關於改進這個程式庫的建議時，請告訴我們。建立新的問題之前，請先查看這個程式庫中的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件。

1.1 版本

1.1.0-alpha04 版本

2022 年 11 月 9 日

發布了 androidx.window:window-*:1.1.0-alpha04。1.1.0-alpha04 版本包含這些修訂版本。

新功能

公開判定 ActivityEmbedding 的 ActivityStack 是否空白的方法。
從 ActivityEmbedding API 中移除實驗性 API 標記。
將 ActivityRule 建構函式做為 Builder 隱藏是偏好的方式。
新增在 WindowMetrics 取得 WindowInsets 的實驗性方法。
更新 SplitPlaceholderFinishBehavior，以免結束預留位置。如果結束預留位置，則會造成某項錯亂行為。

API 變更

將 val isEmpty 設為公開，即可取代 fun isEmpty。
將 ActivityStack 參數活動重新命名為 activitiesInProcess。(Ia5055)
移除造成錯亂的 ActivityFilter#matchesClassName 和 ActivityFilter#matchesClassNameOrWildCard。
新增 ActivityFilter#componentName 和 ActivityFilter#intentAction，方便呼叫端區別不同的篩選條件 (I41f22)
從實驗性 API 中移除 @Deprecated API (I216b3)
移除活動嵌入 API 的 @ExperimentalWindowApi (I69ebe)
隱藏 ActivityRule 建構函式，請改用 Builder。(If4eb6)
新增用於檢查活動是否屬於 ActivityFilter 的 API。(Ia43cf)
更新 API 檔案以反映 WindowMetrics 和 WindowMetricsCalculatorCompat 類別的變更 (I667fe)
更新 ActivityEmbedding 屬性 Javadoc 和類別名稱 (Ia1386)
新增要用於 AndroidManifest.xml (Id1ad4) 的 ActivityEmbedding 屬性標記名稱
新增取代 SplitPlaceholderRule.finishPrimaryWithSecondary 的 API SplitPlaceholderFinishBehavior 和 SplitPlaceholderRule.finishPrimaryWithPlaceholder，藉以定義何時要結束預留位置活動，以及活動嵌入中關聯的活動應有怎樣的行為。(I64647)

修正錯誤

加入 WindowAreaController 和 API，讓 RearDisplay 模式將目前視窗移至與後置鏡頭對齊的螢幕。(I388ab)

1.1.0-alpha03 版本

2022 年 7 月 27 日

發布 androidx.window:window-*:1.1.0-alpha03。1.1.0-alpha03 版包含以下修訂項目。

新功能

更新嵌入規則的預設值。

API 變更

更新嵌入規則屬性的預設值 (Ic4d35)。

1.1.0-alpha02 版本

2022 年 5 月 11 日

androidx.window:window-*:1.1.0-alpha02 發布。1.1.0-alpha02 版本包含以下修訂項目。

新功能

發布轉接程式程式庫以支援 Java 與 RxJava。

1.1.0-alpha01 版本

2022 年 5 月 11 日

androidx.window:window-*:1.1.0-alpha01 發布。1.1.0-alpha01 版本包含以下修訂項目。

新功能

發布轉接程式以支援 Java 與 RxJava

1.1.0-alpha01 版本

2022 年 4 月 20 日

androidx.window:window:1.1.0-alpha01 發布。1.1.0-alpha01 版本包含以下修訂項目。

新功能

修正了當設定應用程式背景時會停止傳送折疊功能的錯誤。
在實驗性 ActivityEmbedding API 中展開。

API 變更

用於檢查活動是否嵌入的公用 API。(I39eb7)

修正錯誤

新增 API 以自訂活動分割中的容器完成行為 (I1a1e4)
為活動分割規則新增設定選項。(Iec6af)

1.0 版本

1.0.0 版本

2022 年 1 月 26 日

androidx.window:window-*:1.0.0 發布。1.0.0 版包含以下修訂項目。

1.0.0 的主要功能

透過 WindowInfoTracker 和 FoldingFeature 支援折疊式手機。使用 WindowMetricsCalculator 協助計算目前的 WindowMetrics。

1.0.0-rc01 版本

2021 年 12 月 15 日

androidx.window:window-*:1.0.0-rc01 發布。1.0.0-rc01 版包含以下修訂項目。

新功能

新增透過 WindowInfoTracker 提供折疊式手機支援。
新增方法來計算 WindowMetrics 的現有值和最小值。
新增支援的測試 API。

1.0.0-beta04 版本

2021 年 11 月 17 日

androidx.window:window-*:1.0.0-beta04 發布。1.0.0-beta04 版包含這些修訂版本。

新功能

將 WindowInfoRepository 重新命名為 WindowInfoTracker。
將活動明確設為 WindowInfoTracker 的方法依附元件。
為 WindowMetricsCalculator 新增簡單的 TestRule，藉此支援使用 Robolectric 的開發人員。

API 變更

擷取擴充功能。(I25a5f)
在 ActivityStack 中新增 isEmpty。(I5a4e6)
將 WindowInfoRepository 重新命名為 WindowInfoTracker。
- 更新 java/rxjava/testing 依附元件以進行比對。(I0da63)
為簡易的 WindowMetricsCalculator 新增測試規則。(Ibacdb)

1.0.0-beta03 版本

2021 年 10 月 27 日

androidx.window:window-*:1.0.0-beta03 發布。1.0.0-beta03 版本包含以下修訂項目。

新功能

新增實驗功能活動嵌入 API。初始版面配置版本可讓您並排顯示兩個活動。

API 變更

已移除 currentWindowMetrics API，因為我們無法正確提供。請改用 WindowMetricsCalculator。(Icda5f)
已更新擴充功能 API。(Ica92b)
已新增允許嵌入活動的新功能介面，並可在父項工作視窗中並排顯示這些活動。(I5711d)
隱藏 WindowMetrics 和 WindowLayoutInfo 的建構函式，請改用測試 API。(I5a1b5)
新增 API 以建立假的 WindowLayoutInfo 物件。(I4a2fd)

修正錯誤

已修正記憶體流失。(I3fc79、b/202989046)

1.0.0-beta02 版本

2021 年 9 月 1 日

androidx.window:window-*:1.0.0-beta02 發布。1.0.0-beta02 版包含這些修訂版本。

新功能

新增實驗功能註解，以註解實驗功能 API。(I9f1b6)
新增測試方法，建立接受矩形的測試 FoldingFeature。如此一來，您在使用 Robolectric 時，會比實際活動更容易測試。(Id1cca)

1.0.0-beta01　版

2021 年 8 月 18 日

androidx.window:window-*:1.0.0-beta01 發布。1.0.0-beta01 版本包含以下修訂項目。

新功能

已移除舊常數，並使 FoldingFeature 成為介面。

API 變更

移除舊常數，並將 FoldFeature 設為介面。(I9a2d5)

修正錯誤

仰賴 Test Core 程式庫的程式庫已升級為 1.4.0 版，現在可與 Android 平台版本 S 搭配使用。(I88b72、b/189353863)

1.0.0-alpha10 版本

2021 年 8 月 4 日

androidx.window:window-*:1.0.0-alpha10 發布。1.0.0-alpha10 版本包含以下修訂項目。

新功能

將 WindowInfoRepo 重新命名為 WindowInfoRepository 並調整對應的類別 / 檔案。
將目前的視窗指標轉換為 WindowInfoRepository 中的流程，因為值會隨著時間改變。
將 WindowInfoRepoJavaAdapter 重新命名為 WindowInfoRepoCallbackAdapter
新增輔助方法來建立測試 FoldingFeature 物件
根據支援的功能更新套件，將類別分類。

API 變更

將 ActivityExt 重新命名為 ActivityExtensions 從 Repo 變更為 Repository。(I61a16)
更新類別的套件。(I23ae2)
從 WindowInfoRepo 移除 WindowMetrics。(I24663)
移除 WindowManager 並使用 WindowInfoRepo
- 將 WindowBackend 設為內部。(I06d9a)
將視窗指標轉換為流程。
- 將 Java 轉接程式重新命名為 WindowInfoRepoCallbackAdapter
- 移除 callbackFlow，因此不必再使用實驗功能 API。(Ia4d15)
新增輔助方法來建立測試顯示功能。
- 從 occlusionMode 變更為 occlusionType。(If4cff)

修正錯誤

修正移除核心程式庫的 ProGuard 錯誤。
修正未將 WindowLayoutInfo 傳送給其他訂閱者的錯誤。
修正設定變更不會觸發折疊功能更新的錯誤。

1.0.0-alpha09 版本

2021 年 6 月 30 日

androidx.window:window-*:1.0.0-alpha09 發布。1.0.0-alpha09 版包含以下修訂項目。

新功能

從整數常數變更為不設限的列舉。
新增測試公用程式，以建立測試折疊功能。

API 變更

新增輔助方法來建立測試顯示功能。(I3cf54)
- 從 occlusionMode 變更為 occlusionType。

修正錯誤

新增多位資料串流消費者時，先發出初始值。

1.0.0-alpha08 版本

2021 年 6 月 16 日

androidx.window:window-*:1.0.0-alpha08 發布。1.0.0-alpha08 版本包含以下修訂項目。

新功能

發布測試構件，方便您在使用 WindowInfoRepository 時進行測試。使用 WindowInfoRepository 取得 DisplayFeatures 和 WindowMetrics 的相關資訊。(I57f66、Ida620)

1.0.0-alpha07 版本

2021 年 6 月 2 日

androidx.window:window-*:1.0.0-alpha07 發布。1.0.0-alpha07 版本包含這些修訂項目。

新功能

將核心視窗程式庫遷移至 Kotlin。將使用協同程式並暫停函式，以公開日後的非同步資料。
將 WindowInfoRepo 新增為取得 WindowMetrics 和 WindowLayoutInfo 串流的主要互動點。
新增 window-java 構件，以公開 Java 適用的 API 來註冊及取消註冊回呼。
新增 window-rxjava2 和 window-rxjava3 構件，以公開經過 RxJava 調整的 API。

API 變更

新增 WindowServices 以統一提供依附元件。
- 新增以協同程式為基礎的 API，以便使用視窗版面配置資訊。(Iab70f)
將核心視窗管理員程式庫遷移至 Kotlin。(Icca34)

修正錯誤

新增資料類別來代表特徵邊界。(I6dcd1)

1.0.0-alpha06 版本

2021 年 5 月 5 日

androidx.window:window:1.0.0-alpha06 發布。1.0.0-alpha06 版本包含以下修訂項目。

新功能

我們已經開始遷移至 Kotlin，將於下一版中完成。
DeviceState 已從公用 API 中移除，請改用 FoldingFeature。
我們目前已將 STATE_FLIPPED 從 FoldingFeature 狀態中移除，因為目前任何用途均不支援這項功能。
我們也移除了其他已淘汰的 API。

API 變更

將 Kotlin 新增為依附元件。
- 將核心程式庫遷移至 Kotlin。(Idd995)
已移除 DisplayFeature 建構工具。(I61fa4)
已從公用 API 中移除 DeviceState，請改用 FoldingFeature。(Id6079)
從擴充功能中移除裝置狀態回呼。(I5ea83)
從 FoldingFeature 移除 STATE_FLIPPED。(I9c4e1)
移除已淘汰的註冊方法。(Ib381b)

1.0.0-alpha05 版本

2021 年 3 月 24 日

androidx.window:window:1.0.0-alpha05 發布。1.0.0-alpha05 版包含此連結所列的修訂項目。

新功能

我們已為 FoldingFeature 新增便利的方法，讓應用程式能夠判斷功能是否分離、阻塞，並判定轉軸的方向。我們也隱藏轉軸類型，這樣一來

我們即將從 WindowManager 中移除同步讀取方法。同步讀取方法很容易出錯，因為有隱含的競爭狀況。註冊事件監聽器和回呼，即可在 WindowLayoutInfo 上接收更新。

API 變更

新增使用 FoldingFeatures 的便利方法。(Ie733f)
從 WindowManager 移除同步讀取方法。(I96fd4)

1.0.0-alpha04 版

2021 年 3 月 10 日

androidx.window:window:1.0.0-alpha04 發布。1.0.0-alpha04 版本包含以下修訂項目。

新功能

修正未採用 OEM 實作時，不會發出 WindowLayoutInfo 的錯誤。現在，我們要發出空的 WIndowLayoutInfo。
修正應用程式在背景執行時，轉軸狀態變更時狀態未妥善更新的錯誤。現在狀態應能保持一致。
更新 ProGuard 檔案，忽略執行階段依附元件的警告。

修正錯誤

缺少 OEM 程式庫時，發送空白值。(Ide935)

1.0.0-alpha03 版本

2021 年 2 月 18 日

androidx.window:window:1.0.0-alpha03 發布。1.0.0-alpha03 版本包含以下修訂項目。

新功能

當 OEM 實作為空白時，發出空白的 WindowLayoutInfo 值。這樣你就可以在更多裝置上輕鬆使用程式庫。由於 API 為非同步，我們仍建議應用程式編寫一些防禦程式碼，並在逾時後發出預設值。我們無法對 OEM 實作作業提供任何保證，因此初始值可能會延遲。

修正錯誤

缺少 OEM 程式庫時，發送空白值。(Ide935)

1.0.0-alpha02 版本

2021 年 1 月 27 日

androidx.window:window:1.0.0-alpha02 發布。1.0.0-alpha02 版包含以下修訂項目。

新功能

我們已淘汰部分 API 來簡化 API，並減少錯誤。值得留意的範例包括從 WindowManager 移除同步讀取作業，並淘汰 DeviceState。同步讀取作業可能會導致競爭狀況及不正確的使用者介面。
我們已將 DisplayFeature 轉換至日後會導入其他功能的介面。第一項功能是 FoldingFeature，現在表示螢幕折疊或轉軸。另外也包含轉軸取代 DeviceState 的狀態。
WindowMetrics 是在 Android 11 中推出，讓開發人員透過簡單的方法查詢視窗相關指標，例如其在畫面上的位置和大小及系統插邊。我們已在這個版本中向後移植 API，讓開發人員能利用 WindowMetrics 並繼續支援舊版 Android。WindowMetrics 可透過 WindowManager#getCurrentWindowMetrics() 和 WindowManager#getMaximumWindowMetrics() API 取得。

API 變更

淘汰將在下一個 Alpha 版中移除的 API。(Ib7cc4)
更新 ExtensionInterface 以接受明確的活動參照。(I07ded)
推出 WindowMetrics API。(I3ccee)
從 WindowManager 中移除同步讀取方法。(I69983)
使 ExtensionWindowBackend 套件受到保護。(Ied208)

修正錯誤

更新 ExtensionInterface API 以接受視覺結構定義。(I8e827)

外部貢獻

合併 DeviceState 和 WindowLayoutInfo，這樣即可輕鬆存取資料。(Id34f4)。

1.0.0-alpha01 版本

2020 年 2 月 27 日

androidx.window:window:1.0.0-alpha01 和 androidx.window:window-extensions:1.0.0-alpha01 發布。1.0.0-alpha01 版包含這些修訂版本。這是視窗管理員程式庫的第一個版本。

新功能

DisplayFeature：這個新的 API 可找出連續平面螢幕途徑的中斷情形，例如轉軸或折疊
DeviceState：這個新的 API 會根據已定義的姿勢清單 (例如 CLOSED、OPENED、HALF_OPENED 等)，提供手機目前的姿勢。