مربّع حوار

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

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

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

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

توفّر واجهة برمجة تطبيقات 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")
            }
        }
    )
}
Dialog.kt

يتضمن هذا التنفيذ عنصرًا رئيسيًا قابلاً للإنشاء ينقل الوسيطات إلى العنصر الثانوي القابل للإنشاء بهذه الطريقة:

@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.kt

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

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

مربّع حوار قابل للإنشاء

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.kt

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

مربّع حوار لا يحتوي سوى على تصنيف
الشكل 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")
                    }
                }
            }
        }
    }
}
Dialog.kt

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

مربّع حوار يعرض صورة لجبل "فيثروب" (فيكتوريا). يتوفّر أسفل الصورة زرّ إغلاق وزر تأكيد.
الشكل 4. مربّع حوار يتضمّن صورة

مصادر إضافية