Referencia de valores de retorno

Todo lo que devuelve el hook useDropup.

Resumen

const {
  files,          // Array de objetos de archivo
  state,          // Estado actual
  actions,        // Acciones disponibles
  getDropProps,   // Props para zona de soltar
  getInputProps,  // Props para elemento input
  openFileDialog, // Abrir selector de archivos
} = useDropup();

files

Array de objetos DropupFile que representan todos los archivos agregados.

const { files } = useDropup();

files.forEach(file => {
  console.log(file.id);          // "abc123"
  console.log(file.name);        // "photo.jpg"
  console.log(file.size);        // 1234567
  console.log(file.type);        // "image/jpeg"
  console.log(file.status);      // "idle" | "uploading" | "complete" | "error"
  console.log(file.progress);    // 0-100
  console.log(file.preview);     // "blob:http://..." (solo imágenes)
  console.log(file.uploadedUrl); // "https://..." (después de carga)
  console.log(file.error);       // DropupError (si falló)
});

Propiedades de DropupFile

Propiedad	Tipo	Descripción
id	string	Identificador único
file	File	Objeto File original del navegador
name	string	Nombre del archivo
size	number	Tamaño en bytes
type	string	Tipo MIME
status	FileStatus	Estado actual
progress	number	Progreso de carga (0-100)
preview	string | undefined	URL de vista previa para imágenes
uploadedUrl	string | undefined	URL después de carga exitosa
response	unknown	Datos de respuesta del servidor
error	DropupError | undefined	Error si la carga falló
meta	Record<string, unknown>	Metadatos personalizados

Valores de FileStatus

Estado	Descripción
'idle'	Archivo agregado, no cargando
'uploading'	Carga en progreso
'complete'	Carga exitosa
'error'	Carga falló
'paused'	Carga pausada (cargas reanudables)

state

Estado actual de la zona de soltar.

const { state } = useDropup();

console.log(state.isDragging);   // true cuando se arrastra encima
console.log(state.isDragAccept); // true cuando archivos arrastrados son válidos
console.log(state.isDragReject); // true cuando archivos arrastrados son inválidos
console.log(state.isUploading);  // true cuando algún archivo está cargando
console.log(state.progress);     // progreso general 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

Propiedades de State

Propiedad	Tipo	Descripción
isDragging	boolean	Archivos siendo arrastrados sobre la zona
isDragAccept	boolean	Archivos arrastrados pasan validación
isDragReject	boolean	Archivos arrastrados fallan validación
isUploading	boolean	Algún archivo actualmente cargando
progress	number	Progreso promedio de todos los archivos (0-100)
status	DropupStatus	Estado general de carga

Valores de DropupStatus

Estado	Descripción
'idle'	Sin cargas en progreso
'uploading'	Uno o más archivos cargando
'complete'	Todas las cargas terminadas exitosamente
'error'	Una o más cargas fallaron

actions

Objeto conteniendo todas las acciones disponibles.

const { actions } = useDropup();

// Iniciar cargas
actions.upload();              // Cargar todos los archivos idle
actions.upload(['id1', 'id2']); // Cargar archivos específicos

// Cancelar cargas
actions.cancel();              // Cancelar todas las cargas
actions.cancel('file-id');     // Cancelar archivo específico

// Eliminar archivos
actions.remove('file-id');     // Eliminar archivo específico
actions.reset();               // Eliminar todos los archivos

// Reintentar cargas fallidas
actions.retry();               // Reintentar todos los fallidos
actions.retry(['id1']);        // Reintentar archivos específicos

// Agregar archivos programáticamente
actions.addFiles(fileList);    // Agregar File[] o FileList

// Actualizar metadatos de archivo
actions.updateFileMeta('file-id', { tag: 'important' });

Métodos de acción

upload(fileIds?)

Iniciar carga de archivos.

// Cargar todos los archivos idle
actions.upload();

// Cargar archivos específicos
actions.upload(['file-id-1', 'file-id-2']);

Parámetro	Tipo	Descripción
fileIds	string[] (opcional)	IDs específicos de archivos a cargar

cancel(fileId?)

Cancelar cargas en curso.

// Cancelar todas las cargas
actions.cancel();

// Cancelar archivo específico
actions.cancel('file-id');

Parámetro	Tipo	Descripción
fileId	string (opcional)	ID específico de archivo a cancelar

remove(fileId)

Eliminar un archivo de la lista.

actions.remove('file-id');

Parámetro	Tipo	Descripción
fileId	string	ID del archivo a eliminar

reset()

Eliminar todos los archivos y reiniciar estado.

actions.reset();

retry(fileIds?)

Reintentar cargas fallidas.

// Reintentar todas las cargas fallidas
actions.retry();

// Reintentar archivos específicos
actions.retry(['file-id-1']);

Parámetro	Tipo	Descripción
fileIds	string[] (opcional)	IDs específicos de archivos a reintentar

addFiles(files)

Agregar archivos programáticamente.

// Desde portapapeles
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files) {
    actions.addFiles(files);
  }
});

// Desde otra fuente
actions.addFiles([file1, file2]);

Parámetro	Tipo	Descripción
files	File[] | FileList	Archivos a agregar

updateFileMeta(fileId, meta)

Actualizar metadatos de archivo.

actions.updateFileMeta('file-id', {
  description: 'Mi foto',
  tags: ['vacaciones', '2024'],
});

Parámetro	Tipo	Descripción
fileId	string	ID del archivo a actualizar
meta	Record<string, unknown>	Metadatos a combinar

getDropProps

Retorna props para expandir en el elemento de zona de soltar.

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  Suelta archivos aquí
</div>

Con props personalizadas

<div
  {...getDropProps({
    className: 'my-dropzone',
    onClick: (e) => {
      // Tu manejador de click personalizado
      console.log('¡Click!');
    },
  })}
>
  <input {...getInputProps()} />
</div>

Props retornadas

Propiedad	Tipo	Descripción
onDragEnter	function	Manejador de entrada de arrastre
onDragOver	function	Manejador de arrastre encima
onDragLeave	function	Manejador de salida de arrastre
onDrop	function	Manejador de soltar
onClick	function	Manejador de click (abre diálogo)
role	string	Rol de accesibilidad
tabIndex	number	Índice de tabulación para enfoque

getInputProps

Retorna props para expandir en el input de archivo oculto.

const { getInputProps } = useDropup();

<input {...getInputProps()} />

Con props personalizadas

<input
  {...getInputProps({
    id: 'file-input',
    name: 'files',
  })}
/>

Props retornadas

Propiedad	Tipo	Descripción
type	'file'	Tipo de input
accept	string	Tipos de archivo aceptados
multiple	boolean	Permitir múltiples archivos
onChange	function	Manejador de cambio
style	object	Estilos ocultos

openFileDialog

Función para abrir programáticamente el selector de archivos.

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  Explorar archivos
</button>

Ejemplos de uso

Lista de archivos completa

function FileList() {
  const { files, actions, state } = useDropup({
    upload: { url: '/api/upload' },
  });

  return (
    <div>
      <h3>Archivos ({files.length})</h3>

      {files.map(file => (
        <div key={file.id}>
          {file.preview && (
            <img src={file.preview} alt="" width={50} />
          )}
          <span>{file.name}</span>
          <span>{(file.size / 1024).toFixed(1)} KB</span>
          <span>{file.status}</span>

          {file.status === 'uploading' && (
            <progress value={file.progress} max={100} />
          )}

          {file.status === 'error' && (
            <>
              <span style={{ color: 'red' }}>{file.error?.message}</span>
              <button onClick={() => actions.retry([file.id])}>Reintentar</button>
            </>
          )}

          <button onClick={() => actions.remove(file.id)}>Eliminar</button>
        </div>
      ))}

      {state.isUploading && (
        <p>Cargando... {state.progress}%</p>
      )}

      <button
        onClick={() => actions.upload()}
        disabled={state.isUploading || files.length === 0}
      >
        Cargar todo
      </button>

      <button onClick={() => actions.reset()}>
        Limpiar todo
      </button>
    </div>
  );
}

Estilos de estado de arrastre

function StyledDropzone() {
  const { state, getDropProps, getInputProps } = useDropup({
    accept: 'image/*',
  });

  const getStyle = () => {
    if (state.isDragAccept) return { borderColor: 'green', backgroundColor: '#e8f5e9' };
    if (state.isDragReject) return { borderColor: 'red', backgroundColor: '#ffebee' };
    if (state.isDragging) return { borderColor: 'blue', backgroundColor: '#e3f2fd' };
    return { borderColor: 'gray', backgroundColor: 'white' };
  };

  return (
    <div
      {...getDropProps()}
      style={{
        border: '2px dashed',
        borderRadius: 8,
        padding: 40,
        textAlign: 'center',
        transition: 'all 0.2s',
        ...getStyle(),
      }}
    >
      <input {...getInputProps()} />
      {state.isDragReject ? (
        <p>¡Solo se aceptan imágenes!</p>
      ) : (
        <p>Suelta imágenes aquí</p>
      )}
    </div>
  );
}