re:re:actable
Урок 094 минуты чтения

Как загружать файлы через форму

На этой странице
Кратко

Файл выбирается через <input type="file"> — это всегда неуправляемое поле: значение нельзя задать через value, файлы читают из input.files или FormData. Отправляют файлы как multipart/form-data через FormData (заголовок Content-Type браузер выставит сам) или напрямую в объектное хранилище по presigned URL. На клиенте проверяют тип и размер, показывают превью (URL.createObjectURL) и прогресс, но окончательную проверку делает сервер.

Вопрос

Как загрузить файл через форму в React? Как показать превью, ограничить тип и размер, отобразить прогресс и почему проверку нужно повторить на сервере?

Базовый вариант

const MAX_SIZE = 5 * 1024 * 1024; // 5 МБ
const ACCEPT = ["image/jpeg", "image/png", "image/webp"];
 
export function AvatarUpload() {
  const [file, setFile] = useState<File | null>(null);
  const [preview, setPreview] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [status, setStatus] = useState<"idle" | "uploading" | "done">("idle");
 
  useEffect(() => {
    if (!file) return;
    const url = URL.createObjectURL(file);
    setPreview(url);
    return () => URL.revokeObjectURL(url);           // освободить память
  }, [file]);
 
  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
    const selected = e.target.files?.[0];
    setError(null);
    if (!selected) return;
    if (!ACCEPT.includes(selected.type)) return setError("Только JPG, PNG или WebP");
    if (selected.size > MAX_SIZE) return setError("Файл больше 5 МБ");
    setFile(selected);
  }
 
  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!file) return;
    const body = new FormData();
    body.append("avatar", file);
    setStatus("uploading");
    const res = await fetch("/api/avatar", { method: "POST", body }); // Content-Type не указываем!
    setStatus(res.ok ? "done" : "idle");
    if (!res.ok) setError("Не удалось загрузить файл");
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="avatar">Фото профиля</label>
      <input id="avatar" type="file" accept={ACCEPT.join(",")} onChange={handleChange} aria-describedby="avatar-hint" />
      <p id="avatar-hint">JPG, PNG или WebP до 5 МБ</p>
      {preview && <img src={preview} alt="Превью выбранного фото" width={96} height={96} />}
      {error && <p role="alert">{error}</p>}
      <button disabled={!file || status === "uploading"}>
        {status === "uploading" ? "Загрузка…" : "Загрузить"}
      </button>
    </form>
  );
}

Если вручную поставить Content-Type: multipart/form-data, пропадет boundary, и сервер не разберет тело.

С react-hook-form

const schema = z.object({
  files: z
    .custom<FileList>()
    .refine((list) => list?.length > 0, "Выберите файл")
    .refine((list) => Array.from(list ?? []).every((f) => f.size <= MAX_SIZE), "Каждый файл до 5 МБ"),
});
 
<input type="file" multiple {...register("files")} />
// в onSubmit: data.files — FileList

register подходит, потому что поле неуправляемое; defaultValues для файлов не задают.

Прогресс загрузки

fetch не сообщает прогресс отправки, поэтому используют XMLHttpRequest (или axios с onUploadProgress):

function upload(url: string, body: FormData, onProgress: (p: number) => void) {
  return new Promise<void>((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open("POST", url);
    xhr.upload.onprogress = (e) => e.lengthComputable && onProgress(Math.round((e.loaded / e.total) * 100));
    xhr.onload = () => (xhr.status < 400 ? resolve() : reject(new Error(String(xhr.status))));
    xhr.onerror = () => reject(new Error("network"));
    xhr.send(body);
  });
}
<progress value={progress} max={100}>{progress}%</progress>

Загрузка напрямую в хранилище

1. Клиент → сервер: «хочу загрузить avatar.png, 2 МБ»
2. Сервер проверяет права, тип, размер → возвращает presigned URL (S3, R2, GCS)
3. Клиент → PUT файла прямо в хранилище по presigned URL
4. Клиент → сервер: «загрузка завершена, ключ такой-то»

Файл не проходит через ваш сервер — меньше нагрузка и ограничений на размер тела запроса.

Drag and drop

<div
  onDragOver={(e) => e.preventDefault()}
  onDrop={(e) => { e.preventDefault(); handleFiles(e.dataTransfer.files); }}
>
  Перетащите файл или <label htmlFor="file">выберите на компьютере</label>
  <input id="file" type="file" className="visually-hidden" />
</div>

Зона перетаскивания не заменяет обычный input: с клавиатуры и на мобильных выбирают через кнопку. Готовые решения — react-dropzone.

Что важно помнить

  • accept и проверка file.type на клиенте — подсказка: тип можно подделать. Сервер проверяет содержимое (magic bytes), размер и права доступа.
  • Не доверяйте имени файла: на сервере генерируйте свое имя, иначе возможен path traversal.
  • Вызывайте URL.revokeObjectURL, иначе превью держат память.
  • Сбросить выбранный файл можно только через input.value = "" или новый key у поля.
  • Большие файлы загружают частями (multipart upload, tus) с возможностью продолжить после обрыва.

Мини-шпаргалка

<input type="file" accept multiple> — неуправляемое поле, файлы в e.target.files. Отправка — FormData без ручного Content-Type. Превью — URL.createObjectURL + revokeObjectURL. Прогресс — xhr.upload.onprogress. Большие файлы — presigned URL в хранилище. Проверки типа и размера — на клиенте и обязательно на сервере.

Документация

MDN: input type="file", MDN: Using FormData Objects, MDN: URL.createObjectURL(), OWASP: File Upload Cheat Sheet.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам