Mini Widgets
Input
Input en React
Captura texto, números, fechas u horas. El valor vive en el estado de React; onChange notifica cada cambio confirmado.
Referencia para @arcrider/arcwidgets-react@0.1.0-alpha.5. <a href="/docs/react/intro/setup-react">Instalación</a> · <a href="/docs/react/intro/react-components">Todos los componentes</a>.
Ejemplo completo
import { useState } from 'react';
import { ArcWidgetInput } from '@arcrider/arcwidgets-react';
export default function Example() { const [value, setValue] = useState('25.11.1990'); return ( <ArcWidgetInput data={{ type: 'date', value, height: '40px', placeholderSettings: { value: 'Date', fontColor: '#000', backgroundColor: '#ccc', }, labelSettings: { title: 'Date' }, }} onChange={(next) => setValue(String(next ?? ''))} /> ); }</code></pre>
Props del componente
id
ID de DOM opcional. No es necesario en el uso normal; se genera automáticamente si se omite.
data
Configuración de tipo ArcWidgetInputData. Pasa los cambios como objetos nuevos; gestiona los datos de negocio y la selección en el estado de React.
onAction
Fallback opcional (type: string, ...args: unknown[]) => unknown. El callback concreto tiene prioridad. Detalles: <a href="/docs/react/patterns/react-state-events">Estado y eventos</a>.
onChange
Se dispara cuando cambia el valor confirmado (blur, Enter, confirmación en el selector o en el numpad, reset). Recibe texto para text y textarea, un número para number, milisegundos epoch para date, 'HH:MM' para time, null para un campo vacío o reset.value tras un restablecimiento.
onChange?: (value: string | number | null) => void | Promise<void>;
onActions
Se dispara cuando el usuario confirma (Enter, confirmación en el selector o en el numpad) o vacía el campo con el botón de restablecer. El valor es el valor confirmado como texto; source distingue ambos eventos.
onActions?: (value: string, source: 'submit' | 'reset') => void;
Configuración
Los siguientes campos pertenecen a data. Los tamaños se indican como strings, los números y valores de tiempo según su tipo respectivo.
type
Tipo de entrada; textarea permite varias líneas. Valor por defecto: text.
Tipo: 'text' | 'number' | 'date' | 'time' | 'textarea'.
value
Valor actual: texto; para number, un número o un string numérico con el formato regional; para date, 'DD.MM.YYYY' o milisegundos epoch; para time, 'HH:MM'.
Tipo: string | number | null.
disabled
Desactiva la edición, los selectores y el botón de borrar. Valor por defecto: false.
Tipo: boolean.
tempStorage
Mantiene en local lo que se escribe: onChange se omite al escribir y al restablecer, onActions se sigue disparando. Las selecciones en el selector y el numpad siguen llamando a onChange. Valor por defecto: false.
Tipo: boolean.
width
Ancho del campo. Valor por defecto: 100%.
Tipo: string.
height
Alto del campo. Valor por defecto: 36px.
Tipo: string.
minHeight
Altura mínima del campo, p. ej. para un textarea que crece.
Tipo: string.
maxHeight
Altura máxima del campo; el contenido más alto se desplaza.
Tipo: string.
alignX
Alineación horizontal del texto dentro del campo. Valor por defecto: left.
Tipo: 'left' | 'center' | 'right'.
paddingX
Espaciado interno a izquierda y derecha. Valor por defecto: 8px.
Tipo: string.
paddingY
Espaciado interno arriba y abajo. Valor por defecto: 2px.
Tipo: string.
fontColor
Color del texto.
Tipo: string.
fontSize
Tamaño de fuente como valor CSS. Valor por defecto: 13px.
Tipo: string.
fontWeight
Grosor de la fuente. Valor por defecto: 400.
Tipo: string | number.
backgroundColor
Color de fondo. Valor por defecto: #fafafa.
Tipo: string.
borderWidth
Grosor del borde; solo se aplica junto con borderColor. Valor por defecto: 1px.
Tipo: string.
borderColor
Color del borde. Valor por defecto: #00000015.
Tipo: string.
borderRadius
Redondeo de las esquinas; también da forma a los botones del selector, del numpad y de borrar dentro del campo. Valor por defecto: 8px.
Tipo: string.
autocomplete
false permite el autocompletado del navegador. Valor por defecto: true (autocompletado desactivado).
Tipo: boolean.
selection
Resaltado del segmento activo de fecha u hora durante la edición (backgroundColor, borderRadius, color).
Tipo: ArcWidgetInputSelection.
focusAction
Ancho y contorno del campo mientras tiene el foco (width, showFocusOutline, outlineWidth, outlineColor), y a dónde pasa el foco tras un cambio confirmado (nextField con loop: 'infinite').
Tipo: ArcWidgetInputFocusAction.
placeholderSettings
Texto del placeholder (value), su color y el fondo del campo vacío.
Tipo: ArcWidgetInputPlaceholderSettings.
labelSettings
Etiqueta encima del campo (title) con tamaño de fuente, color, alineación y separación.
Tipo: ArcWidgetInputLabelSettings.
numberFormat
Decimales y separadores para number. Valores por defecto: digits: 2, decimal ",", miles ".".
Tipo: ArcWidgetInputNumberFormat.
numpad
Teclado en pantalla para number, activado por defecto. suffix define la unidad que se muestra en el campo y en el numpad; enabled: false cambia a la entrada normal por teclado.
Tipo: ArcWidgetInputNumpad.
reset
Botón de borrar (X) dentro del campo, visible con visible: true mientras el campo tiene un valor. value es el valor que recibe el campo al restablecer (por defecto null).
Tipo: ArcWidgetInputReset.
timeSettings
Selector de hora para time: format ('24h' o '12h'), minuteStep (por defecto 5), showNow, ajustes para hours y minutes por separado, y labels de las secciones.
Tipo: ArcWidgetInputTimeSettings.
liveUpdate
Confirma el texto mientras se escribe, opcionalmente con retraso (debounce, por defecto 300 ms), una longitud mínima (minLength) y sin onActions (actions: false).
Tipo: boolean | ArcWidgetInputLiveUpdate.
Comportamiento y límites
onChange entrega el nuevo valor; onActions(value, source) notifica confirmación o reset con source: "submit" | "reset".
- Para búsquedas es adecuado
liveUpdate: { debounce: 200, minLength: 0 }. Sin live-update, el valor se adopta al confirmar o al salir del campo.
- Con
tempStorage: true, los valores escritos permanecen locales en el widget y onChange no se llama para ellos; usa esto solo de forma deliberada.
- El numpad numérico confirma mediante Listo, blur o Enter.
liveUpdate no actúa ahí como en texto. reset.visible debe establecerse para un reset visible.
labelSettings.title y reset.icon admiten texto, strings HTML o descriptores de widget; pasa ahí texto plano en lugar de un elemento JSX. Los strings HTML se interpretan como HTML. <a href="/docs/react/patterns/nested-widget-descriptors">Combinar contenidos</a>.
Tipos de datos
Estos tipos relacionados con el widget se exportan desde el paquete. También están disponibles tipos comunes como ArcWidgetSlot, ArcWidgetStyles y ArcReactWidgetProps. Los objetos de configuración son cerrados, por lo que una clave mal escrita o no admitida se notifica como error de tipo.
export interface ArcWidgetInputReset {
visible?: boolean;
value?: string | number | null;
icon?: string | ArcNestedWidgetDescriptor;
color?: string;
backgroundColor?: string;
borderRadius?: string;
}
export interface ArcWidgetInputNumberFormat { digits?: number | null; decimalSeparator?: string; thousandSeparator?: string; }
export interface ArcWidgetInputNumpad { enabled?: boolean; size?: 'default' | 'mini'; openOnFocus?: boolean; allowNegative?: boolean; maxDecimals?: number; suffix?: string; clearOnFirstInput?: boolean; }
export interface ArcWidgetInputPlaceholderSettings { value?: string; fontColor?: string; backgroundColor?: string; }
export interface ArcWidgetInputLabelSettings { title?: string | number | ArcNestedWidgetDescriptor; fontSize?: string; fontColor?: string; alignX?: 'left' | 'center' | 'right'; gap?: string; }
export interface ArcWidgetInputFocusAction { width?: string; showFocusOutline?: boolean; outlineWidth?: string; outlineColor?: string; nextField?: 'this' | (string & {}); loop?: 'infinite'; }
export interface ArcWidgetInputSelection { backgroundColor?: string; borderRadius?: string; color?: string; }
export interface ArcWidgetInputTimeOption { value: number; label?: string | number; backgroundColor?: string; fontColor?: string; }
export interface ArcWidgetInputTimeLabels { hours?: string; minutes?: string; }
export interface ArcWidgetInputTimeSettings { format?: '24h' | '12h'; minuteStep?: number; showNow?: boolean; hours?: ArcWidgetInputTimeOption[]; minutes?: ArcWidgetInputTimeOption[]; labels?: ArcWidgetInputTimeLabels; }
export interface ArcWidgetInputLiveUpdate { debounce?: number; minLength?: number; actions?: boolean; }
export interface ArcWidgetInputData { type?: 'text' | 'number' | 'date' | 'time' | 'textarea'; value?: string | number | null; disabled?: boolean; tempStorage?: boolean; width?: string; height?: string; minHeight?: string; maxHeight?: string; alignX?: 'left' | 'center' | 'right'; paddingX?: string; paddingY?: string; fontColor?: string; fontSize?: string; fontWeight?: string | number; backgroundColor?: string; borderWidth?: string; borderColor?: string; borderRadius?: string; autocomplete?: boolean; selection?: ArcWidgetInputSelection; focusAction?: ArcWidgetInputFocusAction; placeholderSettings?: ArcWidgetInputPlaceholderSettings; labelSettings?: ArcWidgetInputLabelSettings; numberFormat?: ArcWidgetInputNumberFormat; numpad?: ArcWidgetInputNumpad; reset?: ArcWidgetInputReset; timeSettings?: ArcWidgetInputTimeSettings; liveUpdate?: boolean | ArcWidgetInputLiveUpdate; }
export interface ArcWidgetInputProps extends ArcReactWidgetProps<ArcWidgetInputData> { onChange?: (value: string | number | null) => void | Promise<void>; onActions?: (value: string, source: 'submit' | 'reset') => void; }</code></pre>