Arc Rider Docs · Markdown

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 ( &lt;ArcWidgetInput data={{ type: 'date', value, height: '40px', placeholderSettings: { value: 'Date', fontColor: '#000', backgroundColor: '#ccc', }, labelSettings: { title: 'Date' }, }} onChange={(next) =&gt; setValue(String(next ?? ''))} /&gt; ); }</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 &amp; {}); 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&lt;ArcWidgetInputData&gt; { onChange?: (value: string | number | null) =&gt; void | Promise&lt;void&gt;; onActions?: (value: string, source: 'submit' | 'reset') =&gt; void; }</code></pre>