يعرض المكوّن Dialog
رسائل منبثقة أو يطلب إدخال المستخدم في
طبقة فوق محتوى التطبيق الرئيسي. تؤدي إلى إنشاء تجربة واجهة مستخدم متداخلة لجذب انتباه المستخدمين.
تشمل حالات استخدام مربّع الحوار ما يلي:
- تأكيد إجراء المستخدم، مثل حذف ملف
- طلب إدخال المستخدم، مثل طلب إدخال بيانات في تطبيق قائمة المهام
- عرض قائمة خيارات للمستخدم لاختيارها، مثل اختيار بلد في إعداد الملف الشخصي
مربع حوار تنبيه
يقدّم العنصر القابل للتجميع 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") } } ) }
يشير هذا التنفيذ إلى عنصر مكوّن رئيسي يُرسِل الوسيطات إلى العنصر المكوّن الثانوي بهذه الطريقة:
@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
هو عنصر تركيبي أساسي لا يقدّم أيّ تنسيق أو
مواقع محدّدة مسبقًا للمحتوى. وهي حاوية بسيطة نسبيًا يجب ملئها بحاوية مثل 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
. في هذه
الحالة، ينفِّذ المكوّن يدويًا واجهة مشابهة للمثال 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") } } } } } }
تظهر عملية التنفيذ هذه على النحو التالي: