Jetpack Compose Glimmer 中的 Surface

适用的 XR 设备
本指南可帮助您为以下类型的 XR 设备打造优质体验。
了解 XR 设备类型 →
展示眼镜
了解 XR 设备类型 →

在 Jetpack Compose Glimmer 中，surface 组件是一个基本构建块，表示按钮和卡片等组件的独特视觉区域或物理边界。

界面负责以下视觉和物理属性：

  • 裁剪：将其子项裁剪为指定形状。
  • 边框：绘制内边框以突出显示组件边界。获得焦点时，它会绘制一个带有焦点突出显示的更宽边框。
  • 背景：为表面区域应用背景颜色。
  • 深度效果：根据组件的状态（例如默认状态与聚焦状态）渲染 DepthEffect 阴影。
  • 内容颜色：提供表面内部的文字和图标颜色，默认情况下根据背景颜色计算得出。
  • 互动状态：在表面被按压时绘制按压叠加层，在获得焦点时绘制带有突出显示的更宽边框。

示例：创建表面

以下代码创建了一个具有剪裁、背景和默认边框的 Surface：

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

互动和焦点

默认情况下，界面不可聚焦，因此用户无法与之互动。在大多数情况下，表面应具有互动性，以便用户始终能够在组件之间移动焦点和进行导航。对于仅打算可聚焦的 Surface，您可以使用 Compose focusable 修饰符。同样，您可以使用 Compose clickable 修饰符创建可点击的 Surface。您还可以使用其他修饰符来表示需要执行操作的界面。

以下代码展示了可聚焦和可点击界面的示例：

@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：当表面处于聚焦状态时使用的阴影效果。