Загрузчик сам отправляет файлы по HTTP. Если файлы нужно только выбрать и отправить вместе с формой — возьмите поле CdsFileInput, а для зоны перетаскивания с превью изображений — CdsFileUpload.

Анатомия

Первая схема — каркас: лейбл, описание, кнопка загрузки и сообщения. Вторая — элемент списка файлов во время загрузки: статус, имя-ссылка, действия и полоса прогресса.

Storybook

Вариации

Кнопка загрузки

По умолчанию загрузку запускает primary-кнопка «Загрузить файл» с иконкой upload-icon. Свойство button-props передаёт кнопке любые свойства CdsButton, а слот default заменяет её целиком — готовые пропсы кнопки приходят в параметре слота props.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsButton, CdsUploader } from '@central-design-system/components';
import { ref } from 'vue';

const documents = ref<NUploader.IUploadFile[]>([]);
const photos = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsUploader
      v-model="documents"
      label="Свойства кнопки"
      action="https://user1694090019726.requestly.dev/upload"
      :button-props="{ variant: 'soft', text: 'Прикрепить файлы' }"
    />

    <CdsUploader
      v-model="photos"
      label="Своя кнопка через слот"
      action="https://user1694090019726.requestly.dev/upload"
    >
      <template #default="{ props }">
        <CdsButton v-bind="props" variant="soft" color="neutral" prepend-icon="add" text="Добавить фото" />
      </template>
    </CdsUploader>
  </div>
</template>

Разрешённые типы файлов

Свойство accept ограничивает выбор в системном диалоге и отфильтровывает неподходящие файлы при перетаскивании — отклонённые приходят в событии reject.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка файла"
      description="Подойдут только изображения jpeg, jpg или png"
      action="https://user1694090019726.requestly.dev/upload"
      accept="image/png, image/jpeg"
    />
  </div>
</template>

Список файлов

Список загруженных файлов живёт в v-model — положите туда файлы, полученные с сервера, и они отобразятся сразу. Свойство show-upload-list управляет списком: false скрывает его целиком, объект — включает иконки скачивания и удаления.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([
  {
    uid: '1',
    name: 'dummy.pdf',
    status: 'done',
    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  },
  {
    uid: '2',
    name: 'B2b-elbcp-180x130.png',
    status: 'done',
    url: 'https://upload.wikimedia.org/wikipedia/commons/a/ae/B2b-elbcp-180x130.png'
  }
]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Документы"
      description="Уже загруженные файлы приходят через v-model"
      action="https://user1694090019726.requestly.dev/upload"
      :show-upload-list="{ showDownloadIcon: true, showRemoveIcon: true }"
    />
  </div>
</template>

Количество файлов

Свойство max-count ограничивает длину списка: при max-count="1" новый файл заменяет предыдущий, при большем лимите лишние файлы отбрасываются.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';
import { ref } from 'vue';

const avatar = ref<NUploader.IUploadFile[]>([]);
const documents = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsUploader
      v-model="avatar"
      label="Фото профиля"
      description="Новый файл заменяет предыдущий"
      action="https://user1694090019726.requestly.dev/upload"
      accept="image/png, image/jpeg"
      :max-count="1"
    />

    <CdsUploader
      v-model="documents"
      label="Документы"
      description="Не больше трёх файлов — лишние отбрасываются"
      action="https://user1694090019726.requestly.dev/upload"
      :max-count="3"
    />
  </div>
</template>

Загрузка директорий

Свойство directory включает выбор папки целиком — файлы собираются из неё рекурсивно, в том числе при перетаскивании.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsButton, CdsUploader } from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка директории"
      description="Выберите папку — файлы соберутся из неё рекурсивно"
      action="https://user1694090019726.requestly.dev/upload"
      directory
    >
      <template #default="{ props }">
        <CdsButton v-bind="props" text="Загрузить директорию" />
      </template>
    </CdsUploader>
  </div>
</template>

Состояния

disabled блокирует кнопку и убирает иконки удаления из списка, readonly запрещает менять список, но оставляет скачивание.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';

const files: NUploader.IUploadFile[] = [
  {
    uid: '1',
    name: 'dummy.pdf',
    status: 'done',
    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  }
];
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsUploader label="Disabled" description="Загрузка недоступна" disabled />

    <CdsUploader
      label="Readonly"
      description="Список нельзя изменить, скачивание работает"
      :model-value="files"
      :show-upload-list="{ showDownloadIcon: true }"
      readonly
    />
  </div>
</template>

Слоты

Когда пропсов недостаточно, содержимое любого блока заменяется слотом.

Имя слота	Описание
label	Содержимое лейбла (замещает label)
description	Содержимое описания (замещает description)
prepend	Элемент перед кнопкой загрузки
default	Своя кнопка загрузки; получает готовые props для CdsButton
append	Элемент после кнопки загрузки
messages	Содержимое блока сообщений
itemRender	Свой рендер элемента списка; получает file, fileList и actions

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import {
  CdsButton,
  CdsFunctionalButton,
  CdsIcon,
  CdsListItem,
  CdsTooltip,
  CdsUploader
} from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([
  {
    uid: '1',
    name: 'dummy.pdf',
    status: 'done',
    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  }
]);

const clearAll = () => {
  files.value = [];
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader v-model="files" action="https://user1694090019726.requestly.dev/upload">
      <template #label>
        <span class="flex items-center gap-0.5">
          Загрузка файла
          <CdsTooltip text="Дополнительная информация">
            <template #activator="{ props }">
              <CdsIcon name="info" v-bind="props" />
            </template>
          </CdsTooltip>
        </span>
      </template>

      <template #description> Подойдёт любой формат — <strong>jpg, png, doc, zip</strong> — до 10 МБ. </template>

      <template #default="{ props }">
        <CdsButton v-bind="props" text="Выбрать файл" />
      </template>

      <template #append>
        <CdsFunctionalButton icon="delete" aria-label="Удалить все файлы" @click="clearAll">
          <CdsTooltip activator="parent">Удалить все файлы</CdsTooltip>
        </CdsFunctionalButton>
      </template>

      <template #messages>Файлы проверяются после загрузки</template>

      <template #itemRender="{ file, actions }">
        <CdsListItem :title="file?.name">
          <template #append>
            <CdsFunctionalButton icon="download" aria-label="Скачать файл" @click="actions.download" />
            <CdsFunctionalButton icon="delete" aria-label="Удалить файл" @click="actions.remove" />
          </template>
        </CdsListItem>
      </template>
    </CdsUploader>
  </div>
</template>

Рекомендации

Storybook

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

Отложенная отправка

Хук before-upload, возвращающий false, отключает автоматическую отправку: файлы копятся в списке, а загрузку запускает отдельная кнопка в слоте append — например, вместе с отправкой всей формы.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsButton, CdsToast, CdsUploader } from '@central-design-system/components';
import { ref, unref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([]);
const loading = ref(false);
const uploaded = ref(false);

const beforeUpload = (file: NUploader.IUploadFile): boolean => {
  files.value = [...(unref(files) || []), file];
  return false;
};

const handleUpload = async () => {
  loading.value = true;
  await new Promise((resolve) => setTimeout(resolve, 3000));
  files.value = [];
  loading.value = false;
  uploaded.value = true;
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Выберите файлы"
      description="Файлы копятся в списке, загрузку запускает кнопка"
      :before-upload="beforeUpload"
      :show-upload-list="{ showRemoveIcon: true }"
    >
      <template #default="{ props }">
        <CdsButton
          variant="soft"
          color="brand"
          text="Выбрать файлы"
          :disabled="props.disabled"
          :readonly="props.readonly"
        />
      </template>
      <template #append>
        <CdsButton prepend-icon="upload" :loading="loading" :disabled="!files.length" @click="handleUpload">
          Загрузить файлы
        </CdsButton>
      </template>
    </CdsUploader>
    <CdsToast v-model="uploaded" title="Файлы успешно загружены" status="success" />
  </div>
</template>

Проверка перед загрузкой

Тот же before-upload — точка для валидации: верните false, и файл не уйдёт на сервер. Отклонённый файл всё равно попадает в список — уберите его в обработчике change, а причину покажите через error-messages.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';
import { ref } from 'vue';

const MAX_SIZE_MB = 5;

const files = ref<NUploader.IUploadFile[]>([]);
const errors = ref<string[]>([]);

const beforeUpload = (file: NUploader.IUploadFile): boolean => {
  const valid = (file.size ?? 0) <= MAX_SIZE_MB * 1024 * 1024;

  if (!valid) {
    errors.value = [`«${file.name}» больше ${MAX_SIZE_MB} МБ`];
  }

  return valid;
};

const handleChange = (info: NUploader.IUploadChangeParam<NUploader.IUploadFile> | Event) => {
  if (info instanceof Event) return;

  files.value = info.fileList.filter((file) => file.status);
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Вложения"
      :description="`Любые файлы до ${MAX_SIZE_MB} МБ`"
      action="https://user1694090019726.requestly.dev/upload"
      :error-messages="errors"
      :before-upload="beforeUpload"
      @change="handleChange"
    />
  </div>
</template>

Ошибки загрузки

Файл, который сервер отклонил, остаётся в списке со статусом ошибки. Свойство show-tooltip-with-error показывает ответ сервера в тултипе у статуса, а событие error даёт собрать сообщения под полем — здесь они копятся в error-messages и сбрасываются при удалении файла.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([]);
const errors = ref<string[]>([]);

const handleError = (
  _error: NUploader.IUploadRequestError | ProgressEvent,
  response: { message?: string } | null,
  file: NUploader.IUploadFile
) => {
  errors.value = [...errors.value, `${response?.message ?? 'Ошибка сервера'}: ${file.name}`];
};

const handleRemove = () => {
  errors.value = [];
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка с ошибкой"
      description="Тестовый сервер отклоняет любой файл"
      action="https://user1694090019726.requestly.dev/upload-error"
      :error-messages="errors"
      show-tooltip-with-error
      @error="handleError"
      @remove="handleRemove"
    />
  </div>
</template>

Загрузка без сервера

Свойство custom-request заменяет встроенный XHR-транспорт своей функцией: она получает файл и колбэки onProgress, onSuccess, onError, а возвращает объект с методом abort. Здесь загрузка имитируется таймером — так же можно отправлять файлы через SDK или WebSocket.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([]);

// Имитация загрузки: прогресс по таймеру вместо XHR-запроса
const customRequest = ({ onProgress, onSuccess }: NUploader.IUploadRequestOption) => {
  let percent = 0;

  const timer = setInterval(() => {
    percent += 20;
    onProgress?.({ percent });

    if (percent >= 100) {
      clearInterval(timer);
      onSuccess?.({});
    }
  }, 400);

  return { abort: () => clearInterval(timer) };
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка без сервера"
      description="Файл никуда не отправляется — прогресс имитируется"
      :custom-request="customRequest"
      :show-upload-list="{ showRemoveIcon: true }"
    />
  </div>
</template>

События

Компонент сообщает о каждом шаге: change — любое изменение списка, progress, success и error — ход загрузки, remove, drop, reject, download, preview — действия пользователя. Откройте консоль, чтобы увидеть их.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([]);

const handleChange = (info: NUploader.IUploadChangeParam<NUploader.IUploadFile> | Event) => {
  console.log('onChange', info);
};
const handleProgress = (event: NUploader.IUploadChangeParam['event'], file: NUploader.IUploadFile) => {
  console.log('onProgress', event, file);
};
const handleSuccess = (response: Record<string, any>, file: NUploader.IUploadFile) => {
  console.log('onSuccess', response, file);
};
const handleError = (
  event: NUploader.IUploadRequestError | ProgressEvent,
  response: any,
  file: NUploader.IUploadFile
) => {
  console.log('onError', event, response, file);
};
const handleRemove = (file: NUploader.IUploadFile) => {
  console.log('onRemove', file);
};
const handleDrop = (event: DragEvent) => {
  console.log('onDrop', event);
};
const handleReject = (rejected: NUploader.IUploadFile[]) => {
  console.log('onReject', rejected);
};
const handleDownload = (file: NUploader.IUploadFile) => {
  console.log('onDownload', file);
};
const handlePreview = (file: NUploader.IUploadFile) => {
  console.log('onPreview', file);
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка файлов"
      description="Откройте консоль, чтобы увидеть все циклы событий"
      action="https://user1694090019726.requestly.dev/upload"
      :show-upload-list="{ showDownloadIcon: true, showRemoveIcon: true }"
      @change="handleChange"
      @progress="handleProgress"
      @success="handleSuccess"
      @error="handleError"
      @remove="handleRemove"
      @drop="handleDrop"
      @reject="handleReject"
      @download="handleDownload"
      @preview="handlePreview"
    />
  </div>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
accept	string | string[] | undefined	''	Типы разрешённых файлов
action	NUploader.TAction | undefined	''	URL, куда загружать файлы
activeColor	string | undefined	—	Цвет компонента, когда он находится в активном состоянии
appendIcon	IconValue | undefined	—	Иконка в слоте append после контента
baseColor	string | undefined	—	Цвет неактивного компонента
beforeUpload	((file: NUploader.IUploadFile<any>, fileList: NUploader.IUploadFile<any>[]) => NUploader.TBeforeUploadFileType | Promise<void | NUploader.TBeforeUploadFileType>) | undefined	—	Хук жизненного цикла перед загрузкой файла
bgColor	string | undefined	—	Цвет фона компонента
buttonProps	Partial<CdsButtonProps> | undefined	null	Свойства для компонента CdsButton
capture	boolean | "user" | "environment" | undefined	—	Тип носителя, откуда захватывать файл для загрузки на мобильных устройствах
centerAffix	boolean | undefined	true	Выровнять по вертикали элементы appendInner, prependInner, clearIcon и label по центру.
color	string | undefined	—	Цвет компонента
customRequest	((options: NUploader.IUploadRequestOption<any>) => void) | undefined	—	Собственный запрос на загрузку файла. Переопределяет xhr по умолчанию
data	Record<string, unknown> | ((file: string | Blob | NUploader.IRcFile) => Record<string, unknown>) | {} | undefined	{}	Параметры загрузки файла или функция, возвращающая параметры загрузки файла
defaultFileList	NUploader.IUploadFile<any>[] | undefined	—	Список файлов по умолчанию
description	string | undefined	—	Описание компонента, отображаемое под меткой
direction	"horizontal" | "vertical" | undefined	'horizontal'	Переключение между горизонтальным или вертикальным отображением.
directory	boolean | undefined	—	Загружать директории
disabled	boolean | null | undefined	null	Заблокированное состояние
downloadIcon	IconValue | undefined	'download'	Иконка скачивания файла
error	boolean | undefined	—	Отображает компонент в состояние ошибки
errorMessages	string | readonly string[] | null | undefined	[]	Отображает компонент в состояние ошибки и передает пользовательские сообщения об ошибках. Будет объединяться с любыми проверками, заданными в свойстве rules. Это поле не запускает валидацию.
focused	boolean | undefined	—	Управляет состоянием фокуса компонента. Когда true, компонент считается сфокусированным и может применять соответствующие стили или поведение.
headers	NUploader.TUploadRequestHeaders | undefined	—	Заголовки запроса
hideDetails	boolean | "auto" | undefined	—	Скрытие блока с деталями (сообщениями и подсказками). При значении 'auto' блок скрывается, если нет сообщений
hideMessages	boolean | undefined	—	Скрыть сообщения под полем ввода
hint	string | undefined	—	Текст подсказки, отображаемый под полем ввода
iconColor	string | boolean | undefined	—	Цвет иконки. Принимает булево значение или строку с цветом
id	string | undefined	—	Уникальный идентификатор компонента
isImageUrl	((file: NUploader.IUploadFile<any>) => boolean) | undefined	—	Настройка отображения миниатюр загружаемых файлов (пока не поддерживается)
itemRender	NUploader.TItemRender<any> | undefined	—	Функция рендера для отображения элемента списка загружаемых файлов
label	string | undefined	—	Текст метки (label) компонента
listType	NUploader.TUploadListType | undefined	'text'	Тип списка загружаемых файлов (поддерживается только 'text')
maxCount	number | undefined	—	Максимальное количество загружаемых файлов
maxErrors	string | number | undefined	1	Максимальное число отображаемых ошибок при валидации
maxWidth	string | number | undefined	—	Максимальная ширина компонента
messages	string | readonly string[] | undefined	[]	Сообщения для отображения под полем ввода
method	NUploader.TUploadRequestMethod | undefined	—	Тип http-запроса для загрузки файлов
minWidth	string | number | undefined	—	Минимальная ширина компонента
modelValue	any	—	Значение компонента в v-model. Если компонент поддерживает свойство multiple, по умолчанию используется пустой массив.
multiple	boolean | undefined	true	Множественная загрузка файлов
name	string | undefined	—	Имя поля ввода
openFileDialogOnClick	boolean | undefined	—	Открывать ли системное окно при клике на загрузчик файлов
persistentHint	boolean | undefined	—	Всегда отображать подсказку, а не только при фокусе
prependIcon	IconValue | undefined	—	Иконка в слоте prepend перед контентом
readonly	boolean | null | undefined	null	Только для чтения
removeIcon	IconValue | undefined	'delete'	Иконка удаления файла
rules	readonly ValidationRule[] | undefined	[]	Принимает массив, состоящий из элементов различных типов: функций, логических значений и строк. Функции принимают входное значение в качестве аргумента и должны возвращать либо true / false, либо строку, содержащую сообщение об ошибке. Поле ввода перейдет в состояние ошибки, если функция возвращает значение false (или любое значение в массиве содержит false) либо является строкой.
showTooltipWithError	boolean | undefined	false	Показывать ли тултип с ошибкой возле каждого файла
showUploadList	boolean | NUploader.TShowUploadList | undefined	true	Показывать список загруженных файлов
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Размер компонента
tag	string | JSXComponent<any> | undefined	'span'	Пользовательский HTML-тег для отображения
textColor	string | undefined	—	Цвет текста компонента
theme	string | undefined	—	Тема компонента
uploadIcon	IconValue | undefined	'upload'	Иконка загрузки файла
validateOn	ValidateOn | undefined	—	Изменяет тип события, при котором запускается валидация
validationValue	any	—	Значение, используемое при применении правил валидации
width	string | number | undefined	—	Ширина компонента
withCredentials	boolean | undefined	—	Запрос с передачей cookie

События

Имя	Тип	Описание
change	[info: NUploader.IUploadChangeParam<NUploader.IUploadFile<any>>]	Событие изменения поля ввода
download	[file: NUploader.IUploadFile<any>]	Событие при скачивании файла
drop	[event: DragEvent]	Событие при drag-n-drop файла
error	[error: ProgressEvent<EventTarget> | NUploader.IUploadRequestError, response: any, file: NUploader.IUploadFile<any>]	Событие ошибки загрузки файла
preview	[file: NUploader.IUploadFile<any>]	Событие при просмотре превью файла
progress	[event: { percent: number; } | undefined, file: NUploader.IUploadFile<any>]	Событие процесса загрузки файла
reject	[fileList: NUploader.IUploadFile<any>[]]	Событие при отклонении загрузки файла
remove	[file: NUploader.IUploadFile<any>]	Событие при удалении файла
success	[response: Record<string, unknown>, file: NUploader.IUploadFile<any>]	Событие успешной загрузки файла
update:modelValue	[fileList: NUploader.IUploadFile<any>[]]	Событие при изменении значения (v-model)

Слоты

Имя	Тип	Описание
append	any	Контент в слоте append после кнопки загрузки.
default	{ props: Partial<CdsButtonProps>; }	Кнопка/активатор загрузки. Получает props для CdsButton.
description	any	Описание под меткой.
itemRender	{ originNode: VNode<RendererNode, RendererElement, { [key: string]: any; }>; file?: NUploader.IUploadFile<any> | undefined; fileList?: NUploader.IUploadFile<any>[] | undefined; actions: { download?: (() => void) | undefined; preview?: (() => void) | undefined; remove?: (() => void) | undefined; }; }	Кастомный рендер элемента списка загружаемых файлов.
label	any	Метка (label) поля загрузки.
messages	any	Сообщения подсказки/ошибки.
prepend	any	Контент в слоте prepend перед кнопкой загрузки.

Exposed

Имя	Тип	Описание
fileList	NUploader.IUploadFile<any>[]	Текущий список файлов со статусами загрузки.
uploadRef	NUploader.IUploaderRef | undefined	Ссылка на внутренний элемент загрузки — даёт доступ к программному выбору файлов и прерыванию.