SUpload

Загрузка файла. Всегда вставляется внутри некой формы, не используется в отрыве от неё.

В чем отличие от аналогов?

В отличие от популярных библиотек компонентов для Vue3:

1. В других библиотеках Upload работает как поле, которое по дефолту сразу отправляет файл после выбора (что удобно, например, при импорте таблиц). На практике же гораздо чаще встречается кейс, когда файл/картинка — это атрибут некой модели, и этот файл нужно добавлять-редактировать в форме редактирования модели. SUpload в первую очередь заточен под этот, более частый кейс.
2. SUpload сразу работает в связке с SForm, что позволяет использовать его так же просто, как простые текстовые SInput, не задумываясь о том, как связывать данные с формой.

Базовый пример

Если нужно вставить полем в форму. Сама отправка идёт через Inertia, поэтому базовый пример показан кодом (вживую не запускается):

<SUpload v-model="screenshot" />
<SButton v-if="screenshot" @click="submit">Отправить</SButton>

<template>
    <SUpload v-model="screenshot" />
    <SButton v-if="screenshot" @click="submit">Отправить</SButton>
</template>

<script setup>
import { ref } from 'vue';
import { router } from '@inertiajs/vue3';
import { SUpload, SButton, SAlert } from 'startup-ui';

const screenshot = ref(null);

function submit() {
    router.post('/photos', { screenshot: screenshot.value }, {
        preserveState: true,
        onError: (errors) => console.error(errors),
        onSuccess: () => SAlert.success('Файл отправлен'),
    });
}
</script>

Авто-отправка при выборе

Если нужна авто-отправка, то выполняем отправку формы по событию @select:

Выбрать файл

<SUpload v-model="screenshot" @select="submit" />

<template>
    <SUpload v-model="screenshot" @select="submit" />
</template>
<script setup>
import { ref } from 'vue'
import { SAlert } from 'startup-ui'
const screenshot = ref(null)
// в реальном приложении здесь router.post(...) (Inertia)
function submit() {
    SAlert.success('Файл отправлен')
}
</script>

Кастомный текст кнопки

Можно задать произвольный текст кнопки с помощью атрибута upload-button-title

Выбрать скриншот

<SUpload v-model="screenshot" upload-button-title="Выбрать скриншот" />

<template>
    <SUpload v-model="screenshot" upload-button-title="Выбрать скриншот" />
</template>
<script setup>
import { ref } from 'vue'
const screenshot = ref(null)
</script>

Кастомный шаблон

Перетащите файл сюда или нажмите для загрузки

<SUpload v-model="screenshot">
    <template #header="{ choose, clear, files, isDragging }">
        <div class="s-upload-area" :class="{ dragging: isDragging }">
            <FontAwesomeIcon icon="cloud-arrow-up" class="s-upload-area-icon" />
            <p>Перетащите файл сюда или <a href="javascript:void(0)" @click="choose">нажмите</a> для загрузки</p>
        </div>
    </template>
    <template #preview="{ files, remove }">
        <div v-if="files && files.length">
            Файл выбран <SActionIcon @click="remove(files[0])" icon="trash" />
        </div>
    </template>
</SUpload>

<template>
    <SUpload v-model="screenshot">
        <template #header="{ choose, clear, files, isDragging }">
            <div class="s-upload-area" :class="{ dragging: isDragging }">
                <FontAwesomeIcon icon="cloud-arrow-up" class="s-upload-area-icon" />
                <p>Перетащите файл сюда или <a href="javascript:void(0)" @click="choose">нажмите</a> для загрузки</p>
            </div>
        </template>
        <template #preview="{ files, remove }">
            <div v-if="files && files.length">
                Файл выбран <SActionIcon @click="remove(files[0])" icon="trash" />
            </div>
        </template>
    </SUpload>
</template>
<script setup>
import { ref } from 'vue'
const screenshot = ref(null)
</script>

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

• В слоте кнопки выбора #header: choose() открывает окно выбора файла, clear() очищает набор выбранных файлов, files — список текущих выбранных файлов, isDragging — булево значение, равное true, когда над компонентом перемещают файл.
• В слоте предпросмотра выбранных файлов #preview: files — список текущих выбранных файлов, remove(file) — удаление конкретного файла из набора (передаётся элемент массива files).

Ограничения выбора

Для ограничения выбора по расширению добавляем атрибут accept:

Выбрать файл

<SUpload v-model="screenshot" accept=".txt,.csv,.xlsx" />

<template>
    <SUpload v-model="screenshot" accept=".txt,.csv,.xlsx" />
</template>
<script setup>
import { ref } from 'vue'
const screenshot = ref(null)
</script>

Для ограничения выбора по размеру файла добавляем атрибут max-file-size. Можно указывать человекочитаемо (2M, 512K, 1.5GB — единицы 1024-кратные, как в php.ini) или числом в байтах:

Выбрать файл

<SUpload v-model="screenshot" max-file-size="500K" />

<template>
    <SUpload v-model="screenshot" max-file-size="500K" />
</template>
<script setup>
import { ref } from 'vue'
const screenshot = ref(null)
</script>

Выбор нескольких файлов

Выбрать файлы

<SUpload v-model="screenshots" multiple />

<template>
    <SUpload v-model="screenshots" multiple />
</template>
<script setup>
import { ref } from 'vue'
const screenshots = ref([])
</script>

Интерфейс компонента

Свойства (Props)

Название	Тип	По умолчанию	Описание
v-model	any | any[]	null	Выбранный файл (объект File или строка) или массив файлов.
accept	string	undefined	Допустимые типы файлов (напр. .jpg,.png).
max-file-size	number | string	undefined	Максимальный размер файла: в байтах (число) или человекочитаемо (2M, 512K, 1.5GB).
multiple	boolean	false	Позволяет выбирать несколько файлов.
upload-button-title	string	'Выбрать файл(ы)'	Текст на кнопке выбора (если не используется слот header).

Слоты (Slots)

Название	Параметры	Описание
header	{ choose, clear, files, isDragging }	Кастомная область выбора (триггер).
preview	{ files, remove }	Кастомная область предпросмотра выбранных файлов.
default	-	Содержимое под списком файлов.

События (Events)

Название	Параметры	Описание
select	value	Вызывается при выборе файлов.
clear	-	Вызывается при полной очистке списка.