Как загружать файлы через форму
На этой странице
Файл выбирается через <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 — FileListregister подходит, потому что поле неуправляемое; 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.