Dialog

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

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

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

الشكل 1. مثال على مربّع حوار مملوء بنصوص ورموز

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

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

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

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

@OptIn(ExperimentalMaterial3Api::class)
@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 UI