مربع حوار

يعرض مكوّن 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

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 Design