VGFiles

Кастомизированный инпут файл

API и события

Ручная инициализация, параметры, callbacks и DOM-события.

HTML и Data API

VGFiles автоматически инициализирует .vg-files. Вложенные параметры записываются через дефис: limits.count становится data-limits-count, uploads.route — data-uploads-route.

HTML
<div class="vg-files project-files"
     data-ajax="true"
     data-smartdrop="true"
     data-limits-count="12"
     data-limits-sizes="8"
     data-limits-total="64"
     data-types='["image/jpeg", "image/png", "image/webp"]'
     data-uploads-route="/api/files/upload"
     data-uploads-mode="parallel"
     data-uploads-max-parallel="3"
     data-removes-single-route="/api/files/remove"
     data-removes-all-route="/api/files/clear"
     data-sortable-enabled="true"
     data-sortable-route="/api/files/sort">
  <div class="vg-files-stat">
    <span class="vg-files-stat-count"></span>
    <div class="vg-files-stat-progress"></div>
  </div>
  <label class="vg-files-drop" for="project-files">
    <span class="vg-files-drop-message show">
      <span class="title">Перетащите файлы</span>
    </span>
    <ul class="vg-files-drop--list"></ul>
  </label>
  <input id="project-files" type="file" name="files[]"
         accept="image/jpeg,image/png,image/webp"
         data-vg-toggle="files" multiple>
</div>

JavaScript API

Ручная инициализация нужна для callbacks, функций rename/confirm и управления жизненным циклом. getOrCreateInstance не создаёт второй экземпляр.

JAVASCRIPT
import { VGFiles } from 'vgapp';

const root = document.querySelector('#project-files-widget');
const files = new VGFiles(root, {
  ajax: true,
  smartdrop: true,
  rename: true,
  limits: { count: 12, sizes: 8, total: 64 },
  types: ['image/jpeg', 'image/png', 'image/webp'],
  uploads: {
    route: '/api/files/upload',
    mode: 'parallel',
    maxParallel: 3,
    retryAttempts: 2,
    retryDelay: 1200,
  },
  removes: {
    single: { route: '/api/files/remove', alert: true, toast: true },
    all: { route: '/api/files/clear', alert: true, toast: true },
  },
  sortable: { enabled: true, route: '/api/files/sort', handle: '.file' },
});

// Получение и завершение существующего экземпляра
VGFiles.getInstance(root);
files.clear();
files.dispose();

DOM-события и callbacks

Этапы доступны как callbacks конструктора и всплывающие CustomEvent на .vg-files. Полезная нагрузка DOM-события находится в event.detail.

DOM-события
const root = document.querySelector('.vg-files');

root.addEventListener('vg.files.change', ({ detail }) => {
  console.log('Текущий набор:', detail.files);
});
root.addEventListener('vg.files.upload.progress', ({ detail }) => {
  console.log(detail.file.name, detail.progress);
});
root.addEventListener('vg.files.upload.complete', ({ detail }) => {
  console.log('Серверный id:', detail.id, detail.response);
});
root.addEventListener('vg.files.remove', ({ detail }) => {
  console.log('Осталось файлов:', detail.remaining);
});
Callbacks
const files = new VGFiles(root, {
  callbacks: {
    onInit({ element, files }, instance) {},
    onChange({ files, input, inputFiles }, instance) {},
    onUploadStart({ files, total }, instance) {},
    onUploadProgress({ file, progress, bytesSent, totalBytes }, instance) {},
    onUploadComplete({ file, response, status, id }, instance) {},
    onUploadError({ file }, instance) {},
    onUploadAllComplete({ uploaded, failed, total }, instance) {},
    onRemoveFile({ name, size, id, remaining }, instance) {},
    onReload({ button, file }, instance) {},
    onSortableInit(data, instance) {},
  },
});

Контракт сервера

Загрузчик отправляет multipart/form-data с полем file. Верните id: он попадёт в data-id и затем используется удалением и сортировкой.

HTTP / JSON
// POST /api/files/upload — multipart/form-data, поле file
const uploadResponse = { id: 418, message: 'Файл загружен' };

// DELETE /api/files/remove?id=418
const removeResponse = { message: 'Файл удалён' };

// POST /api/files/sort
const sortRequest = { ids: [418, 205, 731] };

CSS-переменные

Токены задаются на .vg-files или классе конкретного экземпляра. Несколько загрузчиков могут иметь разное оформление без повышения специфичности.

CSS
.project-files {
  --vg-files-label-bg: var(--vg-primary);
  --vg-files-label-color: #fff;
  --vg-files-label-border-radius: 8px;
  --vg-files-label-padding: 10px 20px;

  --vg-files-drop-height: 320px;
  --vg-files-drop-bg: var(--vg-surface-muted-bg);
  --vg-files-drop-border-color: var(--vg-border-default);
  --vg-files-drop-hover-border-color: var(--vg-primary);
  --vg-files-drop-radius: 12px;
  --vg-files-drop-file-height: 180px;
  --vg-files-drop-file-flex: calc(33.333% - 6px);
  --vg-files-drop-remove-size: 30px;
  --vg-files-drop-control-icon-size: 16px;

  --vg-files-info-list-max-height: 420px;
  --vg-files-info-hover-bg: var(--vg-surface-muted-bg);
  --vg-files-info-name-font-size: 15px;
  --vg-files-stat-border-color: var(--vg-border-default);
}

Кнопка выбора

--vg-files-label-bg
фон
--vg-files-label-color
текст и SVG
--vg-files-label-border-color
граница
--vg-files-label-border-radius
радиус
--vg-files-label-padding
отступ текста
--vg-files-label-padding-icon
отступ иконки

Dropzone

--vg-files-drop-bg
фон зоны
--vg-files-drop-border-width
толщина границы
--vg-files-drop-border-style
стиль границы
--vg-files-drop-border-color
цвет границы
--vg-files-drop-radius
радиус
--vg-files-drop-height
минимальная высота
--vg-files-drop-hover-bg
фон при наведении
--vg-files-drop-hover-border-color
граница при наведении
--vg-files-drop-hover-shadow
кольцо при наведении
--vg-files-drop-message-color
цвет подсказки
--vg-files-drop-message-icon-size
иконка подсказки
--vg-files-drop-list-gap
зазор плиток
--vg-files-drop-list-padding
отступ списка
--vg-files-drop-file-height
высота плитки
--vg-files-drop-file-flex
ширина плитки
--vg-files-drop-file-radius
радиус плитки
--vg-files-drop-remove-offset
смещение действий
--vg-files-drop-remove-size
размер кнопок
--vg-files-drop-actions-gap
зазор действий
--vg-files-drop-control-icon-size
размер иконок

Список и статистика

--vg-files-stat-padding
отступ статистики
--vg-files-stat-gap
зазор показателей
--vg-files-stat-border-color
граница статистики
--vg-files-info-list-max-height
высота списка
--vg-files-info-border-color
внешняя граница
--vg-files-info-border-bottom-color
разделители
--vg-files-info-radius
радиус списка
--vg-files-info-gap
зазор строки
--vg-files-info-padding
отступ строки
--vg-files-info-hover-bg
фон при наведении
--vg-files-info-name-font-size
размер имени
--vg-files-info-size-font-size
размер объёма
--vg-files-info-remove-icon-size
иконка удаления

Справочник API

Параметры JavaScript и Data API объединяются с настройками по умолчанию. Функции и callbacks передаются только через JavaScript.

Основные параметры

inittrue
Включает инициализацию экземпляра.
allowedfalse
Оставляет только последнее выбранное множество; в AJAX-режиме отключается.
langdocument.lang
Язык сообщений и форматирования размеров.
limits.count0
Максимальное количество; 0 — без ограничения.
limits.sizes10
Максимальный размер одного файла в МБ.
limits.total0
Максимальный общий размер в МБ; 0 — без ограничения.
types[]
Разрешённые MIME-типы.
imagefalse
Превью изображений; для dropzone включается автоматически.
detach / infotrue / true
Показывает удаление и информационный список.
prepend / replacetrue / true
Добавляет в начало и заменяет одиночный выбор.
renamefalse
true генерирует имя; функция получает file и index.
ajax / smartdropfalse / false
Включает загрузчик и глобальный smartdrop.
uploads.route''
POST-маршрут загрузки файла.
uploads.modesequential
sequential или parallel.
uploads.maxParallel3
Размер параллельной группы.
uploads.maxConcurrent1
Число одновременных задач последовательной очереди.
uploads.retryAttempts / retryDelay1 / 1000
Число повторов и задержка в мс.
removes.single / allobject
route, alert, toast, confirm и buttons.
sortable.enabled / routefalse / ''
Сортировка и POST-маршрут массива ids.
sortable.handle.file
Область начала перетаскивания.

Публичные методы

getInstance(element)
Возвращает существующий экземпляр или null.
getOrCreateInstance(element, options)
Возвращает экземпляр либо создаёт новый.
change(input)
Считывает FileList, валидирует и перестраивает интерфейс.
build()
Повторно строит список, статистику и скрытые input.
uploadAll(files)
Запускает очередь ещё не загруженных файлов.
upload(file)
Загружает или повторяет один File.
reload(button)
Повторяет ошибочную загрузку по data-vg-reload="file".
removeFile(button)
Удаляет файл по data-vg-dismiss="file".
clear(resetInput = true)
Очищает файлы, ошибки, превью, статистику и input.
dispose()
Удаляет обработчики, sortable, uploader и экземпляр.

DOM-события

vg.files.changefiles, input, inputFiles
После изменения набора.
vg.files.upload.startfiles, total
Перед запуском очереди.
vg.files.upload.progressfile, progress, bytesSent, totalBytes
Во время передачи файла.
vg.files.upload.completefile, response, status, id
После успешной загрузки.
vg.files.upload.errorfile
После окончательной ошибки.
vg.files.upload.allComplete
Когда очередь завершилась.
vg.files.removename, size, id, remaining
После удаления.
vg.files.reloadbutton, file
Перед повторной загрузкой.