Jetpack Compose Glimmer 中的垂直堆疊

適用的 XR 裝置
這份指南可協助您為這類 XR 裝置打造體驗。
瞭解 XR 裝置類型 →
顯示眼鏡
瞭解 XR 裝置類型 →

在 Jetpack Compose Glimmer 中，VerticalStack 是可垂直捲動的延遲版面配置，會以視覺上重疊的三維序列排列項目。主要項目會醒目顯示在前景，後續項目則會顯示在主要項目後方。

圖 1. Jetpack Compose Glimmer 中不同樣式的堆疊範例。

捲動和定位行為

由於堆疊會將項目排列在緊湊的重疊版面配置中，因此與其他類型的序列元件 (例如清單) 有些行為不同：

  • 使用者垂直捲動時，系統會將前景中的項目移出畫面，讓下方的項目滑入前景的顯眼位置。
  • 使用者手勢結束後，項目一律會使用專屬的彈簧效果，彈回前景位置。
  • 項目會沿著 z 軸排列，清單中較後面的項目會放在主要項目後方。

焦點管理

VerticalStack 使用專門的焦點系統，確保目前的前景項目一律是使用者互動的主要目標：

  • 初始焦點和重新進入：初始焦點和重新進入的焦點會移至堆疊的目前頂端項目。
  • 自動對焦通知：項目轉換時，堆疊會要求將焦點放在頂端項目。
  • 焦點追蹤：每個項目都會使用 onFocusChanged 通知 StackState 各自的焦點狀態。

範例：建立垂直堆疊

下列程式碼會建立含有多個項目的垂直堆疊：

@Composable
fun VerticalStackSample() {
    VerticalStack(modifier = Modifier.fillMaxWidth().height(364.dp)) {
        item(key = 0) {
            Card(modifier = Modifier.fillMaxSize().itemDecoration(CardDefaults.shape)) {
                Text(
                    "Item-0",
                    style = LocalTextStyle.current.copy(textMotion = TextMotion.Animated),
                )
            }
        }
        items(count = 10, key = { it + 1 }) { index ->
            Card(modifier = Modifier.fillMaxSize().itemDecoration(CardDefaults.shape)) {
                Text(
                    "Item-${index + 1}",
                    style = LocalTextStyle.current.copy(textMotion = TextMotion.Animated),
                )
            }
        }
    }
}

程式碼重點

  • 將文字的 LocalTextStyle 設為 Animated。textMotion這樣可確保版面配置動畫或縮放轉場效果期間的文字算繪作業順暢，避免出現象素對齊瑕疵。
  • 提供垂直堆疊高度的特定大小 364.dp。請務必提供特定高度、使用高度修飾符，或套用 fillMaxSize 修飾符，定義卡片轉場效果的視覺區域。
  • 與直接採用形狀參數的其他元件不同，VerticalStack 會使用 itemDecoration 修飾符管理項目的視覺邊界。這個範例會為初始項目的 itemDecoration 傳遞與所有子項相同的形狀，以維持一致的剪輯和視覺效果。本範例使用預設的 CardDefaults.shape。