FileUploaderItem

FileUploaderItem — это компонент библиотеки Carbon Components Svelte, предназначенный для отображения отдельных элементов в списке загружаемых файлов. Он используется совместно с FileUploader, обеспечивая визуальное представление каждого файла, который пользователь выбрал для загрузки. Компонент предоставляет возможность отображать имя файла, его размер, статус загрузки и действия для удаления или отмены загрузки.

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

Компонент FileUploaderItem обладает набором свойств, позволяющих гибко управлять отображением и поведением элемента:

  • name (string, обязательное) — имя файла, которое будет отображаться в интерфейсе.

  • size (number, необязательное) — размер файла в байтах. Для удобства отображения часто конвертируется в килобайты или мегабайты.

  • status (string, необязательное) — текущий статус файла. Возможные значения:

    • "edit" — файл готов к загрузке, пользователь может его удалить.
    • "uploading" — файл загружается, отображается индикатор прогресса.
    • "complete" — загрузка файла завершена успешно.
    • "error" — произошла ошибка при загрузке.

  • invalid (boolean, необязательное) — указывает, что файл не прошёл валидацию (например, превышен размер или неподдерживаемый формат).

  • errorSubject (string, необязательное) — заголовок ошибки, отображаемый при invalid=true.

  • errorBody (string, необязательное) — подробное описание ошибки.

  • iconDescription (string, необязательное) — текстовое описание иконки, используемой для действий, например, для кнопки удаления файла.

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

<FileUploaderItem
  name="report.pdf"
  size={1048576}
  status="uploading"
  iconDescription="Удалить файл"
/>

События

Компонент поддерживает несколько событий, которые позволяют отслеживать действия пользователя и изменения состояния файла:

  • on:click — срабатывает при клике на элемент, можно использовать для выбора или открытия файла.
  • on:delete — вызывается при нажатии на кнопку удаления. В обработчике можно удалить файл из списка.
  • on:error — срабатывает, когда файл становится недопустимым. Позволяет отобразить уведомление или логировать ошибку.

Пример обработки событий:

<FileUploaderItem
  name="image.png"
  on:delete={() => removeFile('image.png')}
  on:error={(e) => console.error('Ошибка загрузки:', e.detail)}
/>

Индикатор прогресса и статус

Для визуализации состояния загрузки используется комбинация свойства status и встроенного индикатора прогресса:

  • uploading — отображает анимацию загрузки и индикатор прогресса.
  • complete — показывает галочку или соответствующую иконку успешной загрузки.
  • error / invalid — активирует визуальную подсветку ошибки и отображает сообщение errorSubject и errorBody.

Пример отображения индикатора прогресса:

<FileUploaderItem
  name="video.mp4"
  size={52428800}
  status="uploading"
/>

Для динамического изменения прогресса можно использовать реактивные переменные Svelte:

<script>
  let progress = 0;
  const interval = setInterval(() => {
    if (progress < 100) progress += 10;
  }, 500);
</script>

<FileUploaderItem
  name="presentation.pptx"
  size={10485760}
  status="uploading"
/>

Валидация и ошибки

FileUploaderItem тесно интегрирован с системой валидации FileUploader. Свойство invalid позволяет пометить файл как недопустимый, а errorSubject и errorBody дают возможность информировать пользователя о проблеме:

<FileUploaderItem
  name="large_file.zip"
  size={1073741824}
  invalid={true}
  errorSubject="Файл слишком большой"
  errorBody="Максимальный размер файла — 100 МБ"
/>

Элементы с invalid=true автоматически получают визуальную подсветку ошибки и кнопку для удаления.

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

  • Иконки и текст можно менять через слоты и свойства, обеспечивая соответствие дизайн-системе проекта.
  • Стилизация через CSS: компоненты Carbon имеют стандартные классы, которые можно расширять для изменения отступов, цвета текста и иконок.
  • Слоты позволяют вставлять дополнительные элементы, например, метки с дополнительной информацией о файле или кнопки действий.

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

<FileUploaderItem name="document.docx" status="complete">
  <div slot="footer">Загружено 1 из 1</div>
</FileUploaderItem>

Практические советы

  • Всегда указывать уникальное имя файла в name, чтобы корректно обрабатывать удаление и события.
  • Использовать status для отображения состояния загрузки вместо ручного управления классами, это снижает количество ошибок.
  • Для больших списков файлов стоит использовать массив объектов и #each Svelte, создавая FileUploaderItem динамически.
  • Для улучшения UX добавлять прогрессбар или сообщение о завершении загрузки.

Пример динамического списка:

<script>
  let files = [
    { name: "file1.txt", size: 1024, status: "complete" },
    { name: "file2.jpg", size: 2048000, status: "uploading" }
  ];

  function removeFile(fileName) {
    files = files.filter(f => f.name !== fileName);
  }
</script>

{#each files as file (file.name)}
  <FileUploaderItem
    name={file.name}
    size={file.size}
    status={file.status}
    on:delete={() => removeFile(file.name)}
  />
{/each}

FileUploaderItem является ключевым инструментом при работе с загрузкой файлов в Carbon Components Svelte, обеспечивая визуальную информативность и управление файлами на клиентской стороне. Его гибкость позволяет создавать как простые, так и комплексные интерфейсы загрузки, полностью интегрированные с остальной библиотекой компонентов.

Оглавление