TimeField
Com rótulo
Par de pontos
Janela de entrega
Das 08:00 às 18:00, de meia em meia hora.
Vazio
Desabilitado
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
| Prop | Tipo | Padrão |
|---|---|---|
defaultValueA hora inicial de quem nao controla o valor de fora. | string | sem padrão |
labelsAs 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 |
maxUltima hora da janela, em `"HH:MM"`. | string | sem padrão |
minPrimeira hora da janela, em `"HH:MM"`. | string | sem padrão |
nameSome no formulario nativo com a hora inteira, e nunca com o texto pela metade. | string | sem padrão |
onValueChangeChamado so com hora inteira: `"08:30"`, ou `""` quando o campo esvazia. | ((value: string) => void) | sem padrão |
renderTroca 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 |
sizeTamanho do campo, o mesmo vocabulario do Input. | "lg""md""sm" | "md" |
stepQuantos minutos o passo anda, pousando na grade. | number | 15 |
valueA hora escolhida, em 24h e sempre `"HH:MM"`. | string | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.