مربع حوار

يعرض مكوّن 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")
            }
        }
    )
}
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

Dialog هو عنصر مركّب أساسي لا يوفّر أي تنسيق أو مواضع محدّدة مسبقًا للمحتوى. وهو حاوية بسيطة نسبيًا يجب تعبئتها بحاوية مثل Card. في ما يلي بعض المَعلمات الرئيسية لمربّع الحوار:

  • onDismissRequest: تعبير لامدا يتم استدعاؤه عندما يغلق المستخدم مربّع الحوار
  • 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. مربّع حوار يتضمّن صورة

مراجع إضافية