Перейти до вмісту
Leonidov.DEV

Завантаження файла у форму: 5 правил віджета

Інженерія
Завантаження файла у форму: 5 правил віджета

Кожен аудит форми впирається в одне поле. У макеті намальований пунктирний прямокутник, скріпка й гарний список, у коді стоїть сіра кнопка «Вибрати файл», і далі починається суперечка про те, який варіант «справжній». Завантаження файла у форму це місце, де дизайн і платформа розходяться найсильніше, і найдешевше лишити платформу й одягнути її.

Код: Oat-Upload, ліцензія MIT.

Я зібрав віджет як розширення Oat UI, а не як окрему бібліотеку, і його поведінку задали п’ять правил. Кожне прийшло із звернення в підтримку, яке я бачив у чужому коді.

Правило 1: нативний input це контракт

<input type="file"> несе name, accept, multiple і disabled, і браузер перевіряє їх до того, як запуститься скрипт. Віджет, який ховає поле й надсилає масив із JavaScript, ламає контракт у момент, коли скрипт не завантажився.

Тому <ot-upload> обгортає поле й лишає його у формі:

<ot-upload max-size="5242880" max-files="5">
  <input type="file" name="attachments" multiple accept="image/*,.pdf">
</ot-upload>

Сервер бачить те саме поле, що й до редизайну. У запиті нічого не змінилося, і це моя перевірка для будь-якого компонента: вимкніть скрипт, форма мусить надіслатися.

Правило 2: спершу перевіряє браузер, потім мої ліміти

accept і multiple належать платформі, і віджет читає їх звідти. Розмір і кількість файлів наші, бо для звичайного поля файла їх не тримає жоден браузер.

Порядок важливий на рев’ю. Компонент, який перевіряє accept власним списком типів, відхиляє те, що браузер приймає, і далі помилка проявляється як файл, який завантажується на одній машині й не завантажується на іншій.

Правило 3: відхилений файл не стирає вибір

Найдорожчий промах у цьому віджеті це скидання поля при помилці. Людина прикріплює вісім сканів, дев’ятий більший за ліміт, і все зникає. Вона вважає, що форма зламалася, а в підтримку приходить скриншот.

Тут відхилений файл іде в ot-upload-error і не потрапляє до списку. Вісім прийнятих лишаються, повідомлення називає причину, дев’ятий можна замінити. reason приймає значення type, size, count або disabled, тому текст виходить конкретним, а не «неприпустимий файл».

Правило 4: число прогресу належить мережі

setProgress() приймає число від 0 до 100 і пише його в нативний <progress>. Віджет нічого не анімує й не оцінює.

Таймер, який вдає, що завантажує, це брехня, яку людина бачить: смуга доходить до кінця, сторінка стоїть. Справжнє число з коду запиту чесне, включно з моментом, коли воно перестало рухатися через зв’язок.

Правило 5: видалення файла це частина форми

remove() приймає файл, індекс або ідентифікатор елемента, і там, де є DataTransfer, віджет записує решту файлів назад у поле. Без цього список на екрані й дані в запиті розходяться, і сервер отримує файл, який людина видалила.

Одна ця деталь варта більше за будь-яке візуальне полірування: прев’ю й запит це один стан.

Чого віджет не робить

Він не завантажує. У пакеті немає ендпоінта, токена й політики повторів. Передавання шматками, підписи для S3 і перевірка на віруси належать застосунку, а компонент, який береться їх вгадувати, перетворюється на фреймворк, якого ніхто не просив.

Він також не лишає тільки перетягування. <label for="files"> відкриває вибір по кліку й по Enter, тому зона перетягування лишається покращенням поверх працюючого елемента.

Чого це вчить у компонентах

Писати компонент менше за задачу. П’ять правил вище це все про те, щоб не забирати відповідальність у браузера, і тому пакет лишається однією таблицею стилів і одним скриптом без залежностей у рантаймі.

Той самий довід проходить через прогресивне покращення: сторінка з робочим станом до скрипта простіша в перевірці й дешевша в підтримці. Про те саме я кажу в замітці створення фреймворку про ядро на 2 МБ замість повного стека.

Oat Upload виходить під MIT і ставиться з npm як @globus.studio/oat-upload.