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