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

XMLHttpRequest

XMLHttpRequest

позволяет выполнять HTTP-запросы и получать ответы (EventTarget)

Объект XMLHttpRequest позволяет из клиентских JavaScript-сценариев запускать HTTP-запросы и получать от веб-сервера ответы (которые не обязательно должны быть в формате XML). Объект XMLHttpRequest подробно рассматривается в главе 18, там же можно найти множество примеров применения этого объекта.

Создать объект XMLHttpRequest можно с помощью конструктора XMLHttpRequest() (сведения о том, как создавать объекты XMLHttpRequest в ІE6, приводятся во врезке в разделе 18.1) и затем использовать его следующим образом:

1. Вызывается метод ореп(), с помощью которого определяются URL-адрес и метод передачи запроса (обычно «GET» или «POST»).

2. В свойство onreadystatechange записывается ссылка на функцию, которая будет вызываться в процессе выполнения запроса.

3. Вызывается метод setRequestHeader(), если необходимо указать дополнительные параметры запроса.

4. Вызовом метода send() выполняется отправка запроса веб-серверу. Если был выбран метод отправки POST, этому методу можно дополнительно передать тело запроса. В процессе выполнения запроса будет вызываться функция-обработчик события onreadystatechange. Когда свойство readyState получит значение 4, выполнение запроса завершится.

5. После того как свойство readyState достигнет значения 4, можно проверить код состояния в свойстве status, чтобы убедиться, что запрос завершился успехом. В этом случае методом getResponseHeader() или getResponseHeaders() следует извлечь значения из заголовка ответа и с помощью свойства responseText или responseXML получить тело ответа.

Объект XMLHttpRequest определяет относительно высокоуровневый прикладной интерфейс к протоколу HTTP. Он учитывает такие особенности, как обработка переадресации, управление cookies и обслуживание меж доменных запросов с заголовками CORS.

Возможности объекта XMLHttpRequest, описанные выше, прекрасно поддерживаются всеми современными броузерами. На момент написания этих строк велись работы над стандартом «XMLHttpRequest Level 2», и производители броузеров уже приступили к его реализации. Свойства, методы и обработчики событий, перечисленные ниже, включают особенности, введенные спецификацией «XMLHttpRequest Level 2», которые могут быть реализованы не во всех броузерах. Эти новые особенности помечены строкой «XHR2».

Конструктор

new XMLHttpRequest()

Этот конструктор, не имеющий аргументов, возвращает новый объект XMLHttpRequest.

Константы

unsigned short UNSENT = 0

Начальное состояние. Объект XMLHttpRequest только что создан или сброшен в исходное состояние вызовом метода abort().

unsigned short OPENED = 1

Метод open() уже вызван, но обращения к методу send() еще не было. Запрос еще не отправлен.

unsigned short HEADERS.RECEIVED = 2

Вызван метод send() и приняты заголовки ответа, но тело ответа еще не принято.

unsigned short LOADING = З

Начат прием тела ответа, но прием еще не завершился.

unsigned short DONE = 4

HTTP-ответ принят полностью или прием был остановлен из-за ошибки.

Свойства

readonly unsigned short readyState

Состояние HTTP-запроса. В момент создания объекта XMLHttpRequest это свойство приобретает значение 0, а к моменту получения полного HTTP-ответа это значение возрастает до 4. Возможные значения свойства определяют константы, перечисленные выше.

Значение свойства readyState может уменьшаться, только если в процессе выполнения запроса был вызван метод abort() или ореп().

Теоретически при каждом изменении значения этого свойства должен вызываться обработчик события onreadystatechange. Однако на практике событие гарантированно возникает, только когда свойство readyState получает значение 4. (События «progress», введенные спецификацией XHR2, обеспечивают более надежный способ слежения за ходом выполнения запроса.)

readonly any response

В спецификации XHR2 это свойство хранит ответ сервера. Тип свойства зависит от значения свойства responseType. Если responseType содержит пустую строку или строку «text», данное свойство содержит тело ответа в виде строки. Если responseType содержит строку «document», значением данного свойства будет объект Document, полученный в результате разбора XML- или HTML-документа в теле ответа. Если responseType содержит строку «arraybuffer», значением данного свойства будет объект ArrayBuffer, представляющий двоичные данные в теле ответа. А если responseType содержит строку «ЫоЬ», значением данного свойства будет объект Blob, представляющий двоичные данные в теле ответа.

readonly string responseText

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

Если в ответе имеется заголовок, определяющий кодировку символов в теле ответа, используется эта кодировка, в противном случае предполагается кодировка UTF-8.

string responseType

В спецификации ХHR2 это свойство определяет тип ответа и тип свойства response. Допустимыми значениями являются «text», «document», «arraybuffer» и «blob».

Значением по умолчанию является пустая строка, которая также является синонимом значения «text». Если установить это свойство вручную, последующие попытки обратиться к свойствам responseText и responseXML будут возбуждать исключения и для получения ответа сервера необходимо будет использовать свойство response, предусмотренное спецификацией XHR2.

readonly Document responseXML

Ответ на запрос, который интерпретируется как XML- или HTML-документ и возвращается в виде объекта Document. Это свойство будет иметь значение null, если тело ответа еще не получено или оно не является допустимым XML или HTML-документом.

readonly unsigned short status

HTTP-код состояния, полученный от сервера, такой как 200 - в случае успеха, 404 - в случае ошибки отсутствия документа или 0 - если сервер еще не прислал код состояния.

readonly string statusText

Это свойство содержит текст, соответствующий HTTP-коду состояния в ответе. То есть, когда свойство status имеет значение 200, это свойство содержит строку «ОК», а когда 404 - строку «Not Found». Это свойство содержит пустую строку, если сервер еще не прислал код состояния.

unsigned long timeout

Свойство, введенное спецификацией XHR2, определяющее предельное время ожидания ответа в миллисекундах. Если выполнение HTTP-запроса займет больше времени, чем указано в данном свойстве, он будет прерван и будет сгенерировано событие «timeout». Это свойство можно установить только после вызова метода open() и перед вызовом метода send().
readonly XMLHttpRequestUpload upload

Свойство, введенное спецификацией XHR2, ссылающееся на объект XMLHttpRequestUpload, который определяет набор свойств регистрации обработчиков событий для слежения за процессом выгрузки тела НТТР-запроса.

boolean withCredentials

Свойство, введенное спецификацией XHR2, определяющее необходимость аутентификации при выполнении междоменного CORS-запроса и необходимость обработки заголовков cookie в CORS-ответах. По умолчанию имеет значение false.

Методы

void abort()

Возвращает объект XMLHttpRequest в исходное состояние, соответствующее значению 0 в свойстве readyState, и отменяет любые запланированные сетевые взаимодействия. Этот метод может потребоваться, например, если запрос выполняется слишком долго и надобность в получении ответа уже отпала.

string getAllResponseHeaders()

Возвращает все HTTP-заголовки ответа (с отфильтрованными заголовками cookie и CОRS), полученные от сервера, или null, если заголовки еще не были получены. Заголовки cookie и CОRS отфильтровываются и не могут быть получены. Заголовки возвращаются в виде единственной строки и отделяются друг от друга комбинацией символов rn.

string getResponseHeader(string header)

Возвращает значение указанного заголовка header в HTTP-ответе или null, если заголовки вообще не были получены или если ответ не содержит требуемого заголовка header. Заголовки cookie и CORS отфильтровываются, и их нет смысла запрашивать. Если было принято несколько заголовков с указанным именем, значения этих заголовков объединяются в одну строку через запятую и пробел.

void open(string method, string url, [boolean async, string user, string pass])

Этот метод инициализирует объект XMLHttpRequest и сохраняет свои аргументы для последующего использования методом send().

Аргумент method определяет HTTP-метод, используемый для отправки запроса. Среди наиболее устоявшихся методов можно назвать GET, POST и HEAD. Реализации могут также поддерживать методы CONNECT, DELETE, OPTIONS, PUT, TRACE и TRACK.

Аргумент url определяет URL-адрес, который является предметом запроса. Разрешение относительных URL-адресов производится обычным образом с использованием URL-адреса документа со сценарием. Политика общего происхождения (см. раздел 13.6.2) требует, чтобы данный URL-адрес содержал те же имя хоста и номер порта, что и документ со сценарием, выполняющим запрос. Объект XHR2 позволяет выполнять междоменные запросы к серверам, поддерживающим заголовки CORS. Если аргумент async указан и имеет значение false, запрос будет выполняться в синхронном режиме, и последующий вызов send() заблокирует работу сценария, пока ответ не будет получен полностью. Синхронные запросы рекомендуется использовать только в фоновых потоках выполнения.

Необязательные аргументы user и pass определяют имя пользователя и пароль для НТТР-запроса.

void overrideMimeType(string mime)

Этот метод позволяет указать, что ответ сервера должен интерпретироваться в соответствии с указанным MIME-типом mime (и параметром charset, если он указан в определении типа mime), без учета значения заголовка Content-Type в ответе.

void send(any body)

Инициирует выполнение HTTP-запроса. Если перед этим не вызывался метод ореn() или, обобщенно, если значение свойства readyState не равно 1, метод send() возбуждает исключение. В противном случае он начинает выполнение НТТР-запроса, который состоит из:

• НТТР-метода, URL-адреса и информации об авторизации (если необходимо), определенных предшествующим вызовом метода ореn();

• заголовков запроса, если они были определены предшествующим вызовом метода setRequestHeader();

• значения аргумента body, переданного данному методу. Аргумент body может быть строкой, объектом Document, образующим тело запроса; он может быть опущен или иметь значение null, если запрос не имеет тела (например, GET-запросы вообще не имеют тела). Согласно спецификации XHR2 телом запроса также могут быть объекты ArrayBuffer, Blob и FormData.

Если в предшествующем вызове метода ореn() аргумент async имел значение false, данный метод блокируется и не возвращает управление, пока значение свойства readyState не станет равно 4 и ответ сервера не будет получен полностью. В противном случае метод send() немедленно возвращает управление, а ответ сервера обрабатывается асинхронно, с помощью обработчиков событий.

void setRequestHeader(string name, string value)

Определяет HTTP-заголовок с именем name и значением value, который должен быть включен в запрос, передаваемый последующим вызовом метода send(). Этот метод может вызываться, только когда свойство readyState имеет значение 1, т.е. после вызова метода ореn(), но перед вызовом метода send().

Если заголовок с именем пате уже был определен, новым значением заголовка станет прежнее значение заголовка плюс запятая с пробелом и новое значение value, переданное методу.

Если методу open() была передана информация об авторизации, объект XMLHttp-Request автоматически добавит заголовок Authorization. Однако этот заголовок может быть также добавлен методом setRequestHeader().

Объект XMLHttpRequest автоматически устанавливает заголовки «Content-Length», «Date», «Referer» и «User-Agent» и не позволяет изменять их значения. Существует еще несколько заголовков, включая заголовки, имеющие отношение к cookies, которые нельзя установить с помощью этого метода. Полный их список приводится в разделе 18.1.

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

Оригинальный объект XMLHttpRequest определяет только одно свойство регистрации обработчика событий: onreadystatechange. Спецификация XHR2 дополняет этот список множеством обработчиков событий хода выполнения запроса, которые намного проще в использовании. Зарегистрировать обработчики можно с помощью свойств, перечисленных ниже, или с помощью методов интерфейса EventTarget. События, возникающие в объекте XMLHttpRequest, всегда доставляются самому объекту XMLHttpRequest. Они не всплывают и не предусматривают действий по умолчанию, которые можно было бы отменить. Обработчикам событий «readystatechange» передается объект Event, а обработчикам остальных событий - объект ProgressEvent.

См. также описание свойства upload и XMLHttpRequestUpload, где приводится список событий, которые можно использовать для слежения за ходом выгрузки тела НТТР-запроса.

onabort

Вызывается при прерывании запроса.

onerror

Вызывается в случае завершения запроса по ошибке. Обратите внимание, что HTTP-коды состояния, такие как 404, не считаются ошибкой, поскольку сам ответ получен успешно. Однако это событие может породить отрицательный ответ сервера DNS или бесконечный цикл переадресаций.

onload

Вызывается при успешном выполнении запроса.

onloadend

Вызывается в случае успешного или неудачного завершения запроса, после событий «load», «abort», «error» и «timeout».

onloadstart

Вызывается с началом выполнения запроса.

onprogress

Вызывается периодически (примерно раз в 50 миллисекунд) в ходе загрузки тела ответа.

onreadystatechange

Вызывается при изменении значения свойства readyState. Наиболее важен для обработки ситуации завершения запроса.

ontimeout

Вызывается, если истекло время ожидания, определяемое свойством timeout, а ответ так и не был принят.

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