مربع حوار

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

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

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

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

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

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

مربّع حوار تنبيه مفتوح يحتوي على زرَّي "إغلاق" و"تأكيد"
الشكل 2. مربّع حوار للتنبيه يتضمّن أزرارًا

الدالة المركّبة Dialog

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,
            )
        }
    }
}

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

مربّع حوار لا يحتوي على أي شيء سوى تصنيف
الشكل 3. مربّع حوار بسيط

مثال متقدّم

في ما يلي تنفيذ أكثر تقدّمًا للدالة المركّبة 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")
                    }
                }
            }
        }
    }
}

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

مربّع حوار يعرض جبل فيذرتوب في فيكتوريا، مع زرَّي رفض وتأكيد
الشكل 4. مربّع حوار يتضمّن صورة

مراجع إضافية