Dialog

הרכיב Dialog מציג הודעות קופצות או בקשות להזנת משתמש בשכבה מעל תוכן האפליקציה הראשי. היא יוצרת חוויה מפריעה בממשק המשתמש, למשוך את תשומת הלב של המשתמשים.

תרחישים לדוגמה לשימוש בתיבת דו-שיח:

• אישור פעולת המשתמש, למשל מחיקת קובץ.
• בקשה לקלט מהמשתמש, למשל באפליקציה של רשימת משימות.
• הצגת רשימה של אפשרויות לבחירת המשתמש, כמו בחירת מדינה בהגדרת פרופיל.

איור 1. דוגמה לתיבת דו-שיח עם טקסט וסמלים.

תיבת דו-שיח של התראה

התוכן הקומפוזבילי AlertDialog מספק API נוח ליצירת תיבת דו-שיח בנושא עיצוב Material Design. ל-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. תיבת דו-שיח של התראה עם לחצנים.

הערה: כשהמשתמש לוחץ על אחד מהלחצנים, תיבת הדו-שיח תיסגר. כאשר שהמשתמש לוחץ על 'אישור', הוא מפעיל פונקציה שמטפלת גם באישור. לחשבון בדוגמה הזו, הפונקציות האלה הן onDismissRequest() ו-onConfirmRequest().

הערה: במקרים שבהם בתיבת הדו-שיח יש קבוצה מורכבת יותר של לחצנים, אפשר להפיק תועלת מהשימוש בתוכן הקומפוזבילי Dialog ולאכלוס אותו בצורה חופשית יותר באופן דומה.

שימוש ברכיבים של תיבת דו-שיח

Dialog הוא רכיב מורכב בסיסי שלא מספק סגנון או משבצות מוגדרות מראש לתוכן. זהו מאגר פשוט יחסית שצריך לאכלס במאגר כמו Card. ריכזנו כאן כמה מהפרמטרים העיקריים של תיבת דו-שיח:

• onDismissRequest: פונקציית ה-lambda שנקראה כשהמשתמש סוגר את תיבת הדו-שיח.
• properties: מופע של DialogProperties שמספק היקף נוסף של התאמה אישית.

זהירות: בשונה מהדוגמה של AlertDialog שבקטע הקודם, כדי לציין באופן ידני את הגודל והצורה של Dialog. בנוסף, צריך לספק מיכל פנימי.

דוגמה בסיסית

הדוגמה הבאה היא הטמעה בסיסית של ה-composable 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. תיבת דו-שיח מינימלית.

דוגמה מתקדמת

בהמשך מופיעה הטמעה מתקדמת יותר של ה-composable Dialog. כאן ברכיב הזה, הרכיב מיישם באופן ידני ממשק דומה ל-AlertDialog לדוגמה שלמעלה.

זהירות: אם אתם צריכים להציג רק תיבת דו-שיח עם שני לחצנים כמו בדוגמה הזו, צריך להשתמש ב-AlertDialog וב-API הנוח יותר שלו. עם זאת, אם רוצים ליצור תיבת דו-שיח מורכבת יותר, אולי עם טפסים וכמה לחצנים, צריך להשתמש ב-Dialog עם תוכן מותאם אישית, כמו בדוגמה הבאה.

@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. תיבת דו-שיח שכוללת תמונה.

מקורות מידע נוספים

• מסמכי העזרה של Material UI