FileAPI

В этой статье я расскажу о такой чудо-штуке HTML5 как FileAPI. Для тех, кто не в курсе: это расширение возможностей JS в сторону работы с файлами. Теперь можно определять не только имена файлов, но и их MIME тип, размер, а самое главное — содержимое! Тут будет много теории, но на десерт я приготовил кое-что вкусненькое: Drag and Drop file uploader на чистом JS с прогрессбаром!

Кроссбраузерность

К сожалению, прогресс идет неравномерно, поэтому далеко не все браузеры уже успели реализовать этот API. Впереди планеты всей - Firefox и Chrome (на момент написания статьи). Так же поддержка FileAPI появилась в Опере 11.10.

C чего все начинается?

Все начинается с давно известного нам тега input с атрибутом type="file". Теперь у него есть свойство files, который представляет себе массив (экземпляр класса FileList, если точнее) файлов — объектов класса File. Каждый такой объект может похвастаться наличием следующих свойств (унаследованных от класса Blob):

• name — имя файла
• type — MIME тип файла (если удалось определить).
• size — размер в байтах.

В FF 3.6 есть еще такие методы и свойства:

• fileName — синоним для name.
• fileSize — синоним для size.
• getAsText — получить содержимое файла, рассматривая его как текстовый.
• getAsDataURL — получить файл в формате Data:URL.
• getAsBinary — чтение файла в бинарном режиме. Возвращает строку.

Эти свойства и методы не упомянуты в официальной спецификации и самими разработчиками FF объявлены как deprecated. Т.е. их использование нежелательно.
В Chrome также реализован метод slice, принимающий аргументами начальную позицию, длину и, опционально, тип вырезаемой части.

Инпутом теперь можно выбрать не один, а сразу несколько файлов. Это достигается простым установлением атрибута multiple в true (По аналогии с disabled, checked). А еще есть атрибут accept, который позволяет фильтровать файлы на стороне клиента по MIME типу. Например: audio/*, video/* разрешит выбор только аудио и видео файлов.

А как читать?

Для чтения предназначен класс FileReader. Создаете экземпляр этого класса, назначаете обработчики событий и нужным методом запускаете чтение файла. Методы:

• readAsBinaryString(file) — чтение в бинарном режиме.
• readAsText(file[, encoding]) — чтение в текстовом режиме. Дополнительным аргументом указывается кодировка (по-умолчанию UTF-8).
• readAsDataURL(/forum/file) — чтение в бинарном режиме с последующей перекодировкой в Data:URL.

Все чтения происходят в асинхронном режиме. Методы принимают аргументом объект класса File, содержимое которого нужно прочитать. По окончанию чтения заполняется свойство result, readyState принимает значение, соответствующее успешному завершению запроса (см. список состояний) и вызываются события.

Таблица состояний

• Состояние (Значение) — Описание
• FileReader.EMPTY (0) — Файл не выбран
• FileReader.LOADING (1) — Файл обрабатывается
• FileReader.DONE (2) — Файл обработан

События

• onloadstart — вызывается в момент начала чтения файла.
• onprogress — периодически вызывается в течение чтения файла. В момент завершения чтения не вызывается (Т.е. при реализации прогрессбара прогресс не будет доходить до конца. Нужно использовать свойство onload)
• onload — вызывается после успешного прочтения файла.
• onabort — вызывается при отмене чтения.
• onerror — вызывается при ошибке.
• onloadend — вызывается при завершении чтения, вне зависимости от успешности.

Для назначения событий используется, как нетрудно догадаться, метод addEventListener либо назначение соответствующего свойства.

Функциям-обработчикам событий первым аргументом передается событие event. Самые интересные свойства этого объекта, на мой взгляд:

• lengthComputable — true или false в зависимости от того, определена ли длина файла
• loaded — кол-во обработанных байт
• total — байт всего

Обещанный десерт

Итак, как я уже обещал, сейчас я опишу создание Drag and Drop аплоадера с прогрессбаром на чистом JS. Идея такая: получаем файл, сброшенный нам пользователем и асинхронно отсылаем его (файл), отслеживая принятые байты.

Drag and Drop

Для нормальной работы этой функции нужно задать следующие события:

var drg = function(e){
	e.stopPropagation();
	e.preventDefault();
}, element = document.body; // узел, на который будем "сбрасывать" файлы
element.addEventListener("dragenter", drg, false); // событие при наведении указателя
element.addEventListener("dragover", drg, false); // событие при покидании мыши области элемента
element.addEventListener("drop", function(e){ // непосредственно "сброс"
	if(!e.dataTransfer.files) return;
	e.stopPropagation();
	e.preventDefault();

	e.dataTransfer.files // тот же список файлов, что и у инпута
}, false);

Отправляем файл

Официальная спецификация декларирует новый класс: FormData. Экземпляры этого класса имеют один-единственный метод append, устанавливающий параметр запроса и его значение. Первым аргументом передается строка — имя параметра, вторым — данные на отправку. Это может быть либо строка, либо объект типа File (Blob, если быть точным). Если передать сформированный объект аргументом методу send XHR запроса, то он будет отправлен в режиме multipart.
Но, к сожалению, не все так быстро. FormData пока реализован только в Chrome (среди стабильных билдов. Обещается в FF 4). Для FF 3.6 можно вручную сформировать тело запроса, примерно так:
Content-type: multipart/form-data; boundary="<ФЛАГ_ГРАНИЦЫ>"

--<ФЛАГ_ГРАНИЦЫ>
Content-Disposition: form-data; name="<ИМЯ ПАРАМЕТРА>"; filename="<ИМЯ ФАЙЛА>"
Content-Type: application/octet-stream

<БИНАРНОЕ СОДЕРЖИМОЕ ФАЙЛА>
--<ФЛАГ_ГРАНИЦЫ>;

// file — файл для загрузки
// uploadURL - ссылка для загрузки файла
var xhr = new XMLHttpRequest();
xhr.open('POST', uploadURL, true);

if(typeof FormData == 'function'){ // правильный способ
	var fData = new FormData();
	fData.append('upfile', file);
	xhr.send(fData);
} else if(xhr.sendAsBinary){ // пусть работает хоть как-то
	var fReader = new FileReader();
	fReader.addEventListener('load', function(){
		var boundaryString = 'prevedmedved',
			boundary = '--' + boundaryString,
			requestbody = '';

		requestbody += boundary + '\r\n'
				+ 'Content-Disposition: form-data; name="upfile"; filename="' + file.name + '"' + '\r\n' // имя параметра — upfile
				+ 'Content-Type: application/octet-stream' + '\r\n'
				+ '\r\n'
				+ fReader.result // бинарное содержимое файла
				+ '\r\n'
				+ boundary;

		xhr.setRequestHeader("Content-type", 'multipart/form-data; boundary="' + boundaryString + '"');
		xhr.setRequestHeader("Connection", "close");
		xhr.setRequestHeader("Content-length", requestbody.length);
		xhr.sendAsBinary(requestbody);
	}, false);
	fReader.readAsBinaryString(file);
}

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

Вторая версия XHR декларирует свойство upload, служащее "приемником" событий. Т.е. для свойства upload доступен метод addEventListener. События полностью аналогичны событиям FileReader'а, так что приводить описание не буду. Так же, как у FileReader'а, у объекта event есть свойства total и loaded. Рассчитать на их основе процент прогресса и вывести несложно.

Почитать:
— FileAPI
— Спецификация FileAPI
— XMLHttpRequest 2
— Спецификация XMLHttpRequest 2
— FilesystemAPI & FileAPI
— FilesystemAPI