Справочник по возвращаемым значениям

Всё, что возвращается хуком useDropup.

Обзор

const {
  files,          // Массив объектов файлов
  state,          // Текущее состояние
  actions,        // Доступные действия
  getDropProps,   // Свойства для зоны сброса
  getInputProps,  // Свойства для элемента input
  openFileDialog, // Открыть выбор файла
} = useDropup();

files

Массив объектов DropupFile, представляющих все добавленные файлы.

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://..." (только изображения)
  console.log(file.uploadedUrl); // "https://..." (после загрузки)
  console.log(file.error);       // DropupError (при провале)
});

Свойства DropupFile

Свойство	Тип	Описание
id	string	Уникальный идентификатор
file	File	Исходный объект File браузера
name	string	Имя файла
size	number	Размер в байтах
type	string	MIME тип
status	FileStatus	Текущий статус
progress	number	Прогресс загрузки (0-100)
preview	string | undefined	URL превью для изображений
uploadedUrl	string | undefined	URL после успешной загрузки
response	unknown	Данные ответа сервера
error	DropupError | undefined	Ошибка при провале загрузки
meta	Record<string, unknown>	Пользовательские метаданные

Значения FileStatus

Статус	Описание
'idle'	Файл добавлен, не загружается
'uploading'	Загрузка в процессе
'complete'	Загрузка успешна
'error'	Загрузка провалена
'paused'	Загрузка приостановлена (возобновляемые загрузки)

state

Текущее состояние зоны сброса.

const { state } = useDropup();

console.log(state.isDragging);   // true при перетаскивании
console.log(state.isDragAccept); // true когда перетаскиваемые файлы валидны
console.log(state.isDragReject); // true когда перетаскиваемые файлы невалидны
console.log(state.isUploading);  // true когда какой-либо файл загружается
console.log(state.progress);     // общий прогресс 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

Свойства State

Свойство	Тип	Описание
isDragging	boolean	Файлы перетаскиваются над зоной сброса
isDragAccept	boolean	Перетаскиваемые файлы проходят валидацию
isDragReject	boolean	Перетаскиваемые файлы не проходят валидацию
isUploading	boolean	Какой-либо файл в данный момент загружается
progress	number	Средний прогресс всех файлов (0-100)
status	DropupStatus	Общий статус загрузки

Значения DropupStatus

Статус	Описание
'idle'	Нет загрузок в процессе
'uploading'	Один или более файлов загружается
'complete'	Все загрузки завершены успешно
'error'	Одна или более загрузок провалены

actions

Объект, содержащий все доступные действия.

const { actions } = useDropup();

// Начать загрузки
actions.upload();              // Загрузить все неактивные файлы
actions.upload(['id1', 'id2']); // Загрузить конкретные файлы

// Отменить загрузки
actions.cancel();              // Отменить все загрузки
actions.cancel('file-id');     // Отменить конкретный файл

// Удалить файлы
actions.remove('file-id');     // Удалить конкретный файл
actions.reset();               // Удалить все файлы

// Повторить проваленные загрузки
actions.retry();               // Повторить все проваленные
actions.retry(['id1']);        // Повторить конкретные файлы

// Добавить файлы программно
actions.addFiles(fileList);    // Добавить File[] или FileList

// Обновить метаданные файла
actions.updateFileMeta('file-id', { tag: 'important' });

Методы действий

upload(fileIds?)

Начать загрузку файлов.

// Загрузить все неактивные файлы
actions.upload();

// Загрузить конкретные файлы
actions.upload(['file-id-1', 'file-id-2']);

Параметр	Тип	Описание
fileIds	string[] (необязательно)	Конкретные ID файлов для загрузки

cancel(fileId?)

Отменить текущие загрузки.

// Отменить все загрузки
actions.cancel();

// Отменить конкретный файл
actions.cancel('file-id');

Параметр	Тип	Описание
fileId	string (необязательно)	Конкретный ID файла для отмены

remove(fileId)

Удалить файл из списка.

actions.remove('file-id');

Параметр	Тип	Описание
fileId	string	ID файла для удаления

reset()

Удалить все файлы и сбросить состояние.

actions.reset();

retry(fileIds?)

Повторить проваленные загрузки.

// Повторить все проваленные загрузки
actions.retry();

// Повторить конкретные файлы
actions.retry(['file-id-1']);

Параметр	Тип	Описание
fileIds	string[] (необязательно)	Конкретные ID файлов для повтора

addFiles(files)

Добавить файлы программно.

// Из буфера обмена
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files) {
    actions.addFiles(files);
  }
});

// Из другого источника
actions.addFiles([file1, file2]);

Параметр	Тип	Описание
files	File[] | FileList	Файлы для добавления

updateFileMeta(fileId, meta)

Обновить метаданные файла.

actions.updateFileMeta('file-id', {
  description: 'Моя фотография',
  tags: ['отпуск', '2024'],
});

Параметр	Тип	Описание
fileId	string	ID файла для обновления
meta	Record<string, unknown>	Метаданные для слияния

getDropProps

Возвращает свойства для распространения на элемент зоны сброса.

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  Перетащите файлы сюда
</div>

С пользовательскими свойствами

<div
  {...getDropProps({
    className: 'my-dropzone',
    onClick: (e) => {
      // Ваш пользовательский обработчик клика
      console.log('Клик!');
    },
  })}
>
  <input {...getInputProps()} />
</div>

Возвращаемые свойства

Свойство	Тип	Описание
onDragEnter	function	Обработчик входа при перетаскивании
onDragOver	function	Обработчик нахождения над при перетаскивании
onDragLeave	function	Обработчик выхода при перетаскивании
onDrop	function	Обработчик сброса
onClick	function	Обработчик клика (открывает диалог)
role	string	Роль для доступности
tabIndex	number	Индекс табуляции для фокуса

getInputProps

Возвращает свойства для распространения на скрытый файловый input.

const { getInputProps } = useDropup();

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

С пользовательскими свойствами

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

Возвращаемые свойства

Свойство	Тип	Описание
type	'file'	Тип input
accept	string	Принимаемые типы файлов
multiple	boolean	Разрешить несколько файлов
onChange	function	Обработчик изменения
style	object	Скрывающие стили

openFileDialog

Функция для программного открытия выбора файлов.

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  Обзор файлов
</button>

Примеры использования

Полный список файлов

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

  return (
    <div>
      <h3>Файлы ({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)} КБ</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])}>Повторить</button>
            </>
          )}

          <button onClick={() => actions.remove(file.id)}>Удалить</button>
        </div>
      ))}

      {state.isUploading && (
        <p>Загрузка... {state.progress}%</p>
      )}

      <button
        onClick={() => actions.upload()}
        disabled={state.isUploading || files.length === 0}
      >
        Загрузить все
      </button>

      <button onClick={() => actions.reset()}>
        Очистить всё
      </button>
    </div>
  );
}

Стилизация состояния перетаскивания

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>Принимаются только изображения!</p>
      ) : (
        <p>Перетащите изображения сюда</p>
      )}
    </div>
  );
}