کادر گفتگو

عنصر Dialog پیام‌های کادر گفتگو را نمایش می‌دهد یا ورودی کاربر را در لایه‌ای بالای محتوای اصلی برنامه درخواست می‌کند. این کار باعث ایجاد تجربه میانای کاربر مزاحم برای جلب توجه کاربر می‌شود.

ازجمله موارد استفاده برای کادر گفتگو می‌توان به موارد زیر اشاره کرد:

  • تأیید کنش کاربر، مثلاً هنگام حذف فایل.
  • درخواست درونداد کاربر، مثلاً در برنامه فهرست کارها.
  • ارائه فهرستی از گزینه‌ها برای انتخاب کاربر، مانند انتخاب کشور در راه‌اندازی نمایه.
کادر گفتگویی که با نوشتار و نمادها پر شده است.
شکل ۱. مثالی از کادر گفتگویی که با نوشتار و نمادها تکمیل شده است.

کادر گفتگوی هشدار

عنصر AlertDialog composable میانای برنامه‌سازی کاربردی مناسبی برای ایجاد کادر گفتگوی زمینه‌دار «طراحی مواد» ارائه می‌دهد. ‫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
                )
            }
        }
    }
}

این پیاده‌سازی به‌صورت زیر نشان داده می‌شود:

کادر گفتگوی هشدار باز که هم دکمه بستن و هم دکمه تأیید دارد.
شکل ۲. کادر گفتگوی هشداری با دکمه‌ها.

تابع ترکیب‌پذیر کادر گفتگو

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 ارائه شده است. در این مورد، عنصر به‌صورت دستی رابط مشابهی را با مثال 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")
                    }
                }
            }
        }
    }
}

این پیاده‌سازی به‌صورت زیر نشان داده می‌شود:

کادر گفتگویی که «کوه فِذرتوپ، ویکتوریا» را با دکمه بستن و دکمه تأیید نمایش می‌دهد.
شکل ۴. کادر گفتگویی که شامل تصویر است.

منابع بیشتر