مربع حوار

يعرض المكوّن 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 هي دالة مركّبة أساسية لا توفّر أي أنماط أو خانات محدّدة مسبقًا للمحتوى. وهي حاوية بسيطة نسبيًا يجب ملؤها بحاوية أخرى، مثل 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. مربّع حوار يتضمّن صورة

مراجع إضافية