مربّع حوار

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

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

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

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

توفّر واجهة برمجة تطبيقات AlertDialog القابلة للإنشاء واجهة برمجة تطبيقات مناسبة لإنشاء مربّع حوار عن موضوع "التصميم المتعدد الأبعاد" تتضمن 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

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

مربّع حوار قابل للإنشاء

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

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

مثال متقدم

في ما يلي قائمة أكثر تقدمًا من عنصر 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

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

مصادر إضافية

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