Jetpack Compose Glimmer 中的橫向頁面控制項

適用的 XR 裝置

這份指南可協助您為這類 XR 裝置打造體驗。

顯示眼鏡

在 Jetpack Compose Glimmer 中，GlimmerHorizontalPager 是以延遲方式組合的水平捲動版面配置，可依序排列頁面。這與 Compose Foundation 中找到的標準 HorizontalPager 類似，但專為顯示型眼鏡量身打造，具有 Glimmer 行為和預設值。

根據預設，系統一次只會醒目顯示一個頁面。為提供完善的體驗，翻頁元素會使用貼齊動畫，確保使用者捲動手勢結束後，頁面一律會準確地停留在可視區域邊界。

重要參數和版面配置選項

GlimmerHorizontalPager 提供可自訂的參數，可控制間距、版面配置對齊方式和延遲載入。部分參數如下：

參數	說明
`state`	`GlimmerPagerState` 物件，可管理、觀察及以程式輔助方式控制分頁檢視區塊的捲動位置和作用中頁面。
`contentPadding`	裁剪後套用至整體內容邊界的邊框間距，適用於在第一頁之前或最後一頁之後新增開頭或結尾邊框間距。
`pageSpacing`	頁面控制項中各個頁面之間的水平間距。
`pageIndicator`	可組合的插槽，可轉譯有效頁面指標。預設為 `GlimmerHorizontalPagerDefaults.PageIndicator(state)`。
`beyondViewportPageCount`	要組合及排版的可視區域外頁面數量，做為預先載入最佳化。請避免設定過大的值，以維持延遲組合效率。

如要瞭解所有可用參數，請參閱完整參考文件。

文字動畫動作建議

在顯示眼鏡上進行頁面快速捲動動畫和轉場效果時，預設文字算繪可能會出現象素對齊假影。設定 TextMotion.Animated 可確保版面配置動畫在整個過程中順暢算繪：

Text(
    text = "Page: $page",
    style = LocalTextStyle.current.copy(textMotion = TextMotion.Animated),
)GlimmerHorizontalPagerSample.kt

範例：橫向頁面控制項

以下程式碼示範如何建立含有 10 個頁面的基本水平分頁檢視區塊，並在每個頁面中放置 Card：

// Hoist the pager state, specifying the total page count with a lambda.
val pagerState = rememberGlimmerPagerState(pageCount = { 10 })

GlimmerHorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxSize(),
) { page ->
    // Use Glimmer components like Card and Text for optimized glasses styling.
    Card(modifier = Modifier.fillMaxWidth()) {
        Text(
            text = "Page: $page",
            // Recommended: use TextMotion.Animated for smooth transitions in a pager.
            style = LocalTextStyle.current.copy(textMotion = TextMotion.Animated),
        )
    }
}GlimmerHorizontalPagerSample.kt

程式碼重點

State：使用 rememberGlimmerPagerState(pageCount = { 10 }) 初始化 GlimmerPagerState，管理分頁器的狀態。
頁面位置內容：在 GlimmerPagerScope lambda 中接收頁面索引 page，以便顯示每張資訊卡。
流暢動畫文字樣式：複製 LocalTextStyle.current 並明確啟用 TextMotion.Animated。
自動頁面指標：與標準 Compose 分頁器不同，GlimmerHorizontalPager 預設會自動嵌入點狀頁面指標，不需要外部指標元件。

網頁指標

根據預設，GlimmerHorizontalPager 會使用 GlimmerHorizontalPagerDefaults.PageIndicator 轉譯以點為主的頁面指標。指標會自動調整色彩配置：

活動圓點會使用從最接近的周圍 surface 解析出的內容顏色。

您可以傳遞自訂的 PageIndicator 來指定明確的顏色，或將點替換為自己的自訂版面配置：

GlimmerHorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxSize(),
    // Use a page numbers instead of the default dot-indicator
    pageIndicator = {
        Text(
            text = "${pagerState.currentPage + 1} / ${pagerState.pageCount}",
            style = LocalTextStyle.current.copy(textMotion = TextMotion.Animated),
        )
    }
)GlimmerHorizontalPagerSample.kt