Книга: JavaScript. Подробное руководство, 6-е издание

FileReader

FileReader

асинхронный интерфейс чтения объекта File или Blob (EventTarget)

Объект FileReader определяет асинхронный прикладной интерфейс чтения содержимого объекта File или любого объекта Blob. Чтобы прочитать файл, следует выполнить следующие действия:

• Создать объект FileReader вызовом конструктора FileReader().

• Определить необходимые обработчики событий.

• Передать объект File или Blob одному из четырех методов чтения.

• Затем, когда будет вызван обработчик onload, содержимое файла будет доступно в свойстве result. Или, если будет вызван обработчик отеrror, свойство error будет ссылаться на объект FileError, содержащий дополнительную информацию.

• После окончания операции чтения при необходимости можно повторно использовать объект FileReader или удалить его и создать новый.

Синхронный прикладной интерфейс, который можно использовать в фоновых потоках выполнения, описывается в справочной статье FileReaderSync.

Конструктор

new FileReader()

Новый объект FileReader создается с помощью конструктора FileReader(), который не требует аргументов.

Константы

Следующие константы определяют возможные значения свойства readyState:

unsigned short EMPTY = 0

Метод чтения еще не был вызваню

unsigned short LOADING = 1

Выполняется операция чтенияю

unsigned short DONE = 2

Операция чтения завершилась, успешно или с ошибкой.

Свойства

readonly FileError error

Если ошибка возникнет во время чтения, это свойство будет ссылаться на объект FileError, описывающий ошибку.

readonly unsigned short readyState

Это свойство описывает текущее состояние объекта FileReader. Его значением будет одна из трех констант, перечисленных выше.

readonly any result

Если операция чтения завершится успешно, это свойство будет хранить содержимое объекта File или Blob в виде строки или объекта ArrayBuffer (в зависимости от использовавшегося метода чтения). Когда свойство readyState имеет значение LOADING или когда возбуждается событие «progress», это свойство может хранить неполное содержимое объекта File или Blob. Если метод чтения еще не был вызван или если возникла ошибка, это свойство будет иметь значение null.

Методы

void abort()

Прерывает операцию чтения. Он присваивает свойству readyState значение DONE, свойству result - значение null и свойству error - объект FileError со свойством code, установленным в значение FileError.AB0RT_ERR. После этого возбуждаются события «abort» и «loadend».

void readAsArrayBuffer(Blob blob)

• Асинхронно читает данные из объекта blob и сохраняет их в свойстве result в виде объекта ArrayBuffer.

void readAsBinaryString(Blob blob)

Асинхронно читает байты данных из объекта blob, преобразует их в двоичную строку и сохраняет ее в свойстве result. Каждый «символ» в двоичной строке представлен кодом символа в диапазоне от 0 до 255. Извлекать эти значения байтов можно с помощью метода String.charCodeAt(). Следует отметить, что двоичные строки являются не самым эффективным представлением двоичных данных: вместо них следует использовать объекты ArrayBuffer, когда это возможно.

void readAsDataURL(Blob blob)

Асинхронно читает байты данных из объекта blob, преобразует их (учитывая тип объекта Blob) в URL-адрес data:// и присваивает полученную строку свойству result.

void readAsText(Blob blob, [string encoding])

Асинхронно читает байты данных из объекта blob, декодирует их с использованием кодировки encoding в текстовую строку Юникода и затем присваивает полученную строку свойству result. Если аргумент encoding не указан, используется кодировка UTF-8 (текст в кодировке UTF-16 определяется и декодируется автоматически, если он начинается с маркера Byte Order Mark).

Обработчики событий

Подобно всем асинхронным прикладным интерфейсам, в своей работе объект FileReader опирается на события. Для регистрации обработчиков событий можно использовать свойства, перечисленные ниже, или методы интерфейса EventTarget, реализуемого объектом FileReader.

События объекта FileReader возбуждаются в самом объекте FileReader. Они не всплывают, и для них не предусматриваются действия по умолчанию. Обработчикам событий в объекте FileReader всегда передается объект ProgressEvent. Успешная операция чтения начинается с события «loadstart», за которым следует ноль или более событий «progress», событие «load» и событие «loadend». Неудачная операция чтения начинается с события «loadstart», за которым следует ноль или более событий «progress», событие «error» или «abort» и событие «loadend».

onabort

Вызывается, если операция чтения была прервана методом abort().

onerror

Вызывается, если возникла какая-либо ошибка. Свойство error объекта FileReader будет ссылаться на объект FileError, который имеет свойство code с кодом ошибки.

onload

Вызывается в случае успешного завершения операции чтения объекта File или Blob. Свойство result объекта FileReader хранит содержимое объекта File или Blob в виде, зависящем от использовавшегося метода чтения.

onloadend

Каждый вызов метода чтения объекта FileReader в конечном итоге возбуждает событие «load», «error» или «abort». Кроме того, после каждого из этих событий объект FileReader возбуждает событие «loadend» для программ, в которых было бы желательно обрабатывать единственное событие вместо трех.

onloadstart

Вызывается после вызова метода чтения, но перед тем как будут прочитаны какие-либо данные.

onprogress

Возбуждается примерно 20 раз в секунду, пока выполняется чтение данных из объекта File или Blob. Объект ProgressEvent позволяет узнать количество прочитанных байтов, а свойство result объекта FileReader может содержать представление этих байтов.

Оглавление книги