الأسطح في 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")
    }
}
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 نفسه. ويضمن ذلك مزامنة الحالات المرئية (مثل الضغط أو التركيز)، ما يتيح للسطح التفاعل بشكل مرئي مع إدخال المستخدم.

• ترتيب المعدِّلات: إنّ تسلسل المعدِّلات مهم جدًا. لأنّ .يقتطع surface() جزءًا من تخطيط، ويضعه قبل .يضمن clickable() أن تكون مساحة اللمس محصورة بشكل السطح. إذا كان .إذا كان clickable() يظهر أولاً، قد تمتد مساحة التفاعل إلى ما بعد الحدود المرئية والمقتطعة للمكوّن.

SurfaceDepthEffect

يدير الصف SurfaceDepthEffect عملية انتقال الظلال بين حالات التفاعل:

• ‫depthEffect: تأثير الظل المستخدَم عندما تكون المساحة في حالتها التلقائية.
• focusedDepthEffect: تأثير الظل المستخدَم عند التركيز على السطح.