مربّع حوار

يعرض المكوّن Dialog رسائل منبثقة أو يطلب إدخال المستخدم في طبقة فوق محتوى التطبيق الرئيسي. إنه يخلق تجربة واجهة مستخدم مقاطعة لجذب انتباه المستخدم.

تشمل حالات استخدام مربّع الحوار ما يلي:

  • تأكيد إجراء المستخدم، مثل حذف ملف
  • طلب إدخال المستخدم، مثل طلب إدخال بيانات في تطبيق قائمة المهام
  • عرض قائمة خيارات للمستخدم لاختيارها، مثل اختيار بلد في إعداد الملف الشخصي
مربّع حوار مملوء بنصوص ورموز
الشكل 1. مثال على مربّع حوار مملوء بنصوص ورموز

مربع حوار تنبيه

توفّر العنصر القابل للتجميع AlertDialog واجهة برمجة تطبيقات ملائمة لإنشاء مربع حوار بتصميم مستوحى من أسلوب Material Design. يحتوي AlertDialog على مَعلمات محدّدة لمعالجة عناصر معيّنة من مربّع الحوار. ومن بين هذه التحسينات ما يلي:

  • title: النص الذي يظهر في أعلى مربّع الحوار
  • text: النص الذي يظهر في وسط مربّع الحوار
  • icon: الرسم الذي يظهر في أعلى مربّع الحوار
  • onDismissRequest: الدالة التي يتمّ استدعاؤها عندما يغلِق المستخدِم مربّع الحوار، مثلاً من خلال النقر خارج مربّع الحوار
  • ‫dismissButton: عنصر قابل للتجميع يعمل كزر لإغلاق التطبيق
  • confirmButton: عنصر قابل للتجميع يعمل كزر تأكيد

ينفِّذ المثال التالي زرَّين في مربّع حوار تنبيه، أحدهما ل إغلاق مربّع الحوار والآخر لتأكيد الطلب.

@Composable
fun AlertDialogExample(
    onDismissRequest: () -> Unit,
    onConfirmation: () -> Unit,
    dialogTitle: String,
    dialogText: String,
    icon: ImageVector,
) {
    AlertDialog(
        icon = {
            Icon(icon, contentDescription = "Example Icon")
        },
        title = {
            Text(text = dialogTitle)
        },
        text = {
            Text(text = dialogText)
        },
        onDismissRequest = {
            onDismissRequest()
        },
        confirmButton = {
            TextButton(
                onClick = {
                    onConfirmation()
                }
            ) {
                Text("Confirm")
            }
        },
        dismissButton = {
            TextButton(
                onClick = {
                    onDismissRequest()
                }
            ) {
                Text("Dismiss")
            }
        }
    )
}
Dialog.kt

يشير هذا التنفيذ إلى عنصر مكوّن رئيسي يُرسِل الوسيطات إلى العنصر المكوّن الثانوي بهذه الطريقة:

@Composable
fun DialogExamples() {
    // ...
    val openAlertDialog = remember { mutableStateOf(false) }

    // ...
        when {
            // ...
            openAlertDialog.value -> {
                AlertDialogExample(
                    onDismissRequest = { openAlertDialog.value = false },
                    onConfirmation = {
                        openAlertDialog.value = false
                        println("Confirmation registered") // Add logic here to handle confirmation.
                    },
                    dialogTitle = "Alert dialog example",
                    dialogText = "This is an example of an alert dialog with buttons.",
                    icon = Icons.Default.Info
                )
            }
        }
    }
}
Dialog.kt

تظهر عملية التنفيذ هذه على النحو التالي:

مربّع حوار تنبيه مفتوح يحتوي على زرَّي إغلاق وتأكيد
الشكل 2. مربّع حوار تنبيه مزوّد بأزرار

تركيب الحوار

Dialog هو عنصر تركيبي أساسي لا يقدّم أيّ تنسيق أو مواقع محدّدة مسبقًا للمحتوى. إنها حاوية واضحة نسبيًا يجب تعبئتها بحاوية مثل Card. في ما يلي بعض المَعلمات الرئيسية للمحادثة:

  • onDismissRequest: دالة lambda التي يتم استدعاءها عندما يغلق المستخدم مربّع الحوار
  • ‫properties: مثيل DialogProperties يقدّم بعض الساحات الإضافية للتخصيص

مثال أساسي

المثال التالي هو عملية تنفيذ أساسية للعنصر القابل للتجميع Dialog. يُرجى العِلم أنّها تستخدم Card كحاوية ثانوية. بدون Card، سيظهر المكوِّن Text بمفرده فوق محتوى التطبيق الرئيسي.

@Composable
fun MinimalDialog(onDismissRequest: () -> Unit) {
    Dialog(onDismissRequest = { onDismissRequest() }) {
        Card(
            modifier = Modifier
                .fillMaxWidth()
                .height(200.dp)
                .padding(16.dp),
            shape = RoundedCornerShape(16.dp),
        ) {
            Text(
                text = "This is a minimal dialog",
                modifier = Modifier
                    .fillMaxSize()
                    .wrapContentSize(Alignment.Center),
                textAlign = TextAlign.Center,
            )
        }
    }
}
Dialog.kt

تظهر طريقة التنفيذ هذه على النحو التالي. يُرجى العلم أنّه عندما يكون مربّع الحوار مفتوحًا، يظهر محتوى التطبيق الرئيسي تحته بشكل مظلم ورمّادي:

مربّع حوار لا يحتوي على أي شيء سوى تصنيف
الشكل 3. الحد الأدنى من مربّعات الحوار

مثال متقدّم

في ما يلي قائمة أكثر تقدمًا من عنصر Dialog القابل للإنشاء. في هذه الحالة، ينفِّذ المكوّن يدويًا واجهة مشابهة للمثال AlertDialog أعلاه.

@Composable
fun DialogWithImage(
    onDismissRequest: () -> Unit,
    onConfirmation: () -> Unit,
    painter: Painter,
    imageDescription: String,
) {
    Dialog(onDismissRequest = { onDismissRequest() }) {
        // Draw a rectangle shape with rounded corners inside the dialog
        Card(
            modifier = Modifier
                .fillMaxWidth()
                .height(375.dp)
                .padding(16.dp),
            shape = RoundedCornerShape(16.dp),
        ) {
            Column(
                modifier = Modifier
                    .fillMaxSize(),
                verticalArrangement = Arrangement.Center,
                horizontalAlignment = Alignment.CenterHorizontally,
            ) {
                Image(
                    painter = painter,
                    contentDescription = imageDescription,
                    contentScale = ContentScale.Fit,
                    modifier = Modifier
                        .height(160.dp)
                )
                Text(
                    text = "This is a dialog with buttons and an image.",
                    modifier = Modifier.padding(16.dp),
                )
                Row(
                    modifier = Modifier
                        .fillMaxWidth(),
                    horizontalArrangement = Arrangement.Center,
                ) {
                    TextButton(
                        onClick = { onDismissRequest() },
                        modifier = Modifier.padding(8.dp),
                    ) {
                        Text("Dismiss")
                    }
                    TextButton(
                        onClick = { onConfirmation() },
                        modifier = Modifier.padding(8.dp),
                    ) {
                        Text("Confirm")
                    }
                }
            }
        }
    }
}
Dialog.kt

تظهر عملية التنفيذ هذه على النحو التالي:

مربّع حوار يعرض صورة لجبل "فيذرتوب" في "فيكتوريا". تحت الصورة، يظهر زر إغلاق وزر تأكيد.
الشكل 4. مربّع حوار يتضمّن صورة

مصادر إضافية