Finestra di dialogo

Il componente Dialog mostra messaggi popup o richiede l'input dell'utente su un livello sopra i contenuti principali dell'app. Crea un'esperienza utente che interrompe per attirare l'attenzione dell'utente.

Ecco alcuni casi d'uso per una finestra di dialogo:

• Conferma dell'azione dell'utente, ad esempio quando viene eliminato un file.
• Richiesta di input dell'utente, ad esempio in un'app per l'elenco di cose da fare.
• Presentazione di un elenco di opzioni per la selezione da parte dell'utente, ad esempio la scelta di un paese nella configurazione di un profilo.

Figura 1. Esempio di una finestra di dialogo popolata con testo e icone.

Finestra di avviso

Il composable AlertDialog fornisce un'API comoda per creare una finestra di dialogo in tema Material Design. AlertDialog ha parametri specifici per gestire determinati elementi della finestra di dialogo. Tra questi:

• title: il testo visualizzato nella parte superiore della finestra di dialogo.
• text: il testo visualizzato al centro della finestra di dialogo.
• icon: l'immagine visualizzata nella parte superiore della finestra di dialogo.
• onDismissRequest: la funzione chiamata quando l'utente chiude la finestra di dialogo, ad esempio toccando al di fuori.
• dismissButton: un composable che funge da pulsante di chiusura.
• confirmButton: un componibile che funge da pulsante di conferma.

L'esempio seguente implementa due pulsanti in una finestra di dialogo di avviso, uno che chiude la finestra di dialogo e un altro che conferma la richiesta.

@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

Questa implementazione implica un elemento componibile principale che passa gli argomenti all'elemento componibile secondario in questo modo:

@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

Questa implementazione è visualizzata come segue:

Figura 2. Una finestra di dialogo di avviso con pulsanti.

Nota: quando l'utente fa clic su uno dei pulsanti, la finestra di dialogo si chiude. Quando l'utente fa clic su Conferma, viene chiamata una funzione che gestisce anche la conferma. In questo esempio, queste funzioni sono onDismissRequest() e onConfirmRequest().

Nota: se la finestra di dialogo richiede un insieme di pulsanti più complesso, ti consigliamo di utilizzare il composable Dialog e di compilarlo in modo più libero.

Componenti composibili di dialogo

Dialog è un componente componibile di base che non fornisce stili o scomparti predefiniti per i contenuti. Si tratta di un contenitore relativamente semplice che deve essere compilato con un contenitore come Card. Di seguito sono riportati alcuni degli parametri chiave di una finestra di dialogo:

• onDismissRequest: la funzione lambda chiamata quando l'utente chiude la finestra di dialogo.
• properties: un'istanza di DialogProperties che offre un ambito aggiuntivo per la personalizzazione.

Attenzione: a differenza dell'esempio di AlertDialog nella sezione precedente, devi specificare manualmente le dimensioni e la forma di Dialog. Devi anche fornire un container interno.

Esempio di base

L'esempio seguente è un'implementazione di base del composable Dialog. Tieni conto che utilizza un Card come contenitore secondario. Senza Card, il componente Text verrebbe visualizzato da solo sopra i contenuti principali dell'app.

@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

Questa implementazione è visualizzata come segue. Tieni presente che, quando la finestra di dialogo è aperta, i contenuti principali dell'app sottostante appaiono scuri e non selezionabili:

Figura 3. Finestra di dialogo minima.

Esempio avanzato

Di seguito è riportata un'implementazione più avanzata del componibile Dialog. In questo caso, il componente implementa manualmente un'interfaccia simile a quella dell'AlertDialog esempio riportato sopra.

Attenzione: se devi solo visualizzare una finestra di dialogo con due pulsanti come in questo esempio, devi utilizzare AlertDialog e la relativa API più pratica. Tuttavia, se vuoi creare una finestra di dialogo più complessa, ad esempio con moduli e più pulsanti, devi utilizzare Dialog con contenuti personalizzati, come nell'esempio seguente.

@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

Questa implementazione è visualizzata come segue:

Figura 4. Una finestra di dialogo che include un'immagine.

Risorse aggiuntive

• Documentazione di Material UI