Uploader

Selecciona y valida archivos locales con vistas previas y estado de subida gestionado por la aplicación.

Categoría: Formularios y selección
Import: @neural-ui/core/uploader
Selector: neu-uploader

import { NeuUploaderComponent } from '@neural-ui/core/uploader';

Uso

value contiene objetos File; seleccionar o arrastrar no los sube. accept, maxFiles y maxFileSize validan la selección. Procesa filesRejected para explicar errores. La aplicación realiza la petición HTTP y aporta progress o fileStates; fileRetry solicita reintentar, no ejecuta la red. previewTemplate recibe NeuUploaderFileItem con file, status y progress. El archivo de ejemplo se genera tras una acción, no durante SSR.

Ejemplos

Prueba esta interacción gestionada por la aplicación. Código incluye los eventos y los datos iniciales.

Adjuntos

Elegir archivos

Arrastra archivos aquí o elígelos · Tipos permitidos: .txt,.pdf · Tamaño máximo: 1.0 MB

0 archivos seleccionados

Eventos: 0

Prueba y configura

Cambia las opciones públicas, prueba el resultado y consulta el template actualizado. Código contiene la implementación ejecutable completa.

Adjuntos

Elegir archivos

Arrastra archivos aquí o elígelos · Tipos permitidos: .txt,.pdf · Tamaño máximo: 1.0 MB

Usa Fallar junto al archivo para simular un fallo y después Reintentar. No se sube ningún archivo.

0 archivos seleccionados

Eventos: 0

disabled

readonly

invalid

multiple

dropzone

showProgress

maxFiles

maxFileSize

Opciones avanzadas · 30

Comportamiento y contenido

errorMessage

hint

pickerDescription

required

showPickerText

acceptedTypesLabel

chooseLabel

clearLabel

dropzoneLabel

duplicateFileMessage

emptySelectionMessage

fileCountPluralLabel

fileCountSingularLabel

invalidTypeMessage

label

listAriaLabel

maxFileSizeMessage

maxFileSizeTextLabel

maxFilesMessage

placeholder

progress

progressLabel

removeAriaLabel

retryAriaLabel

retryLabel

Estado del formulario

dirty

hidden

pending

touched

Accesibilidad

inputId

Los datos estructurados, callbacks y templates se muestran en los ejemplos y en la API.

El código añade las opciones avanzadas cuando difieren del valor predeterminado. Los datos y valores de esta configuración aparecen en el estado del template.

<neu-uploader
  [value]="value()"
  (valueChange)="onValueChange($event)"
  [disabled]="false"
  [readonly]="false"
  [invalid]="false"
  [multiple]="true"
  [dropzone]="true"
  [showProgress]="true"
  [size]="'md'"
  [maxFiles]="3"
  [maxFileSize]="1048576"
  [accept]="'.txt,.pdf'"
  [progress]="progress()"
  [fileStates]="fileStates()"
  [previewTemplate]="failurePreview"
  (filesRejected)="record('filesRejected', $event)"
  (filesSelected)="record('filesSelected', $event.map(fileName))"
  (fileRetry)="retry($event)"
  [acceptedTypesLabel]="'Tipos permitidos'"
  [chooseLabel]="'Elegir archivos'"
  [clearLabel]="'Limpiar'"
  [dropzoneLabel]="'Arrastra archivos para añadirlos'"
  [duplicateFileMessage]="'Archivo ya seleccionado.'"
  [emptySelectionMessage]="'Ningún archivo seleccionado.'"
  [fileCountPluralLabel]="'archivos'"
  [fileCountSingularLabel]="'archivo'"
  [invalidTypeMessage]="'El tipo de archivo no está permitido.'"
  [label]="'Adjuntos'"
  [listAriaLabel]="'Archivos seleccionados'"
  [maxFileSizeMessage]="'El archivo supera el tamaño máximo.'"
  [maxFileSizeTextLabel]="'Tamaño máximo'"
  [maxFilesMessage]="'Demasiados archivos seleccionados.'"
  [placeholder]="'Arrastra archivos aquí o elígelos'"
  [progressLabel]="'Progreso de subida'"
  [removeAriaLabel]="'Eliminar archivo'"
  [retryAriaLabel]="'Reintentar subida de'"
  [retryLabel]="'Reintentar'"
/>
<div class="remaining-actions">
  <button
    neu-button
    variant="outline"
    [disabled]="disabled() || readonly()"
    (neuClick)="sample()"
  >
    {{ t("Add sample file", "Añadir archivo de ejemplo") }}</button
  ><button neu-button variant="ghost" [disabled]="disabled() || readonly() || !value().length" (neuClick)="simulate()">
    {{ t("Toggle sample progress", "Alternar progreso de ejemplo") }}
  </button>
</div>
<ng-template #failurePreview let-item>
  <button neu-button variant="outline" tone="danger" size="sm"
    [ariaLabel]="t('Simulate upload failure for', 'Simular fallo de subida de') + ' ' + item.name"
    [disabled]="disabled() || readonly() || item.status === 'error'"
    (neuClick)="simulateFailure(item)"
  >{{ t('Fail', 'Fallar') }}</button>
</ng-template>

Estado y datos de esta configuración

Estos valores corresponden a la vista previa actual. Los handlers, imports de Core y templates completos están en Código.

import { signal } from '@angular/core';

export const value = signal([]);

export const progress = signal(null);

export const fileStates = signal({});

export const failurePreview = undefined /* Runtime e instance; use the provider or reference in Source. */;

Inputs de datos, callbacks y configuración estructurada

Estos inputs requieren un modelo o función, no un checkbox. Modifica el campo del mismo nombre en el componente de Código y enlázalo al template; los datos que ya usa esta vista previa se muestran en el estado anterior.

errors · readonly ValidationError.WithOptionalFieldTree[]

En Código: define errors con este tipo y utiliza [errors]="errors" (o errors() si es una signal).

fileStates ·

Record<string, {
    status?: NeuUploaderFileStatus;
    progress?: number | null;
    error?: string;
}>

En Código: define fileStates con este tipo y utiliza [fileStates]="fileStates" (o fileStates() si es una signal).

previewTemplate ·

TemplateRef<{
    $implicit: NeuUploaderFileItem;
    item: NeuUploaderFileItem;
}> | null

En Código: define previewTemplate con este tipo y utiliza [previewTemplate]="previewTemplate" (o previewTemplate() si es una signal).

value · readonly File[]

En Código: define value con este tipo y utiliza [value]="value" (o value() si es una signal).

Estado y eventos

Accesibilidad y teclado

Tab alcanza el selector y los controles de eliminar o reintentar. Intro abre el selector nativo; no hace falta arrastrar para añadir archivos.

Tecla	Acción
`Tab`	Recorre el selector de archivos y los botones disponibles de eliminar o reintentar.
`Enter`	En el selector, abre el diálogo nativo de archivos; en una acción, elimina o reintenta el archivo.
`Space`	En el selector, abre el diálogo nativo de archivos; en una acción, elimina o reintenta el archivo.

API

Inputs, modelos y Outputs se extraen del paquete Core instalado. Los tipos públicos enlazan a sus definiciones. Los Templates incluyen ejemplos ejecutables.

Inputs

Configura el componente con [propiedad]="valor". Tu aplicación proporciona estos valores; el componente no debe reemplazar el estado que le pasas.

Nombre	Tipo	Por defecto	Uso en el template	Descripción
`accept`	`string`	`''`	`[accept]`	Tipos MIME o extensiones permitidos, con la sintaxis del selector nativo de archivos.
`acceptedTypesLabel`	`string`	`'Allowed types'`	`[acceptedTypesLabel]`	Título visible de la indicación de tipos de archivo permitidos.
`chooseLabel`	`string`	`'Choose files'`	`[chooseLabel]`	Etiqueta visible del activador del selector nativo.
`clearLabel`	`string`	`'Clear'`	`[clearLabel]`	Etiqueta de la acción que limpia la selección.
`dirty`	`boolean`	`false`	`[dirty]`	Estado del formulario que indica que el usuario ha cambiado el valor.
`disabled`	`boolean`	`false`	`[disabled]`	Impide interactuar con este control.
`dropzone`	`boolean`	`true`	`[dropzone]`	Habilita la zona de arrastre. La selección nativa sigue disponible.
`dropzoneLabel`	`string`	`'Drop files here to add them'`	`[dropzoneLabel]`	Nombre accesible de la región de arrastre de archivos.
`duplicateFileMessage`	`string`	`'File {{fileName}} has already been selected.'`	`[duplicateFileMessage]`	Mensaje localizado de rechazo; puede conservar los marcadores documentados {{fileName}} / {{maxFiles}}.
`emptySelectionMessage`	`string`	`'No file was selected.'`	`[emptySelectionMessage]`	Mensaje para una selección vacía de archivos.
`errorMessage`	`string`	`''`	`[errorMessage]`	Mensaje de error visible asociado al campo.
`errors`	`readonly ValidationError.WithOptionalFieldTree[]`	`[]`	`[errors]`	Errores de validación proporcionados por el formulario o la aplicación.
`fileCountPluralLabel`	`string`	`'files'`	`[fileCountPluralLabel]`	Palabra localizada en singular o plural para el contador de archivos.
`fileCountSingularLabel`	`string`	`'file'`	`[fileCountSingularLabel]`	Palabra localizada en singular o plural para el contador de archivos.
`fileStates`	`Record<string, { status?: NeuUploaderFileStatus; progress?: number \| null; error?: string; }>`	`{}`	`[fileStates]`	Estado/progreso/error por archivo aportado por la aplicación mediante los ids del uploader.
`hidden`	`boolean`	`false`	`[hidden]`	Oculta el control según el estado del formulario.
`hint`	`string`	`''`	`[hint]`	Texto de ayuda aportado por la aplicación.
`inputId`	`string`	`inject(NeuIdGenerator).getId('neu-uploader-')`Valor derivado	`[inputId]`	Id estable del control, generado si se omite; permite asociar etiquetas o descripciones.
`invalid`	`boolean`	`false`	`[invalid]`	Muestra el estado inválido; no añade una regla de validación.
`invalidTypeMessage`	`string`	`'File {{fileName}} does not match the allowed file types.'`	`[invalidTypeMessage]`	Mensaje localizado de rechazo; puede conservar los marcadores documentados {{fileName}} / {{maxFiles}}.
`label`	`string`	`''`	`[label]`	Etiqueta visible que identifica el campo o la acción.
`listAriaLabel`	`string`	`'Selected files'`	`[listAriaLabel]`	Nombre accesible de la lista de archivos seleccionados.
`maxFiles`	`number \| null`	`null`	`[maxFiles]`	Número máximo de archivos aceptados; null elimina el límite.
`maxFileSize`	`number \| null`	`null`	`[maxFileSize]`	Tamaño máximo aceptado en bytes por archivo; null elimina el límite.
`maxFileSizeMessage`	`string`	`'File {{fileName}} exceeds the allowed maximum size.'`	`[maxFileSizeMessage]`	Mensaje localizado de rechazo; puede conservar los marcadores documentados {{fileName}} / {{maxFiles}}.
`maxFileSizeTextLabel`	`string`	`'Max size'`	`[maxFileSizeTextLabel]`	Título visible de la indicación de tamaño máximo.
`maxFilesMessage`	`string`	`'You can only select up to {{maxFiles}} files.'`	`[maxFilesMessage]`	Mensaje localizado de rechazo; puede conservar los marcadores documentados {{fileName}} / {{maxFiles}}.
`multiple`	`boolean`	`true`	`[multiple]`	Permite seleccionar más de un archivo.
`pending`	`boolean`	`false`	`[pending]`	Estado del formulario que indica que hay una validación asíncrona pendiente.
`pickerDescription`	`string`	`'Use the button below to choose files from your device.'`	`[pickerDescription]`	Texto complementario que explica la selección nativa.
`placeholder`	`string`	`'Drag files here or select them from your device.'`	`[placeholder]`	Texto que se muestra cuando el campo no tiene un valor seleccionado.
`previewTemplate`	`TemplateRef<{ $implicit: NeuUploaderFileItem; item: NeuUploaderFileItem; }> \| null`	`null`	`[previewTemplate]`	TemplateRef que recibe $implicit/item: NeuUploaderFileItem para la vista de cada archivo.
`progress`	`number \| null`	`null`	`[progress]`	Porcentaje global de subida aportado por la aplicación; null indica ausencia de progreso aplicado.
`progressLabel`	`string`	`'Upload in progress'`	`[progressLabel]`	Etiqueta accesible del progreso de subida.
`readonly`	`boolean`	`false`	`[readonly]`	Mantiene visible el valor aplicado, pero impide editarlo.
`removeAriaLabel`	`string`	`'Remove file'`	`[removeAriaLabel]`	Nombre accesible del botón para eliminar.
`required`	`boolean`	`false`	`[required]`	Marca el campo como obligatorio; utiliza un validador del formulario para exigirlo.
`retryAriaLabel`	`string`	`'Retry upload for'`	`[retryAriaLabel]`	Etiqueta visible o accesible para reintentar una carga o subida fallida.
`retryLabel`	`string`	`'Retry'`	`[retryLabel]`	Etiqueta visible o accesible para reintentar una carga o subida fallida.
`showPickerText`	`boolean`	`false`	`[showPickerText]`	Muestra la explicación complementaria del selector nativo.
`showProgress`	`boolean`	`true`	`[showProgress]`	Muestra el progreso aportado por la aplicación. No inicia una petición de red.
`size`	`NeuUploaderSize`	`'md'`	`[size]`	Tamaño del control. El tipo indica la escala o unidad numérica admitida.
`touched`	`boolean`	`false`	`[touched]`	Estado del formulario que indica que el control ha sido visitado.

Models

Un modelo admite [(propiedad)]="signal" o la pareja [propiedad] y (propiedadChange). Elige una de las dos formas, no ambas.

Nombre	Tipo	Por defecto	Uso en el template	Descripción
`value`	`readonly File[]`	`[]`	`[(value)]`	Objetos File locales aceptados; seleccionarlos no los sube.

Outputs

Escucha un evento con (evento)="handler($event)". La tabla indica qué datos recibe tu función y cómo utilizarlos.

Nombre	Valor emitido	Uso en el template	Descripción
`cleared`	`void`	`(cleared)="onCleared($event)"`	Se emite con la acción explícita de limpiar; valueChange comunica el valor resultante.
`fileRemoved`	`File`	`(fileRemoved)="onFileRemoved($event)"`	Informa del File eliminado de la selección.
`fileRetry`	`NeuUploaderFileItem`	`(fileRetry)="onFileRetry($event)"`	Solicita reintentar un archivo. La aplicación realiza la operación de subida.
`filesRejected`	`NeuUploaderError[]`	`(filesRejected)="onFilesRejected($event)"`	Informa de códigos de rechazo, mensajes y archivos asociados cuando existen.
`filesSelected`	`readonly File[]`	`(filesSelected)="onFilesSelected($event)"`	Informa de los objetos File aceptados en la última selección.
`touch`	`void`	`(touch)="onTouch($event)"`	Notifica al formulario que el control ha sido visitado; no es un cambio de valor.

Templates

ng-content proyecta contenido dentro del componente. Los inputs TemplateRef reciben un template; las directivas ng-template identifican templates con un contexto tipado. Una directiva compartida en el entrypoint no es necesariamente un slot de este componente.

Nombre	Mecanismo	Contrato
`previewTemplate`Ver ejemplo	Input de tipo TemplateRef	`TemplateRef<{ $implicit: NeuUploaderFileItem; item: NeuUploaderFileItem; }> \| null`

Cada ejemplo muestra un template diferente. Alterna entre Demo y Código para consultar su implementación, imports y estado.

previewTemplate

previewTemplate

Adjuntos

Elegir archivos

Arrastra archivos aquí o elígelos · Tipos permitidos: .txt,.pdf · Tamaño máximo: 1.0 MB

0 archivos seleccionados

Eventos: 0

Public Types

Abre un tipo para consultar su definición y los campos de sus interfaces.

NeuUploaderErrorTypeScript

import type { NeuUploaderErrorCode } from '@neural-ui/core/uploader';

import type { NeuUploaderError } from '@neural-ui/core/uploader';

// Declaración pública (solo referencia)
export interface NeuUploaderError {
  code: NeuUploaderErrorCode;
  file?: File;
  message: string;
}

NeuUploaderErrorCodeTypeScript

import type { NeuUploaderErrorCode } from '@neural-ui/core/uploader';

// Declaración pública (solo referencia)
export type NeuUploaderErrorCode = 'accept' | 'max-file-size' | 'max-files' | 'duplicate' | 'empty-selection';

NeuUploaderFileItemTypeScript

import type { NeuUploaderFileStatus } from '@neural-ui/core/uploader';

import type { NeuUploaderFileItem } from '@neural-ui/core/uploader';

// Declaración pública (solo referencia)
export interface NeuUploaderFileItem {
  error?: string;
  file: File;
  id: string;
  name: string;
  progress: number | null;
  size: number;
  status: NeuUploaderFileStatus;
  type: string;
}

NeuUploaderFileStatusTypeScript

import type { NeuUploaderFileStatus } from '@neural-ui/core/uploader';

// Declaración pública (solo referencia)
export type NeuUploaderFileStatus = 'idle' | 'uploading' | 'success' | 'error';

NeuUploaderSizeTypeScript

Estilos y tokens

Usa los tokens públicos de la referencia. El diseño del contenedor pertenece a tu aplicación; comprueba el resultado en modo claro y oscuro y en espacios estrechos.

Tokens específicos

Este componente utiliza tokens compartidos del tema en lugar de tokens específicos.

Tokens compartidos utilizados

Sobrescríbelos en un contenedor local para afectar a este ejemplo. Una modificación en :root afecta a los demás componentes que utilizan el mismo token.

Token	Efecto aquí	Otros efectos	Valor / alternativa
`--neu-border`	Bordes normales de controles y celdas	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`rgba(15, 23, 42, 0.08)`
`--neu-border-hover`	Bordes de controles al pasar el puntero	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`rgba(15, 23, 42, 0.16)`
`--neu-error`	Color del campo no válido o de la acción de peligro	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#dc2626`
`--neu-error-bg`	Fondo de estados de error o peligro	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#fee2e2`
`--neu-error-text`	Texto de error y de Button danger outline/ghost en ambos temas	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#991b1b`
`--neu-focus-ring`	Anillo normal del foco de teclado	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`0 0 0 var(--neu-focus-ring-width) rgba(0, 122, 255, 0.15)`
`--neu-focus-ring-strong`	Tratamiento de foco destacado	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`0 0 0 var(--neu-focus-ring-width) rgba(0, 122, 255, 0.35)`
`--neu-primary`	Color de marca en controles activos y énfasis	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#007aff`