Seletores de horário

Os seletores de horário permitem que os usuários escolham um horário. Você pode usar os elementos combináveis TimePicker e TimeInput para implementar um seletor de tempo no seu app.

Tipos

Há dois tipos de seletor de tempo:

  • Dial: permite que os usuários definam um horário movendo uma alça em um dial.
  • Entrada: permite que os usuários definam um horário usando o teclado.

A imagem a seguir mostra um exemplo de um seletor de tempo de discagem à esquerda e um seletor de tempo de entrada à direita:

Um botão giratório e um seletor de horário de entrada.
Figura 1. Um mostrador e um seletor de horário de entrada.

Superfície da API

Para implementar um seletor de horário, use o elemento combinável TimePicker ou TimeInput:

  • TimePicker: implementa um seletor de tempo de discagem.
  • TimeInput: implementa um seletor de tempo de entrada.

Estado

Para TimePicker e TimeInput, você também precisa transmitir um TimePickerState. Assim, você pode definir o horário padrão selecionado que aparece no seletor. Ele também captura o horário selecionado pelo usuário usando o seletor.

Dialog

Os seletores de horário aparecem em caixas de diálogo. Os exemplos neste guia não usam caixas de diálogo. Para exemplos que usam caixas de diálogo, consulte o guia Caixas de diálogo para seletores de tempo.

Seletor de horário de discagem

Este snippet demonstra como implementar um seletor de tempo de discagem básico.

@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

Considere o seguinte neste snippet:

  • Calendar.getInstance() inicializa o TimePickerState com a hora atual.
    • Este exemplo usa java.util.Calendar. Ative a simplificação da API Java 8+ no seu projeto para usar java.time.LocalTime em todas as versões do Android.
  • O elemento combinável TimePicker mostra o seletor de horário, usando timePickerState como parâmetro.
  • A implementação inclui dois botões: um para confirmar a seleção e outro para dispensar o seletor.

Esta implementação aparece da seguinte maneira:

Um seletor de horário de discagem. O usuário pode selecionar um horário usando o mostrador.
Figura 2. Um seletor de horário de discagem.

Seletor de horário de entrada

Este snippet demonstra como implementar um seletor de tempo de estilo de entrada básico.

@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

Pontos principais a serem observados nesta implementação:

  • A estrutura é essencialmente a mesma do seletor de tempo de discagem, com a principal diferença sendo o uso de TimeInput em vez de TimePicker.
  • O parâmetro is24Hour para timePickerState está definido explicitamente como true. Por padrão, esse valor é false.

Esta implementação aparece da seguinte maneira:

Um seletor de horário de entrada. O usuário pode inserir um horário usando campos de texto.
Figura 3. Um seletor de horário de entrada.

Usar o estado

Para usar o horário selecionado pelo usuário em um seletor de horário, transmita o TimePickerState adequado à sua função onConfirm. O elemento combinável pai pode acessar o horário selecionado usando TimePickerState.hour e TimePickerState.minute.

O snippet a seguir mostra como fazer isso:

@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

Em seguida, você pode chamar o elemento combinável assim:

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.") }

Para mais detalhes, consulte a implementação completa no app Snippets.

Outros recursos