Oberflächen in Jetpack Compose Glimmer

XR‑Geräte, für die der Leitfaden gilt

Dieser Leitfaden hilft Ihnen dabei, Erlebnisse für die folgenden Arten von XR-Geräten zu entwickeln.

Informationen zu XR‑Gerätetypen

Informationen zu XR‑Gerätetypen

In Jetpack Compose Glimmer ist die surface Komponente ein grundlegender Baustein, der einen bestimmten visuellen Bereich oder eine physische Begrenzung für Komponenten wie Schaltflächen und Karten darstellt.

Eine Oberfläche ist für die folgenden visuellen und physischen Eigenschaften verantwortlich:

• Clipping: Die untergeordneten Elemente werden auf eine bestimmte Form zugeschnitten.
• Border: Zeichnet einen inneren Rahmen, um die Komponentengrenze hervorzuheben. Wenn der Fokus darauf liegt, wird ein breiterer Rahmen mit einer Hervorhebung gezeichnet.
• Hintergrund: Wendet eine Hintergrundfarbe auf den Oberflächenbereich an.
• Depth effects: Rendert DepthEffect Schatten basierend auf dem Status der Komponente (z. B. Standard oder Fokus).
• Content Color: Stellt eine Farbe für Text und Symbole innerhalb der Oberfläche bereit, die standardmäßig aus der Hintergrundfarbe berechnet wird.
• Interaktionszustände: Zeichnet eine gedrückte Überlagerung, wenn die Oberfläche gedrückt wird und einen breiteren Rahmen mit einer Hervorhebung, wenn der Fokus darauf liegt.

Beispiel: Oberfläche erstellen

Mit dem folgenden Code wird eine Oberfläche mit Clipping, einem Hintergrund und Standardrahmen erstellt:

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

Interaction and Focus

Surfaces aren't focusable by default, so users can't interact with them. In most cases, surfaces should be interactive to let users consistently move focus and navigate between components. You can use the Compose focusable modifer for surfaces that are only intended to be focusable, or the Compose clickable modifer and other modifiers for surfaces that require actions.

You can create a focusable surface by combining a surface modifier with the focusable modifier:

@Composable
fun FocusableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        Modifier.surface(
                // Provide the same interaction source here and to focusable to make sure that
                // surface appears focused when interacted with.
                interactionSource = interactionSource
            )
            .focusable(interactionSource = interactionSource)
            .padding(horizontal = 24.dp, vertical = 20.dp)
    ) {
        Text("This is a focusable surface")
    }
}
SurfaceSamples.kt

Key points about the code

• Shared interaction source: Both .surface() and .focusable() must share the same interactionSource. This lets the surface react to focus changes.

Similarly, you can create a clickable surface:

@Composable
fun ClickableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        Modifier.surface(
                // Provide the same interaction source here and to clickable to make sure that
                // surface appears focused and pressed when interacted with
                interactionSource = interactionSource
            )
            .clickable(interactionSource = interactionSource, onClick = {})
            .padding(horizontal = 24.dp, vertical = 20.dp)
    ) {
        Text("This is a clickable surface")
    }
}
SurfaceSamples.kt

Wichtige Punkte zum Code

• Gemeinsame Interaktionsquelle: Beide .surface() und .clickable() müssen dieselbe interactionSource verwenden. So wird sichergestellt, dass visuelle Status (z. B. „Gedrückt“ oder „Fokus“) synchronisiert werden, sodass die Oberfläche visuell auf Nutzereingaben reagieren kann.

• Reihenfolge der Modifikatoren: Die Reihenfolge der Modifikatoren ist entscheidend. Da .surface() ein Layout zuschneidet, wird durch die Platzierung vor .clickable() sichergestellt, dass der Berührungszielbereich auf die Form der Oberfläche beschränkt ist. Wenn .clickable() zuerst kommt, kann sich der Interaktionsbereich über die sichtbaren, zugeschnittenen Grenzen der Komponente hinaus erstrecken.

SurfaceDepthEffect

Die SurfaceDepthEffect Klasse verwaltet den Übergang von Schatten zwischen Interaktionsstatus:

• depthEffect: Der Schatteneffekt, der verwendet wird, wenn sich die Oberfläche im Standardstatus befindet.
• focusedDepthEffect: Der Schatteneffekt, der verwendet wird, wenn der Fokus auf der Oberfläche liegt.