<input type="file"> значение атрибута HTML

Элементы <input> с атрибутом type="file" позволяют пользователю выбрать один или несколько файлов из хранилища устройства. Выбранные файлы можно загрузить на сервер с помощью отправки формы или обработать с помощью кода JavaScript и File API.

Попробуйте

<label for="avatar">Choose a profile picture:</label>

<input type="file" id="avatar" name="avatar" accept="image/png, image/jpeg" />

label {
  display: block;
  font:
    1rem "Fira Sans",
    sans-serif;
}

input,
label {
  margin: 0.4rem 0;
}

Значение

Атрибут value поля выбора файла содержит строку, представляющую путь к выбранному файлу или файлам. Если файл ещё не выбран, значение представляет собой пустую строку (""). Если пользователь выбрал несколько файлов, value представляет первый файл из списка выбранных файлов. Остальные файлы можно получить с помощью свойства HTMLInputElement.files элемента input.

Дополнительные атрибуты

Помимо общих атрибутов, доступных всем элементам <input>, для полей ввода типа file также поддерживаются следующие атрибуты.

accept

Значение атрибута accept — это строка, определяющая типы файлов, которые может принимать поле выбора файла. Эта строка представляет собой список уникальных спецификаторов типов файлов, разделённых запятыми. Поскольку тип файла может быть определён несколькими способами, если вам нужны файлы определённого формата, полезно указать полный набор спецификаторов типа.

Например, файлы Microsoft Word можно определить несколькими способами, поэтому сайт, принимающий файлы Word, может использовать такой <input>:

<input
  type="file"
  id="docpicker"
  accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" />

capture

Значение атрибута capture — это строка, указывающая, какую камеру использовать для захвата изображений или видео, если атрибут accept указывает, что поле ввода должно принимать файлы одного из этих типов. Значение user указывает, что следует использовать фронтальную камеру и/или микрофон. Значение environment указывает, что следует использовать основную камеру и/или микрофон. Если этот атрибут не указан, пользовательский агент может самостоятельно решить, что делать. Если запрошенный режим камеры недоступен, пользовательский агент может использовать предпочитаемый режим по умолчанию.

multiple

Если указан логический атрибут multiple, поле выбора файла позволяет пользователю выбрать несколько файлов.

Нестандартные атрибуты

Помимо перечисленных выше атрибутов, в некоторых браузерах доступны следующие нестандартные атрибуты. По возможности старайтесь не использовать их, так как это ограничит работу вашего кода в браузерах, которые их не поддерживают.

webkitdirectory

Логический атрибут webkitdirectory при наличии указывает, что в интерфейсе выбора файлов пользователь может выбирать только каталоги. Дополнительные сведения и примеры см. в разделе HTMLInputElement.webkitdirectory.

Уникальные спецификаторы типов файлов

Уникальный спецификатор типа файла — это строка, описывающая тип файла, который пользователь может выбрать в элементе <input> типа file. Каждый уникальный спецификатор типа файла может иметь одну из следующих форм:

• Допустимое расширение имени файла без учёта регистра, начинающееся с точки ("."). Например: .jpg, .pdf или .doc.
• Допустимая строка MIME-типа без расширений.
• Строка audio/*, означающая «любой аудиофайл».
• Строка video/*, означающая «любой видеофайл».
• Строка image/*, означающая «любой файл изображения».

Атрибут accept принимает в качестве значения строку с одним или несколькими уникальными спецификаторами типов файлов, разделёнными запятыми. Например, поле выбора файлов для содержимого, которое можно представить в виде изображения, включая стандартные форматы изображений и файлы PDF, может выглядеть так:

<input type="file" accept="image/*,.pdf" />

Использование полей выбора файлов

Простой пример

<form method="post" enctype="multipart/form-data">
  <div>
    <label for="file">Choose file to upload</label>
    <input type="file" id="file" name="file" multiple />
  </div>
  <div>
    <button>Submit</button>
  </div>
</form>

В результате будет получен следующий вывод:

Независимо от устройства или операционной системы пользователя, поле выбора файла отображает кнопку, открывающую диалоговое окно выбора файла, в котором пользователь может выбрать файл.

Как показано выше, атрибут multiple позволяет выбрать несколько файлов одновременно. Пользователь может выбрать несколько файлов любым способом, который поддерживает выбранная им платформа (например, удерживая клавишу Shift или Control и щёлкая по файлам). Если вы хотите, чтобы пользователь мог выбирать только один файл за раз в каждом <input>, не указывайте атрибут multiple.

Получение информации о выбранных файлах

Выбранные файлы доступны через свойство HTMLInputElement.files элемента. Это объект FileList, содержащий список объектов File. Объект FileList ведёт себя как массив, поэтому можно проверить его свойство length, чтобы узнать количество выбранных файлов.

Каждый объект File содержит следующую информацию:

name

Имя файла.

lastModified

Число, указывающее дату и время последнего изменения файла в миллисекундах, прошедших с начала эпохи UNIX (полночь 1 января 1970 года).

lastModifiedDate

Объект Date, представляющий дату и время последнего изменения файла. Это свойство устарело, и его не следует использовать. Вместо него используйте lastModified.

size

Размер файла в байтах.

type

MIME-тип файла.

webkitRelativePath

Строка, указывающая путь к файлу относительно базового каталога, выбранного в окне выбора каталога (то есть в окне выбора file, в котором установлен атрибут webkitdirectory). Это нестандартное свойство, и использовать его следует с осторожностью.

Ограничение допустимых типов файлов

Часто нежелательно позволять пользователю выбирать файлы любого типа; вместо этого обычно требуется, чтобы он выбирал файлы одного или нескольких определённых типов. Например, если поле выбора файла позволяет пользователям загружать фотографию профиля, вероятно, следует разрешить выбирать изображения в форматах, совместимых с вебом, например JPEG или PNG.

Допустимые типы файлов можно указать с помощью атрибута accept, принимающего разделённый запятыми список разрешённых расширений файлов или MIME-типов. Например:

• accept="image/png" или accept=".png" — принимает файлы PNG.
• accept="image/png, image/jpeg" или accept=".png, .jpg, .jpeg" — принимает файлы PNG или JPEG.
• accept="image/*" — принимает любые файлы с MIME-типом image/*. (На многих мобильных устройствах при этом также можно сделать снимок камерой.)
• accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" — принимает всё, что похоже на документ MS Word.

Рассмотрим более полный пример:

<form method="post" enctype="multipart/form-data">
  <div>
    <label for="profile_pic">Choose file to upload</label>
    <input
      type="file"
      id="profile_pic"
      name="profile_pic"
      accept=".jpg, .jpeg, .png" />
  </div>
  <div>
    <button>Submit</button>
  </div>
</form>

В результате получится вывод, похожий на предыдущий пример:

Внешне поле выглядит так же, но если попробовать выбрать файл, вы увидите, что окно выбора файлов позволяет выбирать только типы файлов, указанные в значении accept (точный интерфейс различается в разных браузерах и операционных системах).

Атрибут accept не проверяет типы выбранных файлов; он лишь подсказывает браузерам, какие типы файлов следует выбирать. В большинстве случаев пользователи всё ещё могут изменить настройку в окне выбора файлов, чтобы выбрать любой файл, в том числе неподходящего типа.

Поэтому необходимо обеспечить соответствующую серверную проверку в дополнение к атрибуту accept.

Обнаружение отмены

Событие cancel срабатывает, если пользователь не меняет выбор, повторно выбирая ранее выбранные файлы. Событие cancel также срабатывает при закрытии или отмене диалогового окна выбора файлов с помощью кнопки «Отмена» или клавиши escape.

Например, следующий код выведет сообщение в консоль, если пользователь закроет всплывающее окно, не выбрав файл:

const elem = document.createElement("input");
elem.type = "file";
elem.addEventListener("cancel", () => {
  console.log("Cancelled.");
});
elem.addEventListener("change", () => {
  if (elem.files.length === 1) {
    console.log("File selected: ", elem.files[0]);
  }
});
elem.click();

Примечания

1. Нельзя задать значение поля выбора файла из скрипта — следующий код не даст никакого результата:

   const input = document.querySelector("input[type=file]");
   input.value = "foo";
   

2. При выборе файла с помощью <input type="file"> настоящий путь к исходному файлу по очевидным соображениям безопасности не отображается в атрибуте value поля ввода. Вместо этого отображается имя файла с префиксом C:\fakepath\. Это поведение обусловлено историческими причинами, но поддерживается во всех современных браузерах и даже определено в спецификации.

Примеры

В этом примере мы создадим более продвинутое поле выбора файлов, используя сведения о файлах, доступные через свойство HTMLInputElement.files, и покажем несколько полезных приёмов.

Сначала рассмотрим HTML:

<form method="post" enctype="multipart/form-data">
  <div>
    <label for="image_uploads">Choose images to upload (PNG, JPG)</label>
    <input
      type="file"
      id="image_uploads"
      name="image_uploads"
      accept=".jpg, .jpeg, .png"
      multiple />
  </div>
  <div class="preview">
    <p>No files currently selected for upload</p>
  </div>
  <div>
    <button>Submit</button>
  </div>
</form>

Это похоже на то, что мы уже видели, — здесь нет ничего особенного, что требовало бы пояснений.

Теперь разберём JavaScript.

В первых строках скрипта мы получаем ссылки на само поле ввода формы и элемент <div> с классом .preview. Затем мы скрываем элемент <input>: поля выбора файлов обычно выглядят непривлекательно, их сложно стилизовать, а их оформление различается в разных браузерах. Активировать элемент input можно, нажав на его <label>, поэтому лучше визуально скрыть input и стилизовать метку как кнопку, чтобы пользователю было понятно, что с ней нужно взаимодействовать для загрузки файлов.

const input = document.querySelector("input");
const preview = document.querySelector(".preview");

input.style.opacity = 0;

Затем мы добавляем к полю ввода обработчик событий, который отслеживает изменения выбранного значения (в данном случае — выбор файлов). Обработчик вызывает нашу пользовательскую функцию updateImageDisplay().

input.addEventListener("change", updateImageDisplay);

При каждом вызове функции updateImageDisplay() мы выполняем следующие действия:

• Используем цикл while, чтобы удалить предыдущее содержимое области предварительного просмотра <div>.

• Получаем объект FileList, содержащий сведения обо всех выбранных файлах, и сохраняем его в переменной curFiles.

• Проверяем, не выбраны ли файлы: для этого проверяем, равно ли curFiles.length нулю. Если да, выводим в область предварительного просмотра <div> сообщение о том, что файлы не выбраны.

• Если файлы выбраны, перебираем каждый из них и выводим сведения о нём в область предварительного просмотра <div>. Обратите внимание на следующее:

• Мы используем пользовательскую функцию validFileType(), чтобы проверить, имеет ли файл допустимый тип (например, относится ли он к типам изображений, указанным в атрибуте accept).

• Если да, мы:

  • Выводим имя и размер файла в элемент списка внутри предыдущего <div> (полученные из file.name и file.size). Пользовательская функция returnFileSize() возвращает размер в удобном формате: байты/КБ/МБ (по умолчанию браузер сообщает размер в абсолютных байтах).
  • Создаём миниатюру изображения с помощью вызова URL.createObjectURL(file). Затем добавляем изображение в элемент списка: создаём новый элемент <img> и присваиваем его свойству src миниатюру.

• Если тип файла недопустим, выводим в элементе списка сообщение о том, что пользователю нужно выбрать файл другого типа.

function updateImageDisplay() {
  while (preview.firstChild) {
    preview.removeChild(preview.firstChild);
  }

  const curFiles = input.files;
  if (curFiles.length === 0) {
    const para = document.createElement("p");
    para.textContent = "No files currently selected for upload";
    preview.appendChild(para);
  } else {
    const list = document.createElement("ol");
    preview.appendChild(list);

    for (const file of curFiles) {
      const listItem = document.createElement("li");
      const para = document.createElement("p");
      if (validFileType(file)) {
        para.textContent = `File name ${file.name}, file size ${returnFileSize(
          file.size,
        )}.`;
        const image = document.createElement("img");
        image.src = URL.createObjectURL(file);
        image.alt = image.title = file.name;

        listItem.appendChild(image);
        listItem.appendChild(para);
      } else {
        para.textContent = `File name ${file.name}: Not a valid file type. Update your selection.`;
        listItem.appendChild(para);
      }

      list.appendChild(listItem);
    }
  }
}

Пользовательская функция validFileType() принимает в качестве параметра объект File, а затем использует Array.prototype.includes(), чтобы проверить, совпадает ли какое-либо значение в fileTypes со свойством type файла. Если совпадение найдено, функция возвращает true. Если совпадений нет, она возвращает false.

// https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Formats/Image_types
const fileTypes = [
  "image/apng",
  "image/bmp",
  "image/gif",
  "image/jpeg",
  "image/pjpeg",
  "image/png",
  "image/svg+xml",
  "image/tiff",
  "image/webp",
  "image/x-icon",
];

function validFileType(file) {
  return fileTypes.includes(file.type);
}

Функция returnFileSize() принимает число (количество байтов, полученное из свойства size текущего файла) и преобразует его в размер в удобном формате: байты/КБ/МБ.

function returnFileSize(number) {
  if (number < 1e3) {
    return `${number} bytes`;
  } else if (number >= 1e3 && number < 1e6) {
    return `${(number / 1e3).toFixed(1)} KB`;
  }
  return `${(number / 1e6).toFixed(1)} MB`;
}

Пример выглядит так; попробуйте его:

Техническая сводка

Спецификации

Совместимость с браузерами

См. также

• Использование файлов в веб-приложениях — содержит ряд других полезных примеров, связанных с <input type="file"> и File API.