VGFiles
API и события
Ручная инициализация, параметры, callbacks и DOM-события.
HTML и Data API
VGFiles автоматически инициализирует .vg-files. Вложенные параметры записываются через дефис: limits.count становится data-limits-count, uploads.route — data-uploads-route.
<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 не создаёт второй экземпляр.
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.
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);
});
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 и затем используется удалением и сортировкой.
// 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 или классе конкретного экземпляра. Несколько загрузчиков могут иметь разное оформление без повышения специфичности.
.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- Перед повторной загрузкой.