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