Seletores de horário

Os seletores de horário são uma maneira de os usuários escolherem um horário. Você pode usar os elementos combináveis TimePicker e TimeInput para implementar um horário seletor no seu app.

Tipos

Há dois tipos de seletor de horário:

  • Discagem: permite que os usuários definam um horário movendo uma alça em volta de um controle.
  • Entrada: permite que os usuários definam um horário usando o teclado.

A imagem a seguir fornece um exemplo de um seletor de horário do discador à esquerda e um seletor de horário de entrada à direita:

Um mostrador e um seletor de horário de entrada.
Figura 1. Um mostrador e um seletor de horário de entrada.

Plataforma da API

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

  • TimePicker: implementa um seletor de horário de discagem.
  • TimeInput: implementa um seletor de horário 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 que o usuário selecionou 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 ver exemplos que usam caixas de diálogo, consulte o guia Caixas de diálogo para seletores de horário.

Seletor de horário de discagem

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

@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 o tempo de resposta.
  • O elemento combinável TimePicker mostra o seletor de horário, considerando timePickerState como parâmetro.
  • A implementação inclui dois botões: um para confirmar a seleção e outro para dispensar o seletor.

Essa 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 horário 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 observar nesta implementação:

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

Essa 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 tempo que o usuário selecionou em um seletor de horário, transmita o valor TimePickerState adequada à função onConfirm. O pai pode acessar o horário selecionado usando TimePickerState.hour e TimePickerState.minute.

O snippet a seguir demonstra 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 desta forma:

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 nos snippets app.

Outros recursos