useStandaloneTimePicker
Gestiona el estado del tiempo con comportamiento de abrir/cerrar y clic fuera.
Import
import { useStandaloneTimePicker } from "react-date-range-picker-headless";Uso
import { useState } from "react";import { useStandaloneTimePicker } from "react-date-range-picker-headless";
function MyTimePicker() { const [time, setTime] = useState<Date | null>(null);
const picker = useStandaloneTimePicker({ value: time, onChange: setTime, time: { precision: "minute", hourFormat: "24", minuteStep: 5 }, placeholder: "Seleccionar hora", });
return ( <div ref={picker.containerRef}> <button onClick={picker.handleToggle}> {picker.hasValue ? picker.displayValue : "Seleccionar hora"} </button>
{picker.isOpen && ( <div ref={picker.popupRef} onKeyDown={picker.handleKeyDown}> <div> <span>{String(picker.tempHour).padStart(2, "0")}</span> <span>:</span> <span>{String(picker.tempMinute).padStart(2, "0")}</span> </div>
{/* Conectar controles de hora/minuto */} <input type="range" min={0} max={23} value={picker.tempHour} onChange={(e) => picker.handleHourChange(Number(e.target.value))} /> <input type="range" min={0} max={55} step={5} value={picker.tempMinute} onChange={(e) => picker.handleMinuteChange(Number(e.target.value))} />
<div> <button onClick={picker.handleClear}>Limpiar</button> <button onClick={picker.handleCancel}>Cancelar</button> <button onClick={picker.handleConfirm}>Confirmar</button> </div> </div> )} </div> );}Opciones
| Opción | Tipo | Por defecto | Descripción |
|---|---|---|---|
value | Date | null | — | Requerido. Hora actual como un objeto Date (solo se usa la porción de la hora). |
onChange | (date: Date | null) => void | — | Requerido. Se llama cuando se confirma la hora. |
time | TimeConfig | { precision: "minute", hourFormat: "24", minuteStep: 5, secondStep: 1 } | Configuración del selector de hora. |
locale | Partial<Locale> | DEFAULT_LOCALE | Sobrescribir las cadenas de la localización. |
displayFormat | string | — | Cadena de formato personalizada para la visualización del disparador. |
placeholder | string | — | Texto de marcador de posición cuando no se ha seleccionado ningún valor. |
open | boolean | — | Estado de apertura controlado. |
initialOpen | boolean | false | Estado de apertura inicial (no controlado). |
onOpenChange | (open: boolean) => void | — | Callback cuando cambia el estado de apertura. |
required | boolean | false | Cuando es verdadero, handleClear no hace nada. |
inline | boolean | false | Mostrar siempre el panel sin un disparador/popup. |
name | string | — | Nombre del input oculto para el envío del formulario. |
Valores de Retorno
| Nombre | Tipo | Descripción |
|---|---|---|
isOpen | boolean | Indica si el popup está actualmente abierto. |
handleOpen | () => void | Abre el popup. |
handleClose | () => void | Cierra el popup. |
handleToggle | () => void | Alterna el popup. |
tempHour | number | Valor de hora temporal actual. |
tempMinute | number | Valor de minuto temporal actual. |
tempSecond | number | Valor de segundo temporal actual. |
tempPeriod | TimePeriod | Período AM/PM actual. |
handleHourChange | (hour: number) => void | Actualiza la hora temporal. |
handleMinuteChange | (minute: number) => void | Actualiza el minuto temporal. |
handleSecondChange | (second: number) => void | Actualiza el segundo temporal. |
handlePeriodChange | (period: TimePeriod) => void | Actualiza el período AM/PM. |
handleConfirm | () => void | Confirma la hora temporal, llama a onChange y cierra el popup. |
handleCancel | () => void | Revierte al valor original y cierra el popup. |
handleClear | () => void | Limpia el valor y cierra. No hace nada si es required. |
displayValue | string | Cadena de hora formateada para el disparador (valor confirmado). |
timeDisplayValue | string | Cadena de hora formateada para el panel (valor temporal). |
hasValue | boolean | Indica si se ha establecido un valor de hora. |
canConfirm | boolean | Indica si el botón de confirmar debe estar habilitado. |
locale | Locale | Objeto de localización resuelto. |
resolvedTimeConfig | Required<TimeConfig> | Configuración de hora completamente resuelta. |
containerRef | RefObject<HTMLDivElement | null> | Ref para el contenedor exterior (usado para la detección de clic fuera). |
popupRef | RefObject<HTMLDivElement | null> | Ref para el elemento del popup (usado para la detección de clic fuera). |
handleKeyDown | (e: KeyboardEvent) => void | Manejador de teclado (Escape para cancelar). |
Comportamientos Clave
Abrir/Cerrar
El popup puede ser controlado o no controlado. Cuando se proporciona open, el hook lo usa como la fuente de verdad. De lo contrario, se utiliza el estado interno con initialOpen como valor inicial.
Clic Afuera
Hacer clic fuera de containerRef y popupRef activa handleCancel, revirtiendo al valor original y cerrando el popup.
Teclado
Presionar Escape mientras el popup está abierto activa handleCancel.
Modo en Línea
Cuando inline es true, el panel siempre está visible y los cambios se aplican inmediatamente (sincronización automática). La lógica de abrir/cerrar se omite.
Patrón de Estado Temporal
Este hook mantiene un estado temporal que solo se confirma cuando se llama a handleConfirm:
handleConfirm— escribe el estado temporal enonChangey cierra el popuphandleCancel— revierte el estado temporal alvalueactual y cierrahandleClear— llama aonChange(null)y cierra
Valores de Visualización
displayValue— cadena formateada delvalueconfirmado (para el disparador)timeDisplayValue— cadena formateada de los valores temporales (para el panel)