Нужна заметная зона загрузки со списком файлов — возьмите CdsFileUpload; за отправку файлов на сервер отвечает CdsUploader.

Анатомия

Компонент построен на той же базе, что и CdsTextInput: лейбл, описание, сообщения, валидация и цвета работают одинаково. Своё у поля — иконка загрузки слева (prepend-icon, по умолчанию upload), имена выбранных файлов вместо вводимого текста и счётчик файлов в нижнем блоке. Очистка (clearable) включена из коробки.

Storybook

Вариации

Лейбл и подсказки

label называет поле, в description помещаются требования к файлам, placeholder подсказывает, что файл можно перетащить в поле. Выбранный файл отображается своим именем.

Sandbox Storybook

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

const model = ref<File | null>(null);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Документ"
      description="Прикрепите один файл"
      placeholder="Выберите или перетащите файл в поле"
    />
  </div>
</template>

Несколько файлов

Свойство multiple разрешает выбрать сразу несколько файлов — их имена перечисляются через запятую.

Sandbox Storybook

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

const model = ref<File[]>([]);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Вложения"
      description="Можно выбрать несколько файлов"
      placeholder="Выберите или перетащите файлы в поле"
      multiple
    />
  </div>
</template>

Отображение тегами

Свойство chips показывает каждый файл отдельным тегом (CdsTag) — список из нескольких файлов читается легче.

Sandbox Storybook

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

const model = ref<File[]>([]);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Вложения"
      description="Выбранные файлы показываются тегами"
      placeholder="Выберите или перетащите файл в поле"
      multiple
      chips
    />
  </div>
</template>

Размер и счётчик

show-size добавляет к имени файла его размер, counter выводит количество и суммарный размер под полем. Длинные имена усекаются посередине — порог задаёт truncate-length (по умолчанию 22 символа).

Sandbox Storybook

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

const model = ref<File[]>([]);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Вложения"
      description="Отображается размер файлов и счётчик"
      placeholder="Выберите или перетащите файл в поле"
      multiple
      show-size
      counter
    />
  </div>
</template>

Фильтр по типам

filter-by-type принимает MIME-типы, wildcard-типы и расширения через запятую (image/*,.pdf). Неподходящие файлы не попадают в модель — о них сообщает событие rejected: покажите пользователю, что именно отклонено и почему.

Sandbox Storybook

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

const files = ref<File[]>([]);
const rejectedMessages = ref<string[]>([]);

// `rejected` срабатывает до обновления модели — флаг защищает свежие
// сообщения от сброса в обработчике update:model-value
let justRejected = false;

function onRejected(rejected: File[]) {
  rejectedMessages.value = rejected.map((file) => `${file.name} — не подходит по формату`);
  justRejected = true;
}

function onUpdate() {
  if (justRejected) {
    justRejected = false;

    return;
  }

  rejectedMessages.value = [];
}
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="files"
      label="Сканы документов"
      description="Только изображения или PDF"
      placeholder="Выберите или перетащите файлы"
      filter-by-type="image/*,.pdf"
      multiple
      :error-messages="rejectedMessages"
      @rejected="onRejected"
      @update:model-value="onUpdate"
    />
  </div>
</template>

Состояния

disabled блокирует поле, readonly даёт посмотреть выбранное, но не изменить, loading показывает индикатор — например, пока файлы уходят на сервер.

Sandbox Storybook

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

const file = ref<File | null>(null);

// Файлы создаются только в браузере — SSR-сборка сайта обходится без File
onMounted(() => {
  file.value = new File([new Uint8Array(240_000)], 'отчёт-за-квартал.pdf', { type: 'application/pdf' });
});
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput label="Disabled" placeholder="Выберите файл" disabled />
    <CdsFileInput :model-value="file" label="Readonly" readonly />
    <CdsFileInput :model-value="file" label="Loading" loading />
  </div>
</template>

Слоты

Зоны поля совпадают с CdsTextInput: prepend / append снаружи рамки, prepend-inner / append-inner внутри. Дополнительный слот selection заменяет стандартный список имён файлов.

Имя слота	Описание
label	Содержимое лейбла (замещает label)
description	Содержимое описания (замещает description)
prepend	Элемент до поля (замещает иконку загрузки)
append	Элемент после поля
prepend-inner	Элемент в начале поля, внутри рамки
append-inner	Элемент в конце поля, внутри рамки
selection	Своё отображение выбранных файлов
clear	Своя иконка очистки (при clearable)
loader	Свой индикатор загрузки (при loading)
counter	Содержимое счётчика
details	Нижний блок целиком — сообщения и счётчик
messages	Содержимое блока сообщений

В слот selection приходят усечённые имена файлов (fileNames) и суммарный размер (totalBytes, totalBytesReadable).

Sandbox Storybook

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

const files = ref<File[]>([]);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="files"
      label="Вложения"
      placeholder="Выберите или перетащите файлы"
      multiple
      show-size
      counter
    >
      <template #selection="{ fileNames }">
        <CdsTag v-for="name in fileNames" :key="name" prepend-icon="file" size="sm" :text="name" />
      </template>
    </CdsFileInput>
  </div>
</template>

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

Storybook

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

Отправка формы с вложениями

Поле участвует в валидации CdsForm наравне с остальными: rules получают выбранные файлы — проверьте, что вложения приложены и не превышают лимит размера, до отправки на сервер. chips и counter помогают пользователю следить за списком.

Sandbox Storybook

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

const valid = ref(false);
const topic = ref('');
const files = ref<File[]>([]);
const loading = ref(false);
const sent = ref(false);

const topicRules = [(value: string) => !!value || 'Укажите тему обращения'];

const fileRules = [
  (value: File[]) => (value?.length ?? 0) > 0 || 'Приложите хотя бы один файл',
  (value: File[]) =>
    (value ?? []).every((file) => file.size <= 10 * 1024 * 1024) || 'Файл больше 10 МБ — сожмите его или разбейте архив'
];

async function submit() {
  if (!valid.value) return;

  try {
    loading.value = true;
    sent.value = false;
    await new Promise((resolve) => setTimeout(resolve, 1500));
    sent.value = true;
  } finally {
    loading.value = false;
  }
}
</script>

<template>
  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
    <CdsTextInput v-model="topic" label="Тема обращения" :rules="topicRules" />

    <CdsFileInput
      v-model="files"
      label="Вложения"
      description="До 10 МБ каждый файл"
      placeholder="Выберите или перетащите файлы"
      :rules="fileRules"
      multiple
      chips
      counter
    />

    <CdsButton type="submit" :loading="loading" text="Отправить обращение" />

    <p v-if="sent" class="text-sm text-center">Обращение отправлено</p>
  </CdsForm>
</template>

Кнопка загрузки без поля

Свойство hide-input скрывает поле, оставляя только кликабельную иконку — удобно встроить загрузку в тулбар или строку комментария. Выбранные файлы показывайте рядом сами: здесь — тегами с closable, клик по крестику убирает файл из модели.

Sandbox Storybook

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

const files = ref<File[]>([]);

function removeFile(name: string) {
  files.value = files.value.filter((file) => file.name !== name);
}
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <div class="flex items-center gap-1">
      <span>Прикрепите файлы к комментарию</span>
      <CdsFileInput v-model="files" hide-input hide-details multiple aria-label="Прикрепить файлы" />
    </div>

    <div v-if="files.length" class="flex flex-wrap justify-center gap-1">
      <CdsTag
        v-for="file in files"
        :key="file.name"
        prepend-icon="file"
        :text="file.name"
        closable
        @click:close="removeFile(file.name)"
      />
    </div>
  </div>
</template>

Превью изображения

filter-by-type="image/*" пропускает только картинки, а превью строится из значения модели через URL.createObjectURL. Не забывайте освобождать предыдущий URL — иначе выбранные файлы копятся в памяти вкладки.

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput } from '@central-design-system/components';
import { onBeforeUnmount, ref, watch } from 'vue';

const file = ref<File | null>(null);
const previewUrl = ref('');

watch(file, (value) => {
  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value);

  previewUrl.value = value ? URL.createObjectURL(value) : '';
});

onBeforeUnmount(() => {
  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value);
});
</script>

<template>
  <div class="flex flex-col items-center gap-2 max-w-sm m-auto">
    <CdsFileInput
      v-model="file"
      class="w-full"
      label="Логотип компании"
      description="PNG, JPG или SVG"
      placeholder="Выберите или перетащите изображение"
      filter-by-type="image/*"
    />

    <img v-if="previewUrl" :src="previewUrl" alt="Превью логотипа" class="max-h-40 rounded" />
  </div>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
active	boolean | undefined	—	Активное состояние поля
activeColor	string | undefined	—	Цвет компонента, когда он находится в активном состоянии
appendIcon	IconValue | undefined	—	Иконка в слоте append после контента
appendInnerIcon	IconValue | undefined	—	Иконка во внутреннем слоте append после содержимого поля
baseColor	string | undefined	—	Цвет неактивного компонента
bgColor	string | undefined	—	Цвет фона компонента
centerAffix	boolean | undefined	—	Выровнять по вертикали элементы appendInner, prependInner, clearIcon и label по центру.
chips	boolean | undefined	—	Отображать выбранные файлы в виде тегов (CdsTag) вместо списка имён.
clearable	boolean | undefined	true	Отображать кнопку очистки значения
clearIcon	IconValue | undefined	'remove'	Иконка кнопки очистки
color	string | undefined	—	Цвет компонента
counter	boolean | undefined	—	Отображать счётчик количества (и, при showSize, суммарного размера) выбранных файлов.
counterSizeString	string | undefined	'$cds.fileInput.counterSize'	Ключ локализации для текста счётчика с размером файлов.
counterString	string | undefined	'$cds.fileInput.counter'	Ключ локализации для текста счётчика количества файлов.
description	string | undefined	—	Описание компонента, отображаемое под меткой
dirty	boolean | undefined	—	Признак того, что значение поля было изменено пользователем
disabled	boolean | null | undefined	null	Заблокированное состояние
error	boolean | undefined	—	Состояние ошибки
errorMessages	string | readonly string[] | null | undefined	[]	Отображает компонент в состояние ошибки и передает пользовательские сообщения об ошибках. Будет объединяться с любыми проверками, заданными в свойстве rules. Это поле не запускает валидацию.
filterByType	string | undefined	—	Фильтрация файлов по MIME-типу или расширению (например image/*,.pdf). Отклонённые файлы не попадают в модель.
focused	boolean | undefined	—	Управляет состоянием фокуса компонента. Когда true, компонент считается сфокусированным и может применять соответствующие стили или поведение.
hideDetails	boolean | "auto" | undefined	—	Скрытие блока с деталями (сообщениями и подсказками). При значении 'auto' блок скрывается, если нет сообщений
hideInput	boolean | undefined	—	Скрыть поле ввода, оставив только иконку prepend (например, для использования как кнопки).
hideMessages	boolean | undefined	—	Скрыть сообщения под полем ввода
hint	string | undefined	—	Текст подсказки, отображаемый под полем ввода
iconColor	string | boolean | undefined	—	Цвет иконки. Принимает булево значение или строку с цветом
id	string | undefined	—	Уникальный идентификатор компонента
label	string | undefined	—	Текст метки (label) компонента
loading	string | boolean | undefined	—	Индикатор загрузки для компонента
maxErrors	string | number | undefined	1	Максимальное число отображаемых ошибок при валидации
maxWidth	string | number | undefined	—	Максимальная ширина компонента
messages	string | readonly string[] | undefined	[]	Сообщения для отображения под полем ввода
minWidth	string | number | undefined	—	Минимальная ширина компонента
modelValue	File | File[] | null | undefined	(props) => props.multiple ? [] : null	Значение модели: массив файлов (при multiple), один файл или null.
multiple	boolean | undefined	—	Разрешить выбор нескольких файлов.
name	string | undefined	—	Имя поля ввода
persistentClearable	boolean | undefined	—	Всегда отображать кнопку очистки, а не только при наведении или фокусе
persistentHint	boolean | undefined	—	Всегда отображать подсказку, а не только при фокусе
placeholder	string | undefined	—	Текст-заполнитель, отображаемый в пустом поле (когда файлы ещё не выбраны).
prependIcon	IconValue | undefined	'upload'	Иконка в слоте prepend перед контентом
prependInnerIcon	IconValue | undefined	—	Иконка во внутреннем слоте prepend перед содержимым поля
readonly	boolean | null | undefined	null	Только для чтения
reverse	boolean | undefined	—	Обратный порядок расположения элементов внутри поля
rules	readonly ValidationRule[] | undefined	[]	Принимает массив, состоящий из элементов различных типов: функций, логических значений и строк. Функции принимают входное значение в качестве аргумента и должны возвращать либо true / false, либо строку, содержащую сообщение об ошибке. Поле ввода перейдет в состояние ошибки, если функция возвращает значение false (или любое значение в массиве содержит false) либо является строкой.
showSize	boolean | 1000 | 1024 | undefined	false	Отображать размер выбранных файлов. Булево значение или основание счисления: 1000 (kB) или 1024 (KiB).
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Размер компонента
textColor	string | undefined	—	Цвет текста компонента
theme	string | undefined	—	Тема компонента
truncateLength	string | number | undefined	22	Максимальная длина имени файла до усечения (символы в начале и конце сохраняются).
validateOn	ValidateOn | undefined	—	Изменяет тип события, при котором запускается валидация
validationValue	any	—	Значение, используемое при применении правил валидации
width	string | number | undefined	—	Ширина компонента

События

Имя	Тип	Описание
click:control	[e: MouseEvent]	Событие, возникающее при клике в основной области контрола.
mousedown:control	[e: MouseEvent]	Событие, которое срабатывает при нажатии кнопки мыши в основной области контрола.
rejected	[files: File[]]	Событие, которое срабатывает, когда часть файлов отклонена фильтром filterByType.
update:focused	[focused: boolean]	Вызывается при переходе фокуса на элемент или при его потере.
update:modelValue	[value: File | File[]]	Событие, которое срабатывает при изменении списка выбранных файлов.

Слоты

Имя	Тип	Описание
append	CdsInputSlot	Добавляет элемент после поля ввода
append-inner	CdsInputDefaultSlot	Слот, добавляемый в конце инпута ввода
clear	CdsInputDefaultSlot & { props: Record<string, any>; }	Слот для пользовательского иконки очистки (отображается, когда свойство clearable имеет значение «true»).
counter	CdsCounterSlot	Слот для ввода пользовательского счётчика.
description	{ description: string | undefined; props: Record<string, any>; }	Слот по умолчанию для компонента CdsDescription
details	CdsInputSlot	Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
label	{ label: string | undefined; props: Record<string, any>; }	Слот по умолчанию для компонента CdsLabel
loader	LoaderSlotProps	Слот для пользовательского загрузчика (отображается, если свойство loading имеет значение true).
message	CdsMessageSlot	Слот для настройки содержания сообщения
messages	CdsInputSlot	Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
prepend	CdsInputSlot	Добавляет элемент до поля ввода
prepend-inner	CdsInputDefaultSlot	Слот, добавляемый в начало инпута ввода
selection	CdsFileInputSelectionSlot	Слот для кастомного отображения выбранных файлов.

Exposed

Имя	Тип	Описание
controlRef	HTMLElement | undefined	Ref-ссылка на контролл поля ввода
fieldIconColor	string | undefined	Цвет иконки
isDirty	boolean	Является ли поле ввода "грязным"
isDisabled	boolean	Является ли поле ввода заблокированным
isPure	boolean	Является ли поле ввода "чистым"
isReadonly	boolean	Является ли поле ввода только для чтения
isValid	boolean | null	Является ли поле ввода валидным
isValidating	boolean	Является ли поле ввода в процессе валидации
reset	() => Promise<void>	Функция сброса поля ввода в исходное состояние
resetValidation	() => Promise<void>	Функция сброса валидации поля ввода
validate	(silent?: boolean) => Promise<string[]>	Функция валидации поля ввода