يعرض المكوِّن 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") } } ) }
يشير هذا التنفيذ إلى وجود عنصر رئيسي قابل للإنشاء ينقل الوسيطات إلى وقابل للإنشاء بهذه الطريقة:
@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 ) } } } }
تظهر طريقة التنفيذ هذه على النحو التالي:
![مربّع حوار مفتوح للتنبيه يحتوي على زرَّي الإغلاق والتأكيد](https://developer.android.google.cn/static/develop/ui/compose/images/components/dialog-alert.png?authuser=7&hl=ar)
مربّع حوار قابل للإنشاء
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, ) } } }
تظهر طريقة التنفيذ هذه على النحو التالي. لاحظ أنه عند فتح مربع الحوار، يظهر محتوى التطبيق الرئيسي أسفله معتم ورمادي:
![مربّع حوار لا يحتوي سوى على تصنيف](https://developer.android.google.cn/static/develop/ui/compose/images/components/dialog-minimal.png?authuser=7&hl=ar)
مثال متقدم
في ما يلي قائمة أكثر تقدمًا من عنصر 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") } } } } } }
تظهر طريقة التنفيذ هذه على النحو التالي:
![مربّع حوار يعرض صورة لجبل "فيثروب" (فيكتوريا). يتوفّر أسفل الصورة زرّ إغلاق وزر تأكيد.](https://developer.android.google.cn/static/develop/ui/compose/images/components/dialog-image.png?authuser=7&hl=ar)