Mini Widgets
Select (Dropdown)
Select en React
Elige una opción de una lista. El valor, la etiqueta visible y las entradas activas se derivan del estado de React.
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 { ArcWidgetSelect } from '@arcrider/arcwidgets-react';
const items = [ { title: 'Open', value: 'open' }, { title: 'In progress', value: 'work' }, { title: 'Done', value: 'done' }, ];
export default function Example() { const [value, setValue] = useState<string | number | null>(null); return ( <ArcWidgetSelect data={{ placeholder: 'Choose status', width: '240px', items: items.map((item) => ({ ...item, active: item.value === value })), }} onChange={setValue} /> ); }</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 ArcWidgetSelectData. 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 al hacer clic en una opción, con su value, o con reset.value (o null) para la entrada de restablecimiento.
onChange?: (value: string | number | null) => 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.
items
Opciones de la lista (title, icon, value, active); ver el tipo de dato correspondiente.
Tipo: ArcWidgetSelectItem[].
currentValue
Contenido que se muestra en el campo cerrado: texto, string HTML o descriptor de widget.
Tipo: string | number | ArcNestedWidgetDescriptor.
placeholder
Texto que se muestra cuando currentValue está vacío y en el campo de filtro.
Tipo: string.
multiselect
Mantiene la lista abierta tras un clic para poder elegir varias opciones; el callback devuelve un único valor por clic. Valor por defecto: false.
Tipo: boolean.
disabled
Impide abrir la lista. Valor por defecto: false.
Tipo: boolean.
clickPosition
'icon' abre la lista solo desde el icono; por defecto la abre todo el campo.
Tipo: 'icon'.
icon
Icono al final del campo como string SVG o HTML, o como descriptor de widget. Valor por defecto: un chevron.
Tipo: string | ArcNestedWidgetDescriptor.
width
Ancho del campo. Valor por defecto: 100%.
Tipo: string.
flex
flex de CSS del widget, p. ej. '1' para ocupar el espacio restante de una fila.
Tipo: string.
height
Alto del campo. Valor por defecto: 36px.
Tipo: string.
alignX
Alineación horizontal de currentValue en el campo. Valor por defecto: left.
Tipo: 'left' | 'center' | 'right'.
fontColor
Color del texto y del icono del campo. Valor por defecto: inherit.
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.
borderColor
Color del borde. Valor por defecto: #00000015.
Tipo: string.
borderWidth
Grosor del borde. Valor por defecto: 1px.
Tipo: string.
borderRadius
Redondeo de las esquinas. Valor por defecto: 8px.
Tipo: string.
labelSettings
Etiqueta encima del campo (title) con alineación, altura, tamaño de fuente, color y separación.
Tipo: ArcWidgetSelectLabelSettings.
itemsSettings
Aspecto de la lista de opciones: width (por defecto: ancho del campo), height, radios, colores y el icono de marca de las opciones seleccionadas.
Tipo: ArcWidgetSelectItemsSettings.
reset
Entrada de restablecimiento al principio de la lista. title define su etiqueta, hide: true la elimina, value se pasa a onChange (los valores vacíos se convierten en null).
Tipo: ArcWidgetSelectReset.
focusAction
Comportamiento al abrir la lista: autoFocus enfoca el campo de filtro (por defecto true), showCurrentValue mantiene currentValue visible junto a él.
Tipo: ArcWidgetSelectFocusAction.
Comportamiento y límites
items[].value es el valor del callback. currentValue es la etiqueta visible; items[].active marca la selección. Mantén los tres actualizados desde el mismo estado.
multiselect: true mantiene la lista abierta. El callback sigue entregando el valor individual pulsado; añadir o quitar de un conjunto de selección lo implementas tú mismo.
- El reset entrega
null, salvo que reset.value esté establecido. Gestiona este caso de forma explícita.
- La entrada de restablecimiento se muestra por defecto con la etiqueta
(leer). Establece reset.title o reset.hide: true.
Usa texto para las etiquetas de las opciones. Los elementos JSX y los descriptores de widget no se admiten en el dropdown. El ejemplo en vivo muestra un badge separado a partir del mismo estado de selección. 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 ArcWidgetSelectItem {
title?: string | number;
icon?: string;
active?: boolean;
value?: string | number;
}
export interface ArcWidgetSelectReset { hide?: boolean; title?: string; icon?: string; value?: string | number; }
export interface ArcWidgetSelectItemsSettings { width?: string; height?: string; borderRadius?: string; itemBorderRadius?: string; backgroundColor?: string; borderColor?: string; fontColor?: string; hoverBackgroundColor?: string; activeBackgroundColor?: string; iconColor?: string; selectedIconColor?: string; showSelectedIcon?: boolean; selectedIcon?: string | false; }
export interface ArcWidgetSelectLabelSettings { title?: string | number | ArcNestedWidgetDescriptor; alignX?: 'left' | 'center' | 'right'; height?: string; fontSize?: string; fontColor?: string; gap?: string; }
export interface ArcWidgetSelectFocusAction { autoFocus?: boolean; showCurrentValue?: boolean; }
export interface ArcWidgetSelectData { items?: ArcWidgetSelectItem[]; currentValue?: string | number | ArcNestedWidgetDescriptor; placeholder?: string; multiselect?: boolean; disabled?: boolean; clickPosition?: 'icon'; icon?: string | ArcNestedWidgetDescriptor; width?: string; flex?: string; height?: string; alignX?: 'left' | 'center' | 'right'; fontColor?: string; fontSize?: string; fontWeight?: string | number; backgroundColor?: string; borderWidth?: string; borderColor?: string; borderRadius?: string; labelSettings?: ArcWidgetSelectLabelSettings; itemsSettings?: ArcWidgetSelectItemsSettings; reset?: ArcWidgetSelectReset; focusAction?: ArcWidgetSelectFocusAction; }
export interface ArcWidgetSelectProps extends ArcReactWidgetProps<ArcWidgetSelectData> { onChange?: (value: string | number | null) => void; }</code></pre>