مربّع حوار

يعرض المكوِّن 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. مربّع حوار للتنبيه يتضمّن أزرارًا

ملاحظة: عندما ينقر المستخدم على أيّ من الزرَّين، يتم إغلاق مربّع الحوار. عندما يُقرّ العميل على الإجراء، يتم استدعاء دالة تعالج عملية التأكيد أيضًا. ضِمن في هذا المثال، هاتان الدالتان onDismissRequest() وonConfirmRequest().

ملاحظة: في الحالات التي يتطلب فيها مربّع الحوار مجموعة أزرار أكثر تعقيدًا، يمكنك: يستفيدون من استخدام Dialog القابل للإنشاء وملؤه بشكل حر أكثر

تركيب الحوار

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

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

تنبيه: على عكس مثال AlertDialog في القسم السابق، يجب عليك لتحديد حجم وشكل Dialog يدويًا. عليك أيضًا تقديم حاوية داخلية.

مثال أساسي

المثال التالي هو عملية تنفيذ أساسية للعنصر القابل للتجميع 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 أعلاه.

تنبيه: إذا كنت تحتاج فقط إلى عرض مربّع حوار مؤلّف من زرَّين كما في هذا المثال، عليك استخدام AlertDialog وواجهة برمجة التطبيقات الأكثر ملاءمة له. ومع ذلك، إذا كنت تريد وإنشاء مربع حوار أكثر تعقيدًا، ربما باستخدام النماذج والأزرار المتعددة، يجب أن يستخدم Dialog مع المحتوى المخصّص، كما في المثال التالي.

@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. مربّع حوار يتضمّن صورة

مصادر إضافية

• مستندات واجهة مستخدم Material