Dialog

Il componente Dialog mostra i messaggi popup o richiede l'input dell'utente in un livello sopra i contenuti principali dell'app. Crea un'esperienza UI invasiva per catturare l'attenzione degli utenti.

Di seguito sono riportati alcuni casi d'uso di una finestra di dialogo:

• Conferma dell'azione dell'utente, ad esempio l'eliminazione di un file.
• Richiedere input utente, ad esempio in un'app di liste di cose da fare.
• Presentare un elenco di opzioni per la selezione degli utenti, ad esempio la scelta di un paese nella configurazione di un profilo.

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

Finestra di avviso

L'elemento componibile AlertDialog offre un'API utile per la creazione di una finestra di dialogo a tema Material Design. AlertDialog ha parametri specifici per gestire determinati elementi della finestra di dialogo. Tra questi ci sono:

• title: il testo visualizzato nella parte superiore della finestra di dialogo.
• text: il testo visualizzato centrato all'interno della finestra di dialogo.
• icon: l'immagine visualizzata nella parte superiore della finestra di dialogo.
• onDismissRequest: la funzione richiamata quando l'utente chiude la finestra di dialogo, ad esempio toccando all'esterno della finestra di dialogo.
• dismissButton: un componibile che funge da pulsante Ignora.
• confirmButton: un componibile che funge da pulsante di conferma.

L'esempio seguente implementa due pulsanti in una finestra di avviso, uno che consente di chiuderla e un altro di confermarne la richiesta.

@OptIn(ExperimentalMaterial3Api::class)
@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 componibile padre che passa gli argomenti all'elemento componibile figlio 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 si presenta 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, chiama una funzione che gestisce anche la conferma. In questo esempio, queste funzioni sono onDismissRequest() e onConfirmRequest().

Nota: nei casi in cui la finestra di dialogo richiede un insieme più complesso di pulsanti, potresti trarre vantaggio dall'utilizzo dell'elemento componibile Dialog e di compilarlo in modo più libero.

Finestra di dialogo componibile

Dialog è un componibile di base che non fornisce stili o aree predefinite per i contenuti. È un container relativamente semplice che devi completare con un container come Card. Di seguito sono riportati alcuni dei parametri chiave di una finestra di dialogo:

• onDismissRequest: il comando lambda chiamato quando l'utente chiude la finestra di dialogo.
• properties: un'istanza di DialogProperties che fornisce un ambito aggiuntivo per la personalizzazione.

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

Esempio di base

L'esempio seguente è un'implementazione di base dell'elemento componibile Dialog. Tieni presente che utilizza un Card come container 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 ha il seguente aspetto. Tieni presente che quando la finestra di dialogo è aperta, i contenuti principali dell'app sottostanti risultano scuri e in grigio:

Figura 3. Finestra di dialogo minima.

Esempio avanzato

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

Attenzione: se devi visualizzare solo una finestra di dialogo con due pulsanti come in questo esempio, devi utilizzare AlertDialog e l'API più utile. Tuttavia, se vuoi creare una finestra di dialogo più complessa, magari con moduli e più pulsanti, devi usare 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 si presenta come segue:

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

Risorse aggiuntive

• Documentazione sull'interfaccia utente di Material