Jetpack Compose Glimmer 中的介面

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

在 Jetpack Compose Glimmer 中，surface 元件是基本構成元素，代表按鈕和資訊卡等元件的獨立視覺區域或實體邊界。

表面負責下列視覺和實體屬性：

  • 剪裁：將子項剪裁成指定形狀。
  • 邊框：繪製內框，強調元件邊界。當焦點位於該項目時，系統會繪製較寬的邊框，並醒目顯示焦點。
  • 背景：為表面區域套用背景顏色。
  • 深度效果：根據元件的狀態 (例如預設與焦點)，算繪 DepthEffect 陰影。
  • 內容顏色：提供介面內文字和圖示的顏色，預設會根據背景顏色計算。
  • 互動狀態：在表面按下時繪製按下疊加層，並在聚焦時繪製較寬的醒目顯示邊框。

範例：建立介面

下列程式碼會建立具有裁剪、背景和預設邊框的介面：

@Composable
fun SurfaceSample() {
    Box(Modifier.surface().padding(horizontal = 24.dp, vertical = 20.dp)) {
        Text("This is a surface")
    }
}

互動和焦點

介面預設無法成為焦點，因此使用者無法與其互動。在大多數情況下，介面應具備互動性，讓使用者持續移動焦點，並在元件之間導覽。您可以使用 Compose focusable 修飾符，只針對可聚焦的介面。同樣地，您可以使用 Compose clickable 修飾符建立可點選的介面。您也可以針對需要動作的介面使用其他修飾符。

下列程式碼顯示可聚焦和可點選的介面範例：

@Composable
fun FocusableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        modifier = Modifier
            .size(100.dp)
            .surface(interactionSource = interactionSource)
            .focusable(interactionSource = interactionSource),
        contentAlignment = Alignment.Center
    ) {
        Text("Focusable")
    }
}

@Composable
fun ClickableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        modifier = Modifier
            .size(100.dp)
            .surface(interactionSource = interactionSource)
            .focusable(interactionSource = interactionSource)
            .clickable(
                interactionSource = interactionSource,
                indication = null
            ) { /* Handle click action */ },
        contentAlignment = Alignment.Center
    ) {
        Text("Clickable")
    }
}

程式碼重點

  • 可聚焦介面的共用互動來源：.surface() 和 .focusable() 必須共用相同的 interactionSource。這可讓介面回應焦點變更。

  • 可點擊途徑的共用互動來源：.surface() 和 .clickable() 必須共用相同的 interactionSource。這可確保視覺狀態 (例如按下或焦點) 會同步處理，讓介面根據使用者輸入內容做出視覺反應。

  • 修飾符順序：修飾符的順序至關重要。由於 .surface() 會裁剪版面配置，因此請將其放置在 .clickable()「之前」，確保觸控目標受限於表面的形狀。如果 .clickable() 先出現，互動區域可能會超出元件可見的裁剪邊界。

SurfaceDepthEffect

SurfaceDepthEffect 類別會管理互動狀態之間的陰影轉場效果：

  • depthEffect：表面處於預設狀態時使用的陰影效果。
  • focusedDepthEffect：表面聚焦時使用的陰影效果。