يعرض المكوِّن 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 ) } } } }
تظهر طريقة التنفيذ هذه على النحو التالي:
مربّع حوار قابل للإنشاء
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") } } } } } }
تظهر طريقة التنفيذ هذه على النحو التالي: