Перейти к содержимому
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.