کادر گفتگو

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

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

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

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

‫AlertDialog composable یک میانای برنامه‌سازی کاربردی راحت برای ایجاد کردن کادر گفتگوی با زمینه «طراحی مواد» ارائه می‌دهد. AlertDialog پارامترهای خاصی برای مدیریت عناصر خاصی از گفتگو دارد. ازجمله این موارد:

  • title: نوشتاری که در بالای کادر گفتگو نشان داده می‌شود.
  • ‫text: نوشتاری که در مرکز کادر گفتگو نشان داده می‌شود.
  • ‫icon: گرافیکی که در بالای کادر گفتگو نشان داده می‌شود.
  • onDismissRequest: تابعی که وقتی کاربر کادر گفتگو را می‌بندد، مثلاً با ضربه زدن در خارج از آن، فراخوانده می‌شود.
  • ‫dismissButton: یک composable که به‌عنوان دکمه بستن عمل می‌کند.
  • ‫confirmButton: یک composable که به‌عنوان دکمه تأیید عمل می‌کند.

مثال زیر دو دکمه را در کادر گفتگوی هشدار پیاده‌سازی می‌کند، یکی که کادر گفتگو را می‌بندد و دیگری که درخواست آن را تأیید می‌کند.

@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")
                    }
                }
            }
        }
    }
}

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

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

منابع بیشتر