Pular para o conteúdo
Formulário

TimeField

/componentes/time-field.mdmarkdown cru, para quem lê com agent em vez de olho

Com rótulo

Par de pontos

Janela de entrega

Das 08:00 às 18:00, de meia em meia hora.

Vazio

Desabilitado

Importar
import { TimeField } from '@rivocode/ui'

Quando usar

Campo de hora digitável, em 24 horas.

Quem marca ponto, agenda consulta ou fecha janela de entrega digita 0800 mais rápido do que abre qualquer painel. Por isso o campo existe sozinho: o TimePicker é ele com um painel em cima, e não o contrário.

Os dois pontos entram sozinhos enquanto se digita, e o campo para em quatro dígitos. Não existe AM/PM: o valor é sempre 24 horas, que é o que o backend entende sem discussão.

O valor é texto, e não Date

O valor é uma string no formato "14:30", e o campo vazio é "".

Date obrigaria a inventar um dia para uma hora que não tem dia, e um dia inventado carrega fuso, horário de verão e a virada de meia-noite junto. Quem agenda "entrega às 14:30" quer exatamente esses cinco caracteres no banco, e é isso que onValueChange entrega:

const [entrada, setEntrada] = useState('08:00')

<TimeField value={entrada} onValueChange={setEntrada} />

Só hora inteira avisa. Digitar 14 não chama onValueChange, do mesmo jeito que 03/03 não vira data no DatePicker. Quem escuta nunca recebe meia hora, e por isso nunca precisa validar o que chega.

Três funções fazem a ponte e saem pelo pacote, porque tela que mostra hora fora de um campo precisa das mesmas regras:

Função O que faz
applyTimeMask(texto) A máscara enquanto se digita: põe os dois pontos e para em quatro dígitos
parseTime(texto) "HH:MM" para minutos desde a meia-noite, e undefined para o que não é hora
formatTime(minutos) Minutos para "HH:MM", e string vazia quando não há hora

O que acontece com 25:99

Nada é emitido, e o campo se marca inválido na mesma tecla, sem esperar o blur, porque a pessoa ainda está olhando para o campo quando erra.

Ao sair do campo, o texto impossível fica no campo, marcado e com a mensagem ligada por aria-describedby, e o valor esvazia para "", como 31/02 no DatePicker. Até a 1.2 ele voltava para a última hora válida, e voltar em silêncio apaga o que a pessoa digitou sem dizer por quê. Consertar (25:99 virando 23:59) seria pior ainda: ninguém confere um valor que o campo "aceitou". Hora pela metade, como 14, segue a mesma regra ao sair.

Dentro de <Field>, a mensagem vai para a validade do campo e quem a mostra é o FieldError, que acende ao sair do campo mesmo sem Form em volta; fora dele, a peça a mostra logo abaixo. Com readOnly ou dentro de <Field disabled>, nem a seta nem o mais e o menos do celular mudam a hora. Os textos se trocam pelo labels.

Enquanto se digita, 1 e 14 não acusam nada. Só o par completo e impossível acende o campo. Acusar prefixo é acusar quem ainda está escrevendo.

Passo e janela

step é em minutos e governa o passo, não a validação. O passo pousa na grade a partir da meia-noite e não soma o passo cru: com step={15}, 14:07 sobe para 14:15, e não para 14:22. Com o campo vazio, o passo para cima começa na abertura da janela.

Quem anda o passo é a seta ↑/↓ no teclado, e são os dois botões de mais e de menos no celular: as duas portas chamam a mesma conta.

min e max desenham a janela de entrega ou o turno. Hora fora dela chega em quem escuta e o campo se marca inválido: a pessoa digitou uma hora de verdade, e apagar o trabalho dela esconde o erro em vez de mostrá-lo. Ao sair do campo aparece a mensagem com o limite; o formulário que sabe por que a janela é aquela troca o texto pelo labels.

<Field>
  <FieldLabel>Horário da entrega</FieldLabel>
  <TimeField defaultValue="09:00" min="08:00" max="18:00" step={30} />
  <FieldDescription>Das 08:00 às 18:00, de meia em meia hora.</FieldDescription>
</Field>

Hora digitada fora da grade continua valendo: 14:07 com step={30} é uma hora legítima, e recusá-la seria transformar uma conveniência de teclado em regra de negócio.

Turno que atravessa a meia-noite (min="22:00" com max="06:00") não é suportado: a janela invertida é ignorada e o campo aceita o dia inteiro. Duas horas sem data não conseguem dizer qual delas é do dia seguinte.

O passo no dedo

Abaixo de 640px o campo veste [−][campo][+], e sem prop nenhuma: o telefone não tem seta ↑/↓, e os dois botões chamam o mesmo cálculo dela, então pousam na mesma grade do step e param na mesma janela de min e max. Cada um tem 44px de largura. A moldura tem a altura do Input do mesmo size, como todo campo da casa, e com os botões a hora fica no meio, como no NumberField. Na mesa eles não aparecem, porque lá a seta já dá o passo, e dentro do TimePicker também não, porque o painel dele já cumpre esse papel.

Os botões herdam o nome do rótulo do campo (FieldLabel, label for ou aria-label): numa agenda com "Entrada" e "Saída", o leitor de tela ouve "Aumentar Entrada" e "Aumentar Saída". Campo sem rótulo fica com "Aumentar" e "Diminuir" secos, então dê um nome a ele. A hora em que o passo pousou, pelo botão ou pela seta, é dita numa região viva ao lado do campo; digitar não anuncia, porque quem digita já ouve o próprio teclado.

No formulário nativo

Com name, um campo escondido carrega a hora inteira, e nunca o texto pela metade: enviar 08 porque alguém apertou Enter no meio da digitação é o tipo de dado que só aparece semanas depois, no relatório.

Quando não usar

Para escolher a hora sem digitar nada, use TimePicker: é este campo com um painel de horas e minutos, e no celular o painel vira folha de baixo. Ele oferece a hora inteira pronta para escolher; o passo no toque este campo já alcança sozinho.

Para data, DatePicker; para data e hora juntas, os dois lado a lado, cada um guardando o seu texto.

Para duração ("2h30 de serviço"), nenhum dos dois: duração não é hora do dia, e NumberField em minutos soma, compara e não tem meia-noite para atravessar.

Para hora escrita à mão sem regra nenhuma, o MaskedInput com molde hora põe os dois pontos e para por aí. Ele não conhece 25:99, não conhece janela e não tem passo: nem seta, nem botão.

No React Native

Traduz, e continua sendo o campo de DIGITAR: quem marca ponto escreve 0800 mais rápido do que abre painel, e o teclado numérico do sistema é o idioma disso.

As regras de valor atravessam inteiras. "HH:MM" em 24h, vazio é "", e só hora completa avisa quem escuta. 25:99 não é consertado em silêncio para 23:59: marca inválido na mesma tecla e volta ao último válido ao sair. Aqui os lados divergem: no web o texto impossível fica no campo ao sair, com a mensagem, e o valor esvazia. Consertar calado é pior, porque ninguém confere valor que o campo "aceitou". O step governa os passos e as opções, nunca a validação, então 14:07 com step={30} continua sendo hora legítima.

Os dois lados ganharam o botão de passo, e o nativo chegou primeiro. Seta não existe no toque, e step precisava continuar significando alguma coisa; em vez de inventar gesto, a peça vestiu o molde que a casa já tem para passo no dedo, [−][campo][+] do NumberField. O web tinha o mesmo buraco num telefone, e o adotou depois: lá os botões só aparecem abaixo de 640px, porque na mesa a seta já é a porta e não ocupa pixel. Aqui eles estão sempre, porque mesa não existe. Os dois chamam o mesmo cálculo, então pousam na mesma grade a partir da meia-noite; a diferença é o alvo, 48pt aqui contra 44 lá.

Caem defaultValue (aqui tudo é controlado), name (formulário escondido não existe no React Native) e size (o Input nativo não tem vocabulário de tamanho).

Dentro de um Field ele lê o erro, como o Input. A mensagem acende a borda e vira a dica falada do campo, e sair dele conta para o validationMode="onBlur". No FormField, entra por {...forValue(row)}, que leva o invalid só quando há erro: o false calaria a hora impossível e a fora da janela, que o próprio campo marca.

API

PropTipoPadrão
defaultValue

A hora inicial de quem nao controla o valor de fora.

stringsem padrão
labels

As mensagens da hora digitada que nao vale, que aparecem ao sair do campo: `incomplete`, `invalid`, e `tooEarly` e `tooLate`, que recebem o limite em `"HH:MM"`.

Partial<TimeFieldLabels>sem padrão
max

Ultima hora da janela, em `"HH:MM"`.

stringsem padrão
min

Primeira hora da janela, em `"HH:MM"`.

stringsem padrão
name

Some no formulario nativo com a hora inteira, e nunca com o texto pela metade.

stringsem padrão
onValueChange

Chamado so com hora inteira: `"08:30"`, ou `""` quando o campo esvazia.

((value: string) => void)sem padrão
render

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, FieldControlState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
size

Tamanho do campo, o mesmo vocabulario do Input.

"lg""md""sm""md"
step

Quantos minutos o passo anda, pousando na grade.

number15
value

A hora escolhida, em 24h e sempre `"HH:MM"`.

stringsem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.