گفتگو

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

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

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

گفتگوی هشدار

AlertDialog composable یک API مناسب برای ایجاد یک گفتگو با موضوع طراحی مواد ارائه می دهد. 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 والد است که آرگومان های قابل ترکیب را به این ترتیب به فرزند ارسال می کند:

@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 : زمانی که کاربر کادر گفتگو را می بندد، لامبدا فراخوانی می شود.
  • properties : نمونه ای از DialogProperties که فضای بیشتری را برای سفارشی سازی فراهم می کند.

مثال اساسی

مثال زیر یک پیاده سازی اساسی از Dialog composable است. توجه داشته باشید که از یک 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 composable است. در این مورد، کامپوننت به صورت دستی یک رابط مشابه با مثال 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")
                    }
                }
            }
        }
    }
}

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

گفتگو با عکسی از کوه Feathertop، ویکتوریا. در زیر تصویر یک دکمه رد کردن و یک دکمه تایید وجود دارد.
شکل 4. یک گفتگو که شامل یک تصویر است.

منابع اضافی