QFile для загрузки файлов

QFile — компонент библиотеки Quasar, предназначенный для работы с загрузкой файлов в веб-приложениях на Vue.js. Он предоставляет расширенные возможности по выбору, отображению и обработке файлов, интегрируясь с остальными элементами интерфейса Quasar и соблюдая адаптивные стандарты.

Основные свойства QFile

  • v-model Связывает выбранный файл или файлы с реактивной переменной Vue. Может быть строкой (для одного файла) или массивом (для нескольких файлов при multiple).

  • multiple Логическое значение. Позволяет выбирать несколько файлов одновременно. Если не указано, можно выбрать только один файл.

  • accept Определяет допустимые типы файлов, которые можно выбрать. Принимает MIME-типы или расширения файлов:

    accept=".jpg,.png,image/*"

  • label Текстовая метка для кнопки выбора файлов. Может быть динамической и обновляться в зависимости от состояния выбора.

  • counter Показывает количество выбранных файлов при множественном выборе.

  • hide-upload-btn Убирает встроенную кнопку загрузки, позволяя реализовать кастомное оформление кнопки.

  • clearable Добавляет кнопку для очистки выбранных файлов.

Работа с событиями QFile

  • @added Срабатывает после добавления файлов в компонент. Возвращает массив файлов.

  • @removed Срабатывает при удалении файлов из выбора.

  • @rejected Срабатывает при попытке добавить файл, не соответствующий условиям (тип, размер). Возвращает объект с причиной отклонения.

  • @uploaded Используется вместе с автоматической загрузкой через use-upload, сигнализируя об успешной загрузке на сервер.

Ограничение выбора файлов

QFile позволяет ограничивать размеры и типы файлов для предотвращения ошибок загрузки. Основные свойства для контроля:

  • max-files — максимальное количество файлов для множественного выбора.
  • max-file-size — максимальный размер одного файла в байтах.
  • min-file-size — минимальный размер одного файла в байтах.
  • filter — функция, позволяющая программно отфильтровать файлы перед добавлением.

Пример ограничения по размеру и типу файла:

<QFile
  v-model="files"
  multiple
  :max-files="5"
  :max-file-size="10485760"
  accept="image/*"
  @rejected="handleRejected"
/>

Функция обработки отклонённых файлов:

function handleRejected(rejectedFiles) {
  rejectedFiles.forEach(file => {
    console.warn(`Файл ${file.name} не подходит: ${file.__error}`);
  });
}

Кастомизация внешнего вида

QFile интегрируется с Quasar стилями и позволяет использовать слоты для полного контроля над интерфейсом:

  • slot="append" — добавление кнопки или иконки справа.
  • slot="prepend" — добавление элементов слева.
  • slot="file" — кастомное отображение выбранного файла, включая прогресс загрузки или превью изображения.

Пример кастомного отображения файлов:

<QFile v-model="files" multiple>
  <template v-slot:file="scope">
    <div class="q-pa-xs q-mb-xs">
      <q-chip
        :label="scope.file.name"
        removable
        @remove="scope.remove"
      />
    </div>
  </template>
</QFile>

Интеграция с загрузкой на сервер

QFile может работать с FormData для отправки файлов через HTTP:

function uploadFiles() {
  const formData = new FormData();
  files.forEach(file => formData.append('files[]', file));

  fetch('/upload', {
    method: 'POST',
    body: formData
  })
  .then(response => response.json())
  .then(data => console.log('Загрузка завершена', data))
  .catch(err => console.error('Ошибка загрузки', err));
}

Для автоматической обработки можно использовать use-upload или создать собственный composable для управления состоянием загрузки, прогрессом и ошибками.

Дополнительные возможности

  • Предпросмотр изображений: QFile совместим с компонентами QImg и QAvatar для мгновенного отображения выбранного изображения.
  • Индикация прогресса: через слоты можно показывать прогресс каждого файла.
  • Поддержка drag-and-drop: встроенная поддержка перетаскивания файлов в область QFile при использовании свойства :hide-upload-btn="true" и кастомного оформления.

Пример drag-and-drop:

<QFile
  v-model="files"
  multiple
  hide-upload-btn
  class="q-pa-md bg-grey-2"
  @added="onFilesAdded"
/>
function onFilesAdded(newFiles) {
  newFiles.forEach(file => console.log('Добавлен файл', file.name));
}

QFile в Quasar сочетает удобство выбора и обработки файлов с гибкой кастомизацией интерфейса и полной интеграцией с Vue.js, делая загрузку файлов безопасной, наглядной и контролируемой на всех этапах.

Оглавление