Todos los componentes (244)

Importar datos

Gestión · DataImportWizard

Qué es y cuándo usarlo

Un asistente para importar datos de un fichero CSV o de Excel (.xlsx) en tres pasos: elegir el fichero, decir de qué columna sale cada campo y revisar las filas ya convertidas antes de guardarlas.

Cuándo usarlo

Cargar clientes, productos o movimientos desde una hoja de cálculo.
fields son los campos que espera la aplicación: cada uno con su tipo (text, number, date, boolean), si es obligatorio (required), si no puede repetirse (unique), otros nombres con los que puede venir la columna (aliases) y una regla propia (validate).
Lee el fichero en el navegador, sin subirlo a ninguna parte. Detecta el separador, la codificación (UTF-8 o la de Excel en castellano) y las fechas de Excel. El lector de Excel se carga solo al elegir un .xlsx.
Empareja solo las columnas por el nombre; el segundo paso deja cambiarlas. Los números y las fechas se leen según decimal y dateOrder, que el usuario puede cambiar en el primer paso.
onImport recibe las filas correctas, ya convertidas. Puede devolver cuántas entraron y cuáles rechazó el servidor. Las filas con errores se saltan, o impiden importar con allowPartial={false}.

Cuándo no

Ficheros enormes: maxRows (10.000 por defecto) y maxSizeMb (10) acotan lo que se lee en el navegador; para más, importa en el servidor.
Formatos antiguos (.xls) o con fórmulas que hay que recalcular: de una fórmula se toma el último valor que guardó Excel.
La validación de aquí es de formato. El servidor tiene que validar otra vez.

Teclado: son controles normales; el asistente anuncia el paso nuevo y le lleva el foco, y la vista previa es una región que se desplaza con las flechas.

Accesibilidad: cada campo de columna tiene su etiqueta, los errores se dicen con texto en la celda además del color y los recuentos se anuncian.

Aspecto fino: la vista previa resalta con el tono de error las celdas con problemas; los pasos son los de Wizard.

Cómo se ve

Fichero

Fichero que se importa

Arrastra el fichero aquí

CSV, TSV o Excel (.xlsx). Hasta 10 MB y 500 filas.

Sube un CSV o un .xlsx para probarlo.

<DataImportWizard
  label="Importar clientes"
  fields={campos}
  maxRows={500}
  allowPartial
  onImport={(registros) => guardarClientes(registros)}
/>

Props

Se importa con import { DataImportWizard } from '@amset/ui'. Las obligatorias van marcadas.

Prop	Tipo	Para qué sirve
`fields`obligatoria	`readonly ImportField[]`	Los campos que espera la aplicacion, con su tipo, si son obligatorios y sus reglas.
`label`obligatoria	`string`	Que se importa («Importar clientes»): nombra el asistente. Obligatorio.
`onImport`obligatoria	`(records: readonly ImportRecord[], context: ImportContext) => void \| ImportOutcome \| Promise<void \| ImportOutcome>`	Guardar las filas correctas. Sin `batchSize` se llama una sola vez, con todas; con el, una vez por tanda. Puede devolver cuantas entraron y cuales rechazo el servidor (`failed`), y se cuentan en el resultado. Si la primera tanda lanza o rechaza, el asistente lo dice y se queda donde estaba; si falla una posterior, se para y el resultado dice cuantas entraron y cuantas quedan. La biblioteca valida el formato; el servidor tiene que validar otra vez.
`allowPartial`	`boolean`	Importar las filas correctas aunque haya otras con errores. Con `false`, un solo error impide importar. Por defecto, si.
`batchSize`	`number`	Enviar las filas en tandas de este tamaño, una detras de otra, con una barra de avance y un boton para cancelar (la señal de `context` se dispara para cortar tambien la tanda que esta en marcha). Sin el, todas de una vez.
`className`	`string`	Se une a las clases de la biblioteca, no las sustituye.
`dateOrder`	`DateOrder`	En `03/04/2026`, si va primero el dia o el mes, al empezar. Por defecto, el dia.
`decimal`	`DecimalSeparator`	Como se escriben los decimales en el fichero al empezar. Por defecto, la coma.
`headingLevel`	`WizardHeadingLevel`	El nivel del titulo de cada paso. Por defecto, 3.
`maxRows`	`number`	Cuantas filas admite como mucho el fichero. Por defecto, 10.000.
`maxSizeMb`	`number`	El tamaño maximo del fichero, en megabytes. Por defecto, 10.
`onDone`	`(outcome: ImportOutcome) => void`	Se llama cuando termina la importacion, con lo que devolvio `onImport`.

Acepta además los atributos del elemento que pinta: className, style, data-*, aria-* y sus eventos.

En el banco de pruebas

Cada estado y cada variante, para tocarlos de uno en uno, en su ficha de ui.amset.tech: