Sélecteurs d'heure

Les sélecteurs d'heure permettent aux utilisateurs de sélectionner une heure. Vous pouvez utiliser les TimePicker et TimeInput composables pour implémenter un sélecteur d'heure dans votre application.

Types

Il existe deux types de sélecteurs d'heure :

  • Cadran : permet aux utilisateurs de définir une heure en déplaçant une poignée autour d'un cadran.
  • Entrée : permet aux utilisateurs de définir une heure à l'aide de leur clavier.

L'image suivante fournit un exemple de sélecteur d'heure à cadran à gauche et de sélecteur d'heure à entrée à droite :

Un sélecteur d'heure à cadran et à saisie.
Figure 1. Sélecteur d'heure à cadran et à entrée.

Surface d'API

Pour implémenter un sélecteur d'heure, utilisez le composable TimePicker ou TimeInput :

  • TimePicker: implémente un sélecteur d'heure à cadran.
  • TimeInput: implémente un sélecteur d'heure à entrée.

État

Pour TimePicker et TimeInput, vous devez également transmettre un TimePickerState. Cela vous permet de définir l'heure sélectionnée par défaut qui s'affiche dans le sélecteur. Il capture également l'heure que l'utilisateur a sélectionnée à l'aide du sélecteur.

Boîte de dialogue

Les sélecteurs d'heure s'affichent dans des boîtes de dialogue. Les exemples de ce guide n'utilisent pas de boîtes de dialogue. Pour obtenir des exemples qui utilisent des boîtes de dialogue, consultez le guide Boîtes de dialogue pour les sélecteurs d'heure.

Sélecteur d'heure à cadran

Cet extrait montre comment implémenter un sélecteur d'heure à cadran de base.

@Composable
fun DialExample(
    onConfirm: () -> Unit,
    onDismiss: () -> Unit,
) {
    val currentTime = Calendar.getInstance()

    val timePickerState = rememberTimePickerState(
        initialHour = currentTime.get(Calendar.HOUR_OF_DAY),
        initialMinute = currentTime.get(Calendar.MINUTE),
        is24Hour = true,
    )

    Column {
        TimePicker(
            state = timePickerState,
        )
        Button(onClick = onDismiss) {
            Text("Dismiss picker")
        }
        Button(onClick = onConfirm) {
            Text("Confirm selection")
        }
    }
}
TimePickers.kt

Tenez compte des éléments suivants dans cet extrait :

  • Calendar.getInstance() initialise le TimePickerState avec l'heure actuelle.
  • Le composable TimePicker affiche le sélecteur d'heure, en prenant timePickerState comme paramètre.
  • L'implémentation inclut deux boutons : un pour confirmer la sélection et un autre pour fermer le sélecteur.

Cette implémentation est la suivante :

Sélecteur d'heure à cadran. L'utilisateur peut sélectionner une heure à l'aide du sélecteur.
Figure 2. Sélecteur d'heure à cadran.

Sélecteur d'heure à entrée

Cet extrait montre comment implémenter un sélecteur d'heure de style d'entrée de base.

@Composable
fun InputExample(
    onConfirm: () -> Unit,
    onDismiss: () -> Unit,
) {
    val currentTime = Calendar.getInstance()

    val timePickerState = rememberTimePickerState(
        initialHour = currentTime.get(Calendar.HOUR_OF_DAY),
        initialMinute = currentTime.get(Calendar.MINUTE),
        is24Hour = true,
    )

    Column {
        TimeInput(
            state = timePickerState,
        )
        Button(onClick = onDismiss) {
            Text("Dismiss picker")
        }
        Button(onClick = onConfirm) {
            Text("Confirm selection")
        }
    }
}
TimePickers.kt

Points clés à noter dans cette implémentation :

  • La structure est essentiellement la même que celle du sélecteur d'heure à cadran, la principale différence étant l'utilisation de TimeInput au lieu de TimePicker.
  • Le paramètre is24Hour de timePickerState est explicitement défini sur true. Par défaut, cette valeur est false.

Cette implémentation est la suivante :

Sélecteur d'heure d'entrée. L'utilisateur peut saisir une heure à l'aide de champs de texte.
Figure 3. Sélecteur d'heure à entrée.

Utiliser l'état

Pour utiliser l'heure que l'utilisateur a sélectionnée dans un sélecteur d'heure, transmettez le TimePickerState approprié à votre fonction onConfirm. Le composable parent peut ensuite accéder à l'heure sélectionnée via TimePickerState.hour et TimePickerState.minute.

L'extrait suivant montre comment procéder :

@Composable
fun DialUseStateExample(
    onConfirm: (TimePickerState) -> Unit,
    onDismiss: () -> Unit,
) {
    val currentTime = Calendar.getInstance()

    val timePickerState = rememberTimePickerState(
        initialHour = currentTime.get(Calendar.HOUR_OF_DAY),
        initialMinute = currentTime.get(Calendar.MINUTE),
        is24Hour = true,
    )

    Column {
        TimePicker(
            state = timePickerState,
        )
        Button(onClick = onDismiss) {
            Text("Dismiss picker")
        }
        Button(onClick = { onConfirm(timePickerState) }) {
            Text("Confirm selection")
        }
    }
}
TimePickers.kt

Vous pouvez ensuite appeler le composable comme suit :

var selectedTime: TimePickerState? by remember { mutableStateOf(null) }

// ...

DialUseStateExample(
    onDismiss = {
        showDialExample = false
    },
    onConfirm = {
            time ->
        selectedTime = time
        showDialExample = false
    },
)

// ...

if (selectedTime != null) {
    val cal = Calendar.getInstance()
    cal.set(Calendar.HOUR_OF_DAY, selectedTime!!.hour)
    cal.set(Calendar.MINUTE, selectedTime!!.minute)
    cal.isLenient = false
    Text("Selected time = ${formatter.format(cal.time)}")
} else {
    Text("No time selected.")
}

Pour en savoir plus, consultez l'implémentation complète dans l'application d'extraits.

Ressources supplémentaires