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