רכיבי Surface ב-Jetpack Compose Glimmer

מכשירי XR שמתאימים לשימוש

ההנחיות האלה יעזרו לכם ליצור חוויות למכשירי XR מהסוגים הבאים.

מידע על סוגי מכשירי XR →

מידע על סוגי מכשירי XR →

ב-Jetpack Compose Glimmer, הרכיב surface הוא אבן בניין בסיסית שמייצגת אזור ויזואלי נפרד או גבול פיזי לרכיבים כמו לחצנים וכרטיסים.

המשטח אחראי למאפיינים הפיזיים והוויזואליים הבאים:

• ‫Clipping: חותך את הצאצאים לצורה שצוינה.
• גבול: מוסיף גבול פנימי כדי להבליט את הגבול של הרכיב. כשמתמקדים בו, הוא מצייר גבול רחב יותר עם הדגשה ממוקדת.
• רקע: המערכת מחילה צבע רקע על האזור.
• אפקטים של עומק: יוצר צללים DepthEffect על סמך המצב של הרכיב (למשל, ברירת מחדל לעומת מיקוד).
• צבע התוכן: מספק צבע לטקסט ולסמלים בתוך הרכיב, שמחושב כברירת מחדל מצבע הרקע.
• מצבי אינטראקציה: מצייר שכבת-על של לחיצה כשהמשטח נלחץ, וגבול רחב יותר עם הדגשה כשהמיקוד הוא על המשטח.

דוגמה: יצירת פלטפורמה

הקוד הבא יוצר משטח עם חיתוך, רקע ומסגרות ברירת מחדל:

@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

מידע חשוב על הקוד

• מקור משותף של אינטראקציות: גם .‫surface() וגם .clickable() חייבים להיות באותו interactionSource. כך אפשר לוודא שהמצבים החזותיים (כמו לחיצה או מיקוד) מסונכרנים, והממשק יכול להגיב חזותית לקלט של המשתמש.

• סדר השינויים: הרצף של השינויים הוא קריטי. Because .‫surface() חותך פריסה ומציב אותה לפני .‫clickable() מוודא שמשטח המגע מוגבל לצורה של פני השטח. אם .clickable() מופיע ראשון, יכול להיות שאזור האינטראקציה יתרחב מעבר לגבולות הגלויים והחתוכים של הרכיב.

SurfaceDepthEffect

המחלקות SurfaceDepthEffect מנהלות את המעבר של הצללות בין מצבי אינטראקציה:

• ‫depthEffect: אפקט הצל שמוגדר כברירת מחדל כשמשטח נמצא במצב ברירת המחדל שלו.
• ‫focusedDepthEffect: אפקט הצל שמופיע כשמתמקדים במשטח.