摺疊式裝置的 Jetpack 視窗管理員

發行項
07/10/2023

Jetpack Window Manager 提供標準 API 來處理所有可折迭的裝置。它包含兩個重要的類別：

DisplayFeature - 識別連續平面螢幕介面的中斷處 (例如轉軸或摺疊)。視窗管理員會從版面配置變更回呼傳回顯示功能集合。
FoldingFeature - 提供裝置特定功能的相關資訊。雖然 Surface Duo 只有一個折迭功能，但其他裝置可能有更多功能。

類似的指南位於 Android 可折迭程式碼實驗室中。深入瞭解如何在 Android 檔中開發折迭套件。Android 小組的範例也適用于GitHub。 Jetpack 版本資訊會在更新時記錄視窗管理員中的變更。

提示

Surface Duo 雙螢幕程式庫中的控制項和協助程式類別會使用視窗管理員。請遵循指示將正確的套件新增至您的應用程式專案。

若要直接在您的程式碼中使用 Window Manager，請遵循下列指示：

新增相依性

請確定您在最上層build.gradle檔案中有存放 mavenCentral() 庫：

allprojects {
    repositories {
        google()
        mavenCentral()
     }
}

compileSdkVersion請確定和 targetSdkVersion 已設定為模組層級build.gradle檔案中的 API 31 或更新版本：
```
android { 
    compileSdkVersion 31

    defaultConfig { 
        targetSdkVersion 31
    } 
    ... 
}
```

將下列相依性新增至模組層級 build.gradle 檔案：

檢視
組成

dependencies {
    implementation "androidx.window:window:1.0.0"
    implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.4.0'
}

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

在 Kotlin 程式碼中使用視窗管理員

存取 Kotlin 專案中的 Window Manager 屬性時，請務必設定正確的資訊流程。否則，您可能會收到太多或太多事件更新，而且應用程式效能可能會受到影響。

若要初始化和使用 WindowInfoTracker 物件，請遵循下列步驟：

在 MainActivity 類別中，建立的 WindowInfoTracker 變數。確定 import androidx.window.layout.WindowInfoTracker 已新增至檔案頂端。
```
class MainActivity : AppCompatActivity() {
    private lateinit var windowInfoTracker: WindowInfoTracker
```

在活動的 onCreate 方法中初始化， WindowInfoTracker 並設定流程以從 windowLayoutInfo 屬性收集資訊。

檢視
組成

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Initialize the window manager
    windowInfoTracker = WindowInfoTracker.getOrCreate(this@MainActivity)

    // Set up a flow
    lifecycleScope.launch(Dispatchers.Main) {
        lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
            windowInfoTracker.windowLayoutInfo(this@MainActivity)
                .collect { 
                    // Check FoldingFeature properties here
                }
        }
    }
}

確定這些匯入也會新增至檔案頂端：

import androidx.lifecycle.Lifecycle
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.repeatOnLifecycle
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Initialize the window manager
    windowInfoTracker = WindowInfoTracker.getOrCreate(this@MainActivity)

    setContent {
        ExampleAppTheme {
            ExampleApp(windowInfoTracker.windowLayoutInfo(this@MainActivity))
        }
    }
}

@Composable
fun ExampleApp(windowLayoutInfo: Flow<WindowLayoutInfo>) {
    // Set up a flow   
    LaunchedEffect(windowLayoutInfo) {
        windowLayoutInfo.collect { 
            // Check FoldingFeature properties here
        }
    }
}

確定這些匯入也會新增至檔案頂端：

import androidx.compose.runtime.LaunchedEffect
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect

新增程式碼以檢查流程中的 WindowLayoutInfo折迭功能屬性。執行此程式碼時，活動會以目前的裝置狀態更新，並在跨越折迭或轉軸) 時顯示功能 (。

在下列程式碼片段中，活動會根據的屬性 FoldingFeature 顯示不同的文字。

檢視
組成

此範例有一 layout_change_text 個名為的 TextView，顯示任何偵測到折迭功能的遮蔽類型和 isSeparating 值。

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    windowInfoTracker = WindowInfoTracker.getOrCreate(this@MainActivity)

    lifecycleScope.launch(Dispatchers.Main) {
        lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
            windowInfoTracker.windowLayoutInfo(this@MainActivity)
                .collect { newLayoutInfo ->
                    layout_change_text.text = "No display features detected"
                    for (displayFeature : DisplayFeature in newLayoutInfo.displayFeatures) {
                        if (displayFeature is FoldingFeature && displayFeature.occlusionType == FoldingFeature.OcclusionType.NONE) {
                            layout_change_text.text = "App is spanned across a fold, " +
                                "isSeparating = ${displayFeature.isSeparating}"
                        }
                        if (displayFeature is FoldingFeature && displayFeature.occlusionType == FoldingFeature.OcclusionType.FULL) {
                            layout_change_text.text = "App is spanned across a hinge, " +
                                "isSeparating = ${displayFeature.isSeparating}"
                        }
                    }
                }
        }
    }
}

此範例有 Text 元素，顯示任何偵測到折迭特徵的大小和 isSeparating 值。

@Composable
fun ExampleApp(windowLayoutInfo: Flow<WindowLayoutInfo>) {
    var isSeparating by remember { mutableStateOf(false) }
    var foldSizePx by remember { mutableStateOf(0) }

    LaunchedEffect(windowLayoutInfo) {
        windowLayoutInfo.collect { newLayoutInfo ->
                val displayFeatures = newLayoutInfo.displayFeatures

                if (displayFeatures.isNotEmpty()) {
                    val foldingFeature = displayFeatures.first() as FoldingFeature

                    // Check if a folding feature separates content into two sections
                    isSeparating = foldingFeature.isSeparating

                    // Get size of folding feature in pixels
                    foldSizePx = when (foldingFeature.orientation) {
                        FoldingFeature.Orientation.VERTICAL -> foldingFeature.bounds.width()
                        else -> foldingFeature.bounds.height()
                    }
                }
            }
    }

    Text(text = "Fold size: $foldSizePx pixels, isSeparating = $isSeparating")
}

折迭功能屬性

類別 WindowLayoutInfo 具有專案集合 DisplayFeature ，其中一或多個可能是 FoldingFeature 類別的實例。

折迭功能具有下列屬性：

bounds - 折迭功能的周框座標
occlusionType - 如果折迭功能隱藏內容 (FULL 或 NONE)
orientation - 折迭功能的方向 (HORIZONTAL 或 VERTICAL)
state - 折迭功能的角度 (HALF_OPENED 或 FLAT)
isSeparating - 如果折迭功能將顯示區域分成兩個不同的區段

您可以查詢這些屬性，以決定如何在設定變更之後調整版面配置。

isSeparating

決定要放置控制項的位置或要顯示的內容窗格數目時，請使用 isSeparating 屬性。此欄位可確保您的應用程式在所有可折迭裝置上提供最佳的使用者體驗：

針對雙螢幕裝置，當應用程式跨越轉軸時，這一律為真
對於其他可折迭裝置，只有在狀態為 HALF_OPENED 時，才會是 true，例如當裝置處於桌面狀態時

isSeparating使用屬性來決定是否要調整可折迭裝置的應用程式 UI 配置，或在沒有分隔時使用預設 UI：

private fun updateCurrentLayout(newLayoutInfo: WindowLayoutInfo) {
   for (displayFeature in newLayoutInfo.displayFeatures) {
       val foldFeature = displayFeature as? FoldingFeature
       foldFeature?.let {
           if (it.isSeparating) {
               // The content is separated by the FoldingFeature.
               // Here is where you should adapt your UI.
           } else {
               // The content is not separated.
               // Users can see and interact with your UI properly.
           }
       }
   }
}

若要查看如何使用此欄位的更詳盡範例，請參閱此 isSeparating 範例。

Google 也提供與此屬性相關的檔和範例，作為其大型螢幕和可折迭指引的一部分。

範例

surface-duo-jetpack-window-manager-samples GitHub存放庫包含一些 Kotlin 範例，示範使用 Jetpack Window Manager 和傳統檢視系統所建置的不同雙螢幕使用者體驗模式。

surface-duo-compose-samples GitHub存放庫也有使用 Jetpack Window Manager 的雙螢幕 Kotlin 範例，但在這些範例中，UI 是使用 Jetpack Compose 所建置。

Java API

請參閱具有 JAVA 的 Jetpack 視窗管理員部落格文章和此JAVA 範例，以瞭解如何透過 WindowInfoTrackerCallbackAdapter 存取 WindowInfoTracker 類別。

共用方式為