الأسطح في 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 مع مساحات العرض التي يُراد أن تكون قابلة للتركيز فقط. وبالمثل، يمكنك إنشاء سطح قابل للنقر باستخدام المعدِّل clickable في Compose. يمكنك أيضًا استخدام معدّلات أخرى للواجهات التي تتطلّب إجراءات.

يوضّح الرمز البرمجي التالي أمثلة على كل من المساحات القابلة للتركيز والنقر:

@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")
    }
}
SurfaceSamples.kt

نقاط أساسية حول الرمز

• مصدر التفاعل المشترك لمساحات العرض القابلة للتركيز: يجب أن يشترك كل من .surface() و.focusable() في interactionSource نفسه. يتيح ذلك للسطح الاستجابة لتغييرات التركيز.

• مصدر التفاعل المشترك للأسطح القابلة للنقر: يجب أن يتشارك كل من .surface() و.clickable() interactionSource نفسه. ويضمن ذلك مزامنة الحالات المرئية (مثل الضغط أو التركيز)، ما يتيح لمساحة العرض التفاعل بشكل مرئي مع بيانات أدخلها المستخدم.

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

SurfaceDepthEffect

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

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