Upload компонент

Компонент Upload в Naive UI предоставляет мощный и гибкий инструмент для организации загрузки файлов в веб-приложениях на JavaScript с использованием Vue.js. Он поддерживает как одиночную, так и множественную загрузку, позволяет полностью контролировать процесс отправки, предварительный просмотр файлов и обработку ошибок.

Подключение и базовая конфигурация

Для начала необходимо импортировать компонент:

import { NUpload } from 'naive-ui';

Простейшее использование выглядит следующим образом:

<template>
  <n-upload :action="uploadUrl" />
</template>

<script>
export default {
  data() {
    return {
      uploadUrl: 'https://example.com/upload'
    };
  }
};
</script>

Ключевой параметр action указывает URL, на который будут отправляться файлы. Он может быть строкой или функцией, возвращающей строку, что позволяет динамически менять адрес в зависимости от условий.

Управление файлами

С Upload компонентом можно управлять состоянием загружаемых файлов через v-model:value:

<n-upload
  v-model:value="fileList"
  :action="uploadUrl"
/>

export default {
  data() {
    return {
      fileList: []
    };
  }
};

fileList содержит массив объектов с информацией о файлах:

name — имя файла.
status — статус загрузки (pending, uploading, done, error).
percentage — процент загрузки.
url — ссылка на загруженный файл (если сервер возвращает URL).

Настройка ограничений

Upload позволяет задавать ограничения на тип файлов и размер:

<n-upload
  :accept="'.png,.jpg,.jpeg'"
  :max-size="1048576"  <!-- 1 MB -->
  :multiple="true"
  v-model:value="fileList"
  :action="uploadUrl"
/>

accept — перечисление разрешённых типов файлов.
max-size — максимальный размер файла в байтах.
multiple — разрешение множественного выбора файлов.

Если файл не соответствует ограничениям, компонент автоматически вызывает событие on-exceed, где можно обработать ошибку:

<n-upload
  :accept="'.png,.jpg'"
  :max-size="1048576"
  :multiple="true"
  v-model:value="fileList"
  :action="uploadUrl"
  @on-exceed="handleExceed"
/>

methods: {
  handleExceed(files, fileList) {
    console.warn('Файлы превышают ограничения:', files);
  }
}

Настройка процесса загрузки

Upload компонент поддерживает контролируемую загрузку, позволяя перехватывать процесс и использовать собственные методы отправки:

<n-upload
  v-model:value="fileList"
  :custom-request="customUpload"
/>

methods: {
  async customUpload({ file, onProgress, onFinish, onError }) {
    try {
      const formData = new FormData();
      formData.append('file', file);
      const response = await fetch('https://example.com/upload', {
        method: 'POST',
        body: formData
      });
      const result = await response.json();
      onFinish(result);
    } catch (error) {
      onError(error);
    }
  }
}

Параметры функции customUpload:

file — объект загружаемого файла.
onProgress — функция для обновления прогресса загрузки.
onFinish — вызывается после успешной загрузки.
onError — вызывается при ошибке.

Превью файлов

Для отображения миниатюр загруженных файлов используется слот default или встроенные свойства:

<n-upload
  v-model:value="fileList"
  :list-type="'picture-card'"
  :action="uploadUrl"
/>

Типы отображения:

text — стандартный список файлов.
picture — список с иконками и названием.
picture-card — карточки с миниатюрами изображений.

С помощью слотов можно полностью кастомизировать внешний вид превью:

<n-upload v-model:value="fileList" :action="uploadUrl">
  <template #file="{ file }">
    <div class="custom-file-preview">
      <img :src="file.url" alt="" />
      <span>{{ file.name }}</span>
    </div>
  </template>
</n-upload>

Обработка событий

Компонент генерирует следующие события для контроля процесса:

on-change — вызывается при изменении списка файлов.
on-remove — при удалении файла.
on-progress — при обновлении прогресса загрузки.
on-success — после успешной загрузки.
on-error — при ошибке загрузки.

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

<n-upload
  v-model:value="fileList"
  :action="uploadUrl"
  @on-change="handleChange"
  @on-remove="handleRemove"
  @on-progress="handleProgress"
/>

methods: {
  handleChange(files) {
    console.log('Список файлов обновлен:', files);
  },
  handleRemove(file) {
    console.log('Файл удален:', file);
  },
  handleProgress({ file, percentage }) {
    console.log(`Загрузка ${file.name}: ${percentage}%`);
  }
}

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

drag — позволяет использовать drag-and-drop для выбора файлов:

<n-upload
  v-model:value="fileList"
  :action="uploadUrl"
  :drag="true"
/>

disabled — блокирует возможность загрузки.
headers — позволяет добавлять кастомные HTTP-заголовки при отправке.
data — дополнительные данные формы, отправляемые вместе с файлами.

Интеграция с серверной валидацией

Часто требуется проверка загруженных файлов на сервере. Можно обработать ответ сервера в on-success:

methods: {
  handleSuccess(file, response) {
    if (!response.ok) {
      file.status = 'error';
    }
  }
}

Это позволяет гибко управлять состоянием файла и отображать ошибки пользователю.