Живой стандарт — Обновление 29 июня 2020 года
Принять участие:
Фиксировать:
Тесты:
Переводы (ненормативные):
- https://triple-underscore.github.io/XHR-ja.html
Аннотация
Стандарт XMLHttpRequest определяет API-интерфейс, который предоставляет клиенту функциональные возможности по сценарию для передачи данных между клиентом и сервером.
Оглавление
1. Введение
1.1 История спецификаций
2. Соответствие
2.1 Расширяемость
3. Терминология
4. Интерфейс XMLHttpRequest
4.1 Конструкторы
4.2 Сборка мусора
4.3 Обработчики событий
4.4 Состояния
4.5 Запрос
4.5.1 Метод open()
4.5.2 Метод setRequestHeader()
4.5.3 Атрибут timeout
4.5.4 Атрибут withCredentials
4.5.5 Атрибут upload
4.5.6 Метод send()
4.5.7 Метод abort()
4.6 Ответ
4.6.1 Атрибут responseURL
4.6.2 Атрибут status
4.6.3 Атрибут statusText
4.6.4 Метод getResponseHeader()
4.6.5 Метод getAllResponseHeaders()
4.6.6 Тело ответа
4.6.7 Метод overrideMimeType()
4.6.8 Атрибут responseType
4.6.9 Атрибут response
4.6.10 Атрибут responseText
4.6.11 Атрибут responseXML
4.7 Краткое изложение событий
4.8 Интеграция с политикой функций
5. Интерфейс FormData
6. Интерфейс ProgressEvent
6.1 Запуск событий с использованием интерфейса ProgressEvent
6.2 Предлагаемые имена для событий с использованием интерфейса ProgressEvent
6.3 Соображения безопасности
6.4 Пример
Благодарности
Индекс
Термины, определенные в данной спецификации
Термины, определенные ссылкой
Ссылки
Нормативные ссылки
Индекс IDL
1. Введение
Этот раздел не является нормативным.
Объект XMLHttpRequest — это API для извлечения ресурсов. (https://fetch.spec.whatwg.org/#concept-fetch)
Название XMLHttpRequest является историческим и не имеет отношения к его функциональности.
Пример:
Некоторый простой код для работы с данными из XML-документа, извлеченного по сети:
function processData(data) {
// заботиться о данных (taking care of data)
}
function handler() {
if(this.status == 200 &&
this.responseXML != null &&
this.responseXML.getElementById('test').textContent) {
// успех! (success!)
processData(this.responseXML.getElementById('test').textContent);
} else {
// что-то пошло не так (something went wrong)
…
}
}
var client = new XMLHttpRequest();
client.onload = handler;
client.open("GET", "unicorn.xml");
client.send();
Если вы просто хотите записать сообщение на сервер:
function log(message) {
var client = new XMLHttpRequest();
client.open("POST", "/log");
client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
client.send(message);
}
Или, если вы хотите проверить статус документа на сервере:
function fetchStatus(address) {
var client = new XMLHttpRequest();
client.onload = function() {
// в случае сетевых ошибок это может не дать надежных результатов
returnStatus(this.status);
}
client.open("HEAD", address);
client.send();
}
1.1 История спецификаций
Объект XMLHttpRequest изначально был определен как часть работы WHATWG в области HTML. (Основано на реализации Microsoft за много лет до этого.) В 2006 году она перешла на W3C. Расширения (например, события прогресса и запросы разных источников) к XMLHttpRequest были разработаны в отдельном проекте (XMLHttpRequest Level 2) до конца 2011 года, и в этот момент два проекта были объединены, и XMLHttpRequest снова стал единым целым с точки зрения стандартов. В конце 2012 года он вернулся к WHATWG.
Обсуждение, которое привело к текущему черновику, можно найти в следующих архивах списков рассылки:
2. Соответствие
Все диаграммы, примеры и примечания в этой спецификации являются ненормативными, так как все разделы явно помечены как ненормативные. Все остальное в этой спецификации является нормативным.
Ключевые слова «ОБЯЗАН — MUST», «НЕ ОБЯЗАН — MUST NOT», «ТРЕБУЕТСЯ — REQUIRED», «ДОЛЖЕН — SHALL», «НЕ ДОЛЖЕН — SHALL NOT», «СЛЕДУЕТ — SHOULD», «НЕ СЛЕДУЕТ — SHOULD NOT», «РЕКОМЕНДУЕТСЯ — RECOMMENDED», «НЕ РЕКОМЕНДУЕТСЯ — NOT RECOMMENDED», «ВОЗМОЖЕН — MAY» и «ДОПОЛНИТЕЛЬНО — OPTIONAL» в этом документе интерпретироваться как описано в [RFC2119 #] [RFC8174 #].
2.1 Расширяемость
Пользовательским агентам, рабочим группам и другим заинтересованным сторонам настоятельно рекомендуется обсудить новые функции с сообществом WHATWG.
3. Терминология
В этой спецификации используется терминология, сшитая повсеместно, из DOM, парсинга и сериализации DOM, кодирования, политики компонентов, выборки, файлового API, HTML, HTTP, URL, Web IDL и XML.
[DOM] [DOMPS] [ENCODING] [FEATURE-POLICY] [FETCH] [FILEAPI] [HTML] [HTTP] [URL] [WEBIDL] [XML] [XMLNS]
Он использует типографские соглашения из HTML. [HTML]
4. Интерфейс XMLHttpRequest
[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequestEventTarget : EventTarget {
// event handlers
attribute EventHandler onloadstart;
attribute EventHandler onprogress;
attribute EventHandler onabort;
attribute EventHandler onerror;
attribute EventHandler onload;
attribute EventHandler ontimeout;
attribute EventHandler onloadend;
};
[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
};
enum XMLHttpRequestResponseType {
"",
"arraybuffer",
"blob",
"document",
"json",
"text"
};
[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequest : XMLHttpRequestEventTarget {
constructor();
// ОБРАБОТЧИКИ СОБЫТИЙ (event handler)
attribute EventHandler onreadystatechange;
// СОСТОЯНИЯ (states)
const unsigned short UNSENT = 0;
const unsigned short OPENED = 1;
const unsigned short HEADERS_RECEIVED = 2;
const unsigned short LOADING = 3;
const unsigned short DONE = 4;
readonly attribute unsigned short readyState;
// ЗАПРОС (request)
void open(ByteString method, USVString url);
void open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null);
void setRequestHeader(ByteString name, ByteString value);
attribute unsigned long timeout;
attribute boolean withCredentials;
[SameObject] readonly attribute XMLHttpRequestUpload upload;
void send(optional (Document or XMLHttpRequestBodyInit)? body = null);
void abort();
// ОТВЕТ (response)
readonly attribute USVString responseURL;
readonly attribute unsigned short status;
readonly attribute ByteString statusText;
ByteString? getResponseHeader(ByteString name);
ByteString getAllResponseHeaders();
void overrideMimeType(DOMString mime);
attribute XMLHttpRequestResponseType responseType;
readonly attribute any response;
readonly attribute USVString responseText;
[Exposed=Window] readonly attribute Document? responseXML;
};
Объект XMLHttpRequest имеет связанный объект XMLHttpRequestUpload.
У объекта XMLHttpRequest есть связанное состояние:
- unsent (неотправленное)
- opened (открытое)
- headers received (полученные заголовки)
- loading (загрузка)
- done (выполнение)
Если не указано иное, оно unsent (не отправлено)
С объектом XMLHttpRequest связан флаг send(). Если не указано иное, оно не установлено.
4.1 Конструкторы (Constructors)
Для web разработчиков (ненормативно)
client = new XMLHttpRequest()
- Возвращает новый объект XMLHttpRequest.
При вызове конструктор XMLHttpRequest() должен возвращать новый объект XMLHttpRequest.
4.2 Сборка мусора (Garbage collection)
Объект XMLHttpRequest не должен собираться мусором, если его состояние открывается с помощью установленного флага send(), headers received (полученных заголовков) или loading (загрузки), и для него зарегистрирован один или несколько event listeners (прослушивателей событий), тип которых:
- readystatechange
- progress
- abort
- error
- load
- timeout
- loadend
Если объект XMLHttpRequest является сборщиком мусора, когда его соединение все еще открыто, пользовательский агент должен прекратить текущую выборку, управляемую объектом XMLHttpRequest.
4.3 Обработчики событий (Event handlers)
Ниже перечислены обработчики событий (и соответствующие им типы событий обработчиков событий), которые должны поддерживаться в объектах, реализующих интерфейс, который наследуется от XMLHttpRequestEventTarget в качестве атрибутов:
Обработчики событий | Типы событий обработчиков событий |
---|---|
onloadstart | loadstart |
onprogress | progress |
onabort | abort |
onerror | error |
onload | load |
ontimeout | timeout |
onloadend | loadend |
Ниже приведен обработчик события (и соответствующий ему тип события обработчика события), который должен поддерживаться как атрибут исключительно объектом XMLHttpRequest:
Обработчики событий | Типы событий обработчиков событий |
---|---|
onreadystatechange | readystatechange |
4.4 Состояния (States)
Для web разработчиков (ненормативно)
client . readyState
- Возвращает состояние клиента.
Получатель атрибута readyState должен возвращать значение из таблицы ниже в ячейке второго столбца, из строки, где значение в ячейке в первом столбце является состоянием объекта контекста:
unsent |
|
Объект был построен. | |
---|---|---|---|
opened | OPENED (numeric value 1) |
Метод open() был успешно вызван. Во время этого состояния заголовки запроса могут быть установлены с помощью setRequestHeader(), а выборка может быть инициирована с помощью метода send(). | |
headers received | HEADERS_RECEIVED (numeric value 2) |
Все перенаправления (если таковые имеются) были выполнены, и все HTTP-заголовки ответа были получены. | |
loading | LOADING (numeric value 3) |
Тело ответа получено. | |
done | DONE (numeric value 4) |
Передача данных была завершена или что-то пошло не так во время передачи (например, бесконечные перенаправления). |
4.5 Запрос (Request)
Каждый объект XMLHttpRequest имеет следующие связанные с запросом концепции:
- метод запроса (request method)
- URL-адрес запроса (request URL)
- заголовки запроса автора (author request headers)
- тело запроса (request body)
- синхронный флаг (synchronous flag)
- флаг завершения загрузки (upload complete flag)
- флаг прослушивателя загрузки (upload listener flag)
- флаг тайм-аута (timed out flag)
Заголовки запроса автора (author request headers) — это изначально пустой список заголовков (header list).
Тело запроса (request body) изначально нулевое (null).
Синхронный флаг (synchronous flag), флаг завершения загрузки (upload complete flag), флаг прослушивателя загрузки (upload listener flag) и флаг тайм-аута (timed out flag) изначально не установлены.
Примечание: Регистрация одного или нескольких прослушивателей событий в объекте XMLHttpRequestUpload приведет к запросу предварительной проверки CORS. CORS-preflight request
(Это связано с тем, что регистрация прослушивателя событий приводит к установке флага прослушивателя загрузки, что, в свою очередь, приводит к установке флага use-CORS-preflight flag)
4.5.1 Метод open()
Для web разработчиков (ненормативно)
client . open(method, url [, async = true [, username = null [, password = null]]])
Устанавливает метод запроса, URL запроса и синхронный флаг.
- Выдает исключение DOMException «SyntaxError», если какой-либо метод не является допустимым методом HTTP или URL не может быть проанализирован.
- Выдает исключение DOMException «SecurityError», если метод является регистронезависимым совпадением для `CONNECT`,` TRACE` или `TRACK`.
- Выдает исключение DOMException «InvalidAccessError«, если async имеет значение false, текущий глобальный объект является объектом Window, а атрибут timeout не равен нулю или атрибут responseType не является пустой строкой.
Синхронный запрос XMLHttpRequest вне рабочих находится в процессе удаления с веб-платформы, поскольку он оказывает пагубное влияние на работу конечного пользователя. (Это долгий процесс, который занимает много лет.) Разработчики не должны передавать false для асинхронного аргумента, когда текущий глобальный объект является объектом Window. Пользовательским агентам настоятельно рекомендуется предупреждать о таком использовании в инструментах разработчика и могут поэкспериментировать с генерацией исключения DOMException «InvalidAccessError» при его возникновении.
Методы open (method, url) и open (method, url, async, username, password) при вызове должны выполнить следующие шаги:
- Пусть settingsObject будет соответствующим объектом настроек объекта контекста.
- Если settingsObject имеет ответственный документ и он не полностью активен, то генерируется исключение DOMException «InvalidStateError».
- Если method не является методом, то выдается исключение DOMException «SyntaxError»
- Если method является запрещенным методом, то генерируется исключение DOMException «SecurityError»
- Нормализовать method. (Normalize method)
- Пусть parsedURL будет результатом анализа URL-адреса (parsing) с помощью базового URL-адреса API (API base URL) settingsObject и кодировки символов URL-адреса API (API URL character encoding) settingsObject.
- Если parsedURL — сбой, выдается (throw) исключение DOMException «SyntaxError»
- Если аргумент async опущен, задайте для async значение true, а для имени пользователя (username) и пароля (password) — null. (К сожалению, унаследованный контент не позволяет считать асинхронный аргумент неопределенным, поскольку он опущен)
- Если синтаксический анализ URL хоста (host) не равен NULL, то:
-
- Если аргумент username не является нулевым, установите имя пользователя, заданное parsedURL и username
- Если аргумент password не является нулевым, установите пароль с учетом parsedURL и password.
-
- Если async имеет значение false, текущий глобальный объект является объектом Window, а значение атрибута timeout не равно нулю или значение атрибута responseType не является пустой строкой, тогда генерируется исключение DOMException «InvalidAccessError«
- Завершить (Terminate) текущую выборку, управляемую объектом XMLHttpRequest. (Выборка fetch может быть продолжена в этот момент.)
- Установите переменные, связанные с объектом, следующим образом:
- Снимите флажок send() и флаг upload listener
- Установите метод запроса на method
- Установите URL запроса на parsedURL
- Установите синхронный флаг, если async имеет значение false, и в противном случае снимите синхронный флаг
- Пустые заголовки запроса автора
- Установите ответ на сетевую ошибку
- Установить полученные байты в пустую последовательность байтов
- Установить объект ответа на ноль
- Примечание: Override MIME type здесь не переопределяется, так как метод overrideMimeType() может быть вызван перед методом open().
- Если состояние не opened, то:
- Установите состояние на opened
- Запустите событие с именем readystatechange как this.
- Примечание: Причина, по которой определены два метода open(), связана с ограничением программного обеспечения для редактирования, используемого для написания стандарта XMLHttpRequest.
4.5.2 Метод setRequestHeader()
Для web разработчиков (ненормативно)
client . setRequestHeader(name, value)
- Объединяет заголовок в заголовки запроса автора.
- Выдает исключение DOMException «InvalidStateError», если либо состояние не opened, либо установлен флаг send().
- Выдает исключение DOMException «SyntaxError», если name не является именем заголовка или если value не является значением заголовка.
Метод setRequestHeader (name, value) должен выполнить эти шаги:
- Если состояние не opened, то генерируется исключение DOMException «InvalidStateError»
- Если установлен флаг send(), то генерируется исключение DOMException «InvalidStateError»
- Нормализовать значение value
- Если name не является именем или value не является значением, выдается исключение DOMException «SyntaxError» (Примечание: Пустая последовательность байтов представляет пустое значение заголовка.)
- Завершите эти шаги, если name является запрещенным именем заголовка.
- Объедините name/value в заголовках запроса автора
Пример: Небольшой простой код, демонстрирующий, что происходит при установке одного и того же заголовка дважды:
// The following script:
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send();
// …results in the following header being sent:
// X-Test: one, two
4.5.3 Атрибут timeout
Для web разработчиков (ненормативно)
client . timeout
- Может быть установлено время в миллисекундах. Если установлено ненулевое значение, выборка прекратится после истечения заданного времени. Когда время прошло, запрос еще не завершен, и синхронный флаг не установлен, затем будет отправлено событие тайм-аута, или в противном случае будет сгенерировано DOMException «TimeoutError» (для метода send()).
- Если установлено: генерирует исключение DOME «InvalidAccessError», если установлен синхронный флаг и текущий глобальный объект является объектом Window.
Атрибут timeout должен возвращать свое значение. Первоначально его значение должно быть равно нулю.
Установка атрибута времени ожидания должна выполнить эти шаги:
- Если текущий глобальный объект является объектом Window и установлен синхронный флаг, то генерируется исключение DOMException «InvalidAccessError».
- Установите его значение в новое значение. (Примечание: Это означает, что атрибут timeout может быть установлен во время выборки (fetching). Если это произойдет, оно все равно будет измеряться относительно начала выборки.)
4.5.4 Атрибут withCredentials
Для web разработчиков (ненормативно)
client . withCredentials
- Истинно, когда учетные данные должны быть включены в запрос кросс-источника (cross-origin request). Ложно, когда они должны быть исключены в запросе перекрестного происхождения и когда куки-файлы должны игнорироваться в его ответе. Изначально ложно.
- Если установлено: генерирует исключение DOMException «InvalidStateError», если состояние не unsent или не opened, или если установлен флаг send().
Атрибут withCredentials должен возвращать свое значение. Первоначально его значение должно быть ложным.
Установка атрибута withCredentials должна выполнить эти шаги:
- Если состояние не unsent или не opened, выдается исключение DOMException «InvalidStateError»
- Если установлен флаг send(), то генерируется исключение DOMException «InvalidStateError».
- Установите для атрибута withCredentials значение данного значения. (Примечание: Атрибут withCredentials не влияет на выборку ресурсов одного источника.)
4.5.5 Атрибут upload
Для web разработчиков (ненормативно)
client . upload
- Возвращает связанный объект XMLHttpRequestUpload. Он может использоваться для сбора информации о передаче, когда данные передаются на сервер.
Атрибут upload должен возвращать связанный объект XMLHttpRequestUpload.
Примечание: Как указывалось ранее, каждый объект XMLHttpRequest имеет связанный объект XMLHttpRequestUpload.
4.5.6 Метод send()
Для web разработчиков (ненормативно)
client . send([body = null])
- Инициирует запрос. Аргумент body предоставляет тело запроса, если оно есть, и игнорируется, если метод запроса имеет тип GET или HEAD.
- Выдает исключение DOMException «InvalidStateError», если либо состояние не opened, либо установлен флаг send().
Метод send(body) должен выполнить эти шаги:
- Если состояние не opened, то генерируется исключение DOMException «InvalidStateError».
- Если установлен флаг send(), то генерируется исключение DOMException «InvalidStateError».
- Если метод запроса — GET или HEAD, установите для body значение null.
- Если body не является нулевым, то:
- Пусть extractContentType будет нулевым.
- Если body является объектом Document, тогда установите тело запроса в body, сериализованное, преобразованное и кодированное в UTF-8.
- В противном случае, установите тело запроса и extractContentType равным результату извлечения body.
- Если заголовок запроса автора содержит `Content-Type`, то:
- Если body является объектом Document или USVString, то:
- Пусть originalAuthorContentType будет значением заголовка, имя которого является нечувствительным к регистру байтов совпадением для `Content-Type` в заголовках запроса автора.
- Пусть contentTypeRecord будет результатом анализа originalAuthorContentType.
- Если contentTypeRecord не является ошибкой, параметры contentTypeRecord [«charset»] существуют, а параметры [«charset»] не являются ASCII-нечувствительным к регистру соответствием для «UTF-8», тогда:
- Установите для параметров contentTypeRecord [«charset»] значение «UTF-8».
- Пусть newContentTypeSerialized будет результатом сериализации contentTypeRecord.
- Установите `Content-Type` / newContentTypeSerialized в заголовках запроса автора.
- Если body является объектом Document или USVString, то:
- В противном случае:
- Если body является HTML-документом, установите `Content-Type` / ` text / html; charset = UTF-8` в заголовках запроса автора.
- В противном случае, если body является документом XML, установите `Content-Type` / ` application / xml; charset = UTF-8` в заголовках запроса автора.
- В противном случае, если extractContentType не является нулевым, установите `Content-Type` / extractContentType в заголовках запроса автора.
- Если один или несколько прослушивателей событий зарегистрированы в связанном объекте XMLHttpRequestUpload, установите флажок загрузки приемника (upload listener flag).
- Пусть req будет новым запросом, инициализированным следующим образом:
-
- method (request method — метод запроса)
- url (request URL — URL запроса)
- header list (author request headers — заголовки запроса автора)
- unsafe-request flag (флаг небезопасного запроса — установлен)
- body (request body — тело запроса)
- client (context object’s relevant settings object — соответствующий объект настроек объекта контекста)
- synchronous flag (Установите, если установлен синхронный флаг)
- mode («
cors
«) - use-CORS-preflight flag (Установите, если установлен флаг прослушивателя загрузки.)
- credentials mode (Если значение атрибута withCredentials равно true, в противном случае используйте «include» и «same-origin».)
- use-URL-credentials flag (Устанавливается, если имя пользователя URL-адреса запроса не является пустой строкой или пароль URL-адреса запроса не является нулевым.)
-
- Снимите флажок завершения загрузки.
- Снимите флажок тайм-аута.
- Если тело req (запроса) равно нулю, установите флаг завершения загрузки.
- Установите флаг отправки send().
- Если синхронный флаг не установлен, то:
- Запустите событие прогресса с именем loadstart при этом с «0» и «0».
- Если флаг завершения загрузки не установлен, а флаг прослушивателя загрузки установлен, то запускается событие прогресса с именем loadstart для этого объекта XMLHttpRequestUpload с «0» и общим байтом тела запроса.
- Если состояние не opened или флаг send() не установлен, вернитесь.
- Получить запрос req. Обработайте задачи, поставленные в очередь в сетевом источнике задач согласно ниже.
- Выполните эти шаги параллельно:
-
- Подождите, пока не будет установлен флаг готовности req или
-
- значение атрибута timeout количество миллисекунд прошло с момента начала этих шагов
- значение атрибута timeout не равно нулю.
-
- Если флаг выполнения req не установлен, тогда установите флаг тайм-аута и прекратите выборку
- Подождите, пока не будет установлен флаг готовности req или
-
- Чтобы обработать тело запроса для request, выполните эти шаги:
- Если с момента последнего запуска этих шагов прошло не более 50 мс, прекратите эти шаги
- Если установлен флаг прослушивателя загрузки, то запускается событие прогресса с именем progress в этом объекте XMLHttpRequestUpload с переданными байтами тела запроса и общими байтами тела запроса. (Примечание: Эти шаги вызываются только при передаче новых байтов)
- Чтобы обработать запрос конца тела для request, выполните следующие действия:
-
- Установите флаг завершения загрузки
- Если флаг прослушивателя загрузки не установлен, прекратите эти шаги
- Позвольте transmitted (переданному) быть переданные байты тела request (запроса)
- Пусть length (длина) будет общим байтом тела request (запроса)
- Запустите событие прогресса с именем progress в этом объекте XMLHttpRequestUpload с transmitted и length (передачей и длиной)
- Запустите событие прогресса с именем load в этом объекте XMLHttpRequestUpload с transmitted и length (передачей и длиной)
- Запустите событие прогресса с именем loadend для этого объекта XMLHttpRequestUpload с transmitted и length (передачей и длиной)
-
- Чтобы обработать ответ для response, выполните следующие действия:
-
- Установить ответ на response
- Обработайте ошибки для response
- Если ответ — ошибка сети, вернитесь
- Установите состояние headers received
- Запустите событие с именем readystatechange в this
- Если состояние не headers received, то заголовки возвращаются
- Если тело response пустое, то запустите дескриптор end-of-body ответа и вернитесь
- Пусть reader будет результатом получения читателя из потока тела ответа (Примечание: Эта операция не вызовет исключения)
- Пусть read будет результатом чтения фрагмента из потока тела response с помощью reader.
Когда read (чтение) выполняется с объектом, свойство done которого имеет значение false, а свойство value является объектом Uint8Array, выполните эти шаги, а затем снова выполните этот шаг:-
- Добавить свойство value к полученным байтам
- Если с момента последнего вызова этих шагов прошло не более 50 мс, прекратите эти шаги.
- Если состояние — headers received (полученные заголовки), тогда установите состояние для loading (загрузки).
- Запустите событие с именем readystatechange в this. (Примечание: Веб-совместимость является причиной, по которой readystatechange срабатывает чаще, чем изменения состояния.)
- Запустите событие прогресса, называемое
progress
, с переданными байтами тела ответа (response) и общими байтами тела ответа (response).
Когда «read» выполняется с объектом, свойство «done» которого имеет значение true, запускается дескриптор ответа end-of-body для «response»
Когда «read» отклонено с исключением, выполните дескриптор ошибки «response». -
-
- В противном случае, если установлен синхронный флаг, выполните следующие действия:
-
- Если соответствующий объект настроек объекта контекста имеет ответственный документ, которому не разрешено использовать функцию «sync-xhr», тогда выполните end of-body тела ответа handle для сетевой ошибки и возврата.
- Пусть ответ response будет результатом получения запроса req.
Если значение атрибута timeout не равно нулю, установите флаг тайм-аута и прекратите выборку, если он не вернулся в течение миллисекунд с момента тайм-аута. - Если тело ответа response имеет значение null, запустите дескриптор ответа end-of-body и вернитесь.
- Пусть reader будет результатом получения читателя из потока тела ответа. (Примечание: Эта операция не вызовет исключения.)
- Пусть обещание promise будет результатом чтения всех байтов из потока тела ответа response читателем reader.
- Ждите обещания promise, которое будет выполнено или отклонено
- Если обещание promise выполнено с байтами bytes, тогда добавьте байты к полученным байтам
- Запустите дескриптор ответа конца тела для ответа response
-
Чтобы обработать конец ответа для response, выполните следующие действия:
- Если установлен синхронный флаг, установите ответ на response
- Обработайте ошибки для response
- Если ответ — ошибка сети, вернитесь
- Если синхронный флаг не установлен, обновите тело ответа, используя response
- Позвольте переданному transmitted быть переданными байтами тела ответа response
- Пусть длина length будет общим байтом тела ответа response
- Если синхронный флаг не установлен, запускается событие прогресса с именем progress в this с transmitted и length (передачей и длиной)
- Установить состояние на готово done
- Снимите флаг send()
- Запустить событие с именем readystatechange в this
- Выстрелить событие прогресса с именем load в this с transmitted и length (передачей и длиной)
- Выстрелить событие прогресса с именем loadend в this с transmitted и length (передачей и длиной)
Чтобы обработать ошибки для ответа response, выполните эти шаги:
-
- Если флаг send() не установлен, вернуть
- Если установлен флаг
timeout
, выполните шаги запроса ошибки для события тайм-аута и исключения «TimeoutError» DOMException - Если ответом является ошибка сети, выполните шаги запроса ошибки для ошибки события и исключения «NetworkError» DOMException
- В противном случае, если поток тела ответа response будет ошибочным, то:
- Установить состояние на готово — done
- Снять флаг send()
- Установить ответ на сетевую ошибку
- В противном случае, если установлен флаг отмены ответа response, выполните шаги запроса ошибки для события abort и исключения «AbortError» DOMException
Шаги ошибки запроса для события event и, необязательно, исключения exception:
- Установить состояние на готово — done
- Снять флаг send()
- Установить ответ на сетевую ошибку
- Если установлен синхронный флаг, выведите исключение exception
- Запустить событие с именем readystatechange в this (Примечание: На этом этапе ясно, что синхронный флаг не установлен)
- Если флаг завершения загрузки не установлен, то:
- Установите флаг завершения загрузки
- Если установлен флаг прослушивателя загрузки, то:
- Запустите событие выполнения с именем event в этом объекте XMLHttpRequestUpload с «0» и «0»
- Вызвать событие прогресса с именем loadend для этого объекта XMLHttpRequestUpload с «0» и «0»
- Выстрелить событие с именем event в это с «0» и «0»
- Запустите событие прогресса с именем loadend в этом месте с «0» и «0»
4.5.7 Метод abort()
Для web разработчиков (ненормативно)
client . abort()
- Отменяет любую сетевую активность
Метод abort() при вызове должен выполнить следующие шаги:
- Завершить текущую выборку с установленным флагом отмены
- Если состояние opened с установленным флагом send(), headers received или loading, запустите шаги ошибки запроса для отмены события
- Если состояние выполнено done, то установите состояние неотправленным unsent и ответьте на сетевую ошибку. (Примечание: Событие readystatechange не отправляется)
4.6 Ответ (Response)
XMLHttpRequest имеет связанный ответ response. Если не указано иное, это ошибка сети
XMLHttpRequest также имеет связанные полученные байты (received bytes — последовательность байтов). Если не указано иное, это пустая последовательность байтов.
4.6.1 Атрибут responseURL
Атрибут responseURL должен возвращать пустую строку, если URL-адрес ответа имеет значение null, а его сериализация с «флагом исключения фрагмента — exclude fragment flag» установлена иначе.
4.6.2 Атрибут status
Атрибут status должен возвращать статус ответа.
4.6.3 Атрибут statusText
Атрибут statusText должен возвращать сообщение о статусе ответа.
4.6.4 Метод getResponseHeader()
Метод getResponseHeader (name) при вызове должен возвращать результат получения имени name из списка заголовков ответа.
Примечание: Fetch Standard фильтрует список заголовков ответов. [FETCH]
Пример:
Для следующего скрипта:
var client = new XMLHttpRequest();
client.open("GET", "unicorns-are-awesome.txt", true);
client.send();
client.onreadystatechange = function() {
if(this.readyState == this.HEADERS_RECEIVED) {
print(client.getResponseHeader("Content-Type"));
}
}
Функция print() будет обрабатывать что-то вроде:
text/plain; charset=UTF-8
4.6.5 Метод getAllResponseHeaders()
Последовательность байтов «a» имеет значение legacy-uppercased-byte меньше байтовой последовательности «b«, если следующие шаги возвращают true:
- Пусть A будет «a» в верхнем регистре
- Пусть B будет «b«, в верхнем регистре
- Возврат A на байт меньше, чем B
Метод getAllResponseHeaders() при вызове должен выполнить следующие шаги:
- Пусть вывод output будет пустой байтовой последовательностью.
- Пусть initialHeaders будет результатом выполнения сортировки и объединится со списком заголовков ответа.
- Пусть заголовки headers будут результатом сортировки initialHeaders в порядке возрастания, причем значение «a» будет меньше «b«, если имя «a» будет legacy-uppercased-byte меньше, чем имя «b«. (Примечание: К сожалению, это необходимо для совместимости с развернутым контентом.)
- Для каждого заголовка header в заголовках headers добавьте имя заголовка header, затем пару байтов 0x3A 0x20, затем значение заголовка header и пару байтов 0x0D 0x0A для вывода output
- Возвращение вывода output
Примечание: Fetch Standard фильтрует список заголовков ответов. [FETCH]
Пример
Для следующего скрипта:
var client = new XMLHttpRequest();
client.open("GET", "narwhals-too.txt", true);
client.send();
client.onreadystatechange = function() {
if(this.readyState == this.HEADERS_RECEIVED) {
print(this.getAllResponseHeaders());
}
}
Функция print() будет обрабатывать что-то вроде:
connection: Keep-Alive
content-type: text/plain; charset=utf-8
date: Sun, 24 Oct 2004 04:58:38 GMT
keep-alive: timeout=15, max=99
server: Apache/1.3.31 (Unix)
transfer-encoding: chunked
4.6.6 Тело ответа
Тип MIME ответа является результатом выполнения этих шагов:
- Пусть mimeType будет результатом извлечения типа MIME из списка заголовков ответа
- Если mimeType является ошибкой, установите для mimeType значение «text/xml«
- Верните mimeType
Тип MIME переопределения изначально имеет значение null и может получить значение при вызове overrideMimeType(). Конечный MIME-тип является MIME-типом с переопределением, если только он не равен NULL, в этом случае это MIME-тип ответа.
Окончательный набор символов — это возвращаемое значение этих шагов:
- Пусть label будет нулевым
- Если параметры ответа MIME-типа [«charset»] существуют, установите для него метку label
- Если существует переопределение параметров типа MIME [«charset»], установите для него метку label
- Если метка label равна нулю, вернуть ноль
- Пусть кодировка encoding будет результатом получения кодировки из метки
- Если кодировка encoding не удалась, вернуть ноль null
- Вернуть кодировку encoding
Примечание: Вышеуказанные шаги намеренно не используют окончательный тип MIME, так как это приведет к неверному результату.
Объект XMLHttpRequest имеет связанный с ним объект ответа (объект, ошибка или ноль). Если не указано иное, оно является null
Ответ arraybuffer — возвращаемое значение этих шагов:
- Установите объект ответа на новый объект ArrayBuffer, представляющий полученные байты. Если это вызывает исключение, тогда установите объект ответа на сбой и верните null (Примечание: Выделение объекта ArrayBuffer не гарантирует успеха. [ECMAscript])
- Верните объект ответа
Ответ blob — это возвращаемое значение этих шагов:
- Установите объект ответа на новый объект Blob, представляющий полученные байты с типом, установленным в окончательный тип MIME
- Верните объект ответа
Ответ document — возвращаемое значение этих шагов:
- Если тело ответа равно null, вернуть null
- Если конечный тип MIME не является типом HTML MIME или типом XML MIME, возвращает null
- Если responseType является пустой строкой, а конечный MIME-тип является HTML MIME-типом, тогда возвращается null
(Примечание: Это ограничено, чтобы responseType был «документом» для предотвращения взлома устаревшего контента) - Если конечный тип MIME является типом HTML MIME, то:
-
- Пусть charset будет финальным charset
- Если charset равен null, предварительно просканируйте первые 1024 байта полученных байтов, и если это не завершится неудачно, то пусть charset будет возвращаемым значением
- Если charset равен null, тогда установите charset в UTF-8
- Пусть document будет документом, представляющим результат анализа полученных байтов в соответствии с правилами, установленными в стандарте HTML для синтаксического анализатора HTML с отключенным сценарием и известной определенной кодировкой кодировки. [HTML]
- Пометить document как документ HTML
-
- В противном случае, пусть document будет документом, представляющим результат работы анализатора XML с отключенной поддержкой сценариев XML для полученных байтов. Если это не помогло (неподдерживаемая кодировка символов, ошибка правильности формы пространства имен и т. д.), Верните null. [HTML]
(Примечание: Упомянутые ресурсы не будут загружены, и связанный XSLT не будет применен.) - Если charset равен null, тогда установите charset в UTF-8
- Установить кодировку документа document в charset
- Установите тип содержимого документа document в окончательный тип MIME.
- Установить URL документа document для URL ответа
- Задайте в качестве источника документа document источник соответствующих настроек объекта контекста.
- Установите объект ответа на document и верните его.
Ответ JSON — это возвращаемое значение этих шагов:
- Если тело ответа равно null, вернуть null
- Пусть jsonObject будет результатом выполнения анализа JSON из байтов полученных байтов. Если это сгенерировало исключение, верните null
- Установите для объекта ответа значение jsonObject и верните его.
Текстовый ответ text — это возвращаемое значение этих шагов:
- Если тело ответа пустое, верните пустую строку
- Пусть charset будет финальным charset
- Если responseType — пустая строка, charset — null, и окончательный тип MIME — это тип XML MIME, то используйте правила, изложенные в спецификациях XML, для определения кодировки. Пусть charset будет определенной кодировкой. [XML] [XMLNS]
(Примечание: Это ограничено тем, что responseType является пустой строкой, чтобы сохранить не устаревшее responseType значение «text» простым.) - Если charset равен null, тогда установите charset в UTF-8
- Вернуть результат выполнения декодирования на полученных байтах, используя charset запасного кодирования
Примечание: Авторам настоятельно рекомендуется всегда кодировать свои ресурсы, используя UTF-8.
4.6.7 Метод overrideMimeType()
Для web разработчиков (ненормативно)
client . overrideMimeType(mime)
- Действует так, как если бы заголовок `Content-Type` для ответа был mime. (Это на самом деле не меняет заголовок, хотя.)
- Выдает исключение DOMException «InvalidStateError«, если состояние загружается loading или выполнено done
При вызове метод overrideMimeType(mime) должен выполнить следующие шаги:
- Если состояние загружается loading или выполнено done, выдается исключение DOMException «InvalidStateError»
- Установите тип переопределения MIME на результат анализа mime
- Если переопределить MIME-тип не удалось, тогда установить переопределить MIME-тип в «application/octet-stream«
4.6.8 Атрибут responseType
Для web разработчиков (ненормативно)
client . responseType [ = value ]
- Возвращает тип ответа
- Может быть установлен для изменения типа ответа. Значения: пустая строка (по умолчанию), «arraybuffer», «blob», «document», «json» и «text»
- Когда установлено: установка на «document» игнорируется, если текущий глобальный объект не является объектом Window
- Когда установлено: выдает исключение DOMException «InvalidStateError«, если состояние загружается loading или сделано done
- Когда установлено: генерирует исключение DOMException «InvalidAccessError», если установлен синхронный флаг и текущий глобальный объект является объектом Window
Атрибут responseType должен возвращать свое значение. Первоначально его значение должно быть пустой строкой.
Установка атрибута responseType должна выполнить эти шаги:
- Если текущий глобальный объект не является объектом Window и заданным значением является «document», прекратите эти шаги
- Если состояние загружается loading или выполнено done, то генерируется исключение DOMException «InvalidStateError»
- Если текущий глобальный объект является объектом Window и установлен синхронный флаг, то генерируется исключение DOMException «InvalidAccessError»
- Установите значение атрибута responseType для данного значения
4.6.9 Атрибут response
Для web разработчиков (ненормативно)
client . response
- Возвращает тело ответа
Атрибут response должен возвращать результат выполнения этих шагов:
Если responseType — пустая строка или «text»
- Если состояние не loading или не done, вернуть пустую строку
- Вернуть текстовый ответ
В противном случае
- Если состояние не done, вернуть null
- Если объектом ответа является сбой, вернуть null
- Если объект ответа не null, вернуть его
- Если responseType является «arraybuffer» — Вернуть ответ массива-буфера
Если responseType является «blob» — Верните ответ блоб
Если responseType является «document» — Верните ответ документа
Если responseType является «JSON» — Вернуть ответ JSON
4.6.10 Атрибут responseText
Для web разработчиков (ненормативно)
client . responseText
- Возвращает текстовый ответ
- Выдает исключение DOMException «InvalidStateError», если responseType не является пустой строкой или «text»
Атрибут responseText должен возвращать результат выполнения этих шагов:
- Если responseType не является пустой строкой или «text», то генерируется исключение DOMException «InvalidStateError»
- Если состояние не loading или не done, вернуть пустую строку
- Вернуть текстовый ответ
4.6.11 Атрибут responseXML
Для web разработчиков (ненормативно)
client . responseXML
- Возвращает ответ документом
- Выдает исключение DOMException «InvalidStateError», если responseType не является пустой строкой или «document»
Атрибут responseXML должен возвращать результат выполнения этих шагов:
- Если responseType не является пустой строкой или «document», тогда генерируется исключение DOMException «InvalidStateError»
- Если состояние не выполнено, вернуть null
- Утверждение: объект ответа не является ошибкой
- Если объект ответа не равен null, вернуть его
- Верните ответ документа
4.7 Краткое изложение событий
Этот раздел ненормативнен
Следующие события отправляются объектам XMLHttpRequest или XMLHttpRequestUpload:
Название события | Интерфейс | Отправляется, когда … | |
---|---|---|---|
readystatechange | Event | Атрибут readyState меняет значение, кроме случаев, когда он изменяется на UNSENT | |
loadstart |
|
Выборка начинается | |
progress |
|
Передаются данные | |
abort |
|
Когда выборка была прервана. Например, вызывая метод abort() | |
error |
|
Выборка не удалась | |
load |
|
Выборка прошла успешно | |
timeout |
|
Указанный автором тайм-аут прошел до завершения выборки | |
loadend |
|
Выборка завершена (успех или неудача) |
4.8 Интеграция с политикой функций
Эта спецификация определяет управляемую политикой функцию, обозначенную строкой «sync-xhr». Список разрешений по умолчанию *.
5 Интерфейс FormData
typedef (File or USVString) FormDataEntryValue;
[Exposed=(Window,Worker)]
interface FormData {
constructor(optional HTMLFormElement form);
void append(USVString name, USVString value);
void append(USVString name, Blob blobValue, optional USVString filename);
void delete(USVString name);
FormDataEntryValue? get(USVString name);
sequence getAll(USVString name);
boolean has(USVString name);
void set(USVString name, USVString value);
void set(USVString name, Blob blobValue, optional USVString filename);
iterable<USVString, FormDataEntryValue>;
};
Каждый объект FormData имеет связанный список записей (список записей). Это изначально пустой список.
Запись entry состоит из имени name и значения value.
В целях взаимодействия с другими алгоритмами имя файла записи является пустой строкой, если значение не является объектом File, а в противном случае его имя файла является значением атрибута name значения элемента.
Чтобы создать запись для имени name, значения value и, необязательно, имени файла filename, выполните следующие действия:
- Пусть entry будет новой записью
- Установите имя entry на name
- Если значение является объектом Blob, а не объектом File, тогда установите значение для нового объекта File, представляющего те же байты, значение атрибута name которых равно «blob»
- Если value является (сейчас) объектом File и задано имя файла filename, тогда установите значение value для нового объекта File, представляющего те же байты, чьим значением атрибута name является filename
- Установите значение entry в value.
- Верните запись entry
Конструктор FormData (form) должен выполнить следующие шаги:
- Пусть fd будет новым объектом FormData
- Если форма form дается, то:
-
- Пусть list будет результатом построения списка записей для form
- Если list имеет значение null, тогда генерируется исключение DOMException «InvalidStateError»
- Установите список записей fd в list
-
- Верните fd
Методы append(name, value) и append(name, blobValue, filename) при вызове должны выполнить следующие шаги:
- Пусть value будет значением, если оно задано, и blobValue в противном случае (если не задано)
- Пусть entry будет результатом создания записи с именем name, значением value и именем файла filename, если дано
- Добавить entry в список записей объекта контекста
Примечание: Причина, по которой существует аргумент с именем value и blobValue, связана с ограничением программного обеспечения для редактирования, используемого для написания стандарта XMLHttpRequest.
Метод delete(name) при вызове должен удалить все записи, имя которых является именем name из списка записей объекта контекста.
Метод get(name) при вызове должен возвращать значение первой записи, именем которой является name из списка записей объекта контекста, и null в противном случае.
Метод getAll(name) при вызове должен возвращать значения всех записей, чье имя — это name по порядку, из списка записей объекта контекста, а в противном случае — из пустого списка.
Метод has(name) при вызове должен возвращать значение true, если в списке записей объекта контекста есть запись, имя которой равно name, а в противном случае — false.
Методы set(name, value) и set(name, blobValue, filename) при вызове должны выполнить следующие шаги:
- Пусть value будет значением, если оно задано, и blobValue в противном случае
- Пусть entry будет результатом создания записи с именем name, значением value и именем файла filename, если оно задано
- Если в списке записей объекта контекста есть записи с именем name, замените первую такую запись на entry и удалите остальные
- В противном случае добавьте entry в список записей объекта контекста
Примечание: Причина, по которой существует аргумент с именем value и blobValue, связана с ограничением программного обеспечения для редактирования, используемого для написания стандарта XMLHttpRequest.
Итерируемые пары значений являются записями списка записей объекта контекста, ключом является имя, а значением — значение.
6 Интерфейс ProgressEvent
[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface ProgressEvent : Event {
constructor(DOMString type, optional ProgressEventInit eventInitDict = {});
readonly attribute boolean lengthComputable;
readonly attribute unsigned long long loaded;
readonly attribute unsigned long long total;
};
dictionary ProgressEventInit : EventInit {
boolean lengthComputable = false;
unsigned long long loaded = 0;
unsigned long long total = 0;
};
События, использующие интерфейс ProgressEvent, указывают на некоторую прогрессию.
Атрибуты lengthComputable, loaded и total должны возвращать значение, которому они были инициализированы.
6.1 Запуск событий с использованием интерфейса ProgressEvent
Вызвать событие прогресса с именем «e» на цели target, с учетом передачи transmitted и длины length, означает запустить событие с именем «e» на цели, используя ProgressEvent, с атрибутом loaded, инициализированным для transmitted, и, если length не равна 0, с атрибутом lengthComputable, инициализированным как true и атрибут total, инициализированный по length.
6.2 Предлагаемые имена для событий с использованием интерфейса ProgressEvent
Не нормативный раздел
Предлагаемые значения атрибута type для использования с событиями с использованием интерфейса ProgressEvent приведены в таблице ниже. Редакторы спецификаций могут свободно настраивать детали для своих конкретных сценариев, хотя настоятельно рекомендуется обсудить их использование с сообществом WHATWG, чтобы обеспечить вклад людей, знакомых с предметом.
Значение атрибута «type» | Описание | Периоды | Когда? |
---|---|---|---|
loadstart |
Прогресс начался | Однажды | Впервые |
progress |
В ходе выполнения | Один раз или больше | После loadstart был отправлен. |
error |
Прогрессия не удалась | Ноль или один раз (взаимоисключающие) | После того, как последние прогрессы были отправлены. |
abort |
Прогрессия прекращена | ||
timeout |
Прогрессирование прекращается из-за истечения заданного времени | ||
load |
Прогрессия успешна | ||
loadend |
Прогресс остановился | Однажды | Послеодного из error , abort , timeout or load было отправлено. |
Типы событий error, abort, timeout и load являются взаимоисключающими.
Во всей веб-платформе типы событий error, abort, timeout и load имеют свои пузырьки/всплытие (bubbles) и отменяемые атрибуты (cancelable), инициализированные как false, поэтому для согласованности все события, использующие интерфейс ProgressEvent, делают то же самое.
6.3 Соображения безопасности
Для запросов из разных источников какой-либо вариант, например, протокол CORS, определенный в стандарте Fetch, должен использоваться до того, как будут отправлены события, использующие интерфейс ProgressEvent, так как будет раскрыта информация (например, размер), которая не может быть получена иначе. [FETCH]
6.4 Пример
В этом примере XMLHttpRequest в сочетании с концепциями, определенными в предыдущих разделах, и HTML-элемент прогресса используются вместе для отображения процесса извлечения ресурса.
<!DOCTYPE html>
<title>Waiting for Magical Unicorns</title>
<progress id=p></progress>
<script>
var progressBar = document.getElementById("p"),
client = new XMLHttpRequest()
client.open("GET", "magical-unicorns")
client.onprogress = function(pe) {
if(pe.lengthComputable) {
progressBar.max = pe.total
progressBar.value = pe.loaded
}
}
client.onloadend = function(pe) {
progressBar.value = pe.loaded
}
client.send()
</script>
Полностью рабочий код, конечно, будет более сложным и будет иметь дело с большим количеством сценариев, таких как сетевые ошибки или конечный пользователь, завершающий запрос.
Благодарности
Благодаря Аддисону Филлипсу, Адриану Бейтману, Ахмеду Камелю, Алану Томасу, Алексу Хопманну, Алексу Винсенту, Алексею Проскурякову, Али Алаббасу, Андреа Маркезини, Асбьёрну Ульсбергу, Бертрану Гуай-Паке, Бьерну Хёрманну, Борису Збарски, Кейтлин Поттер, Кэмерон, Камерон (Ченг-Ю Бай), Крис Маррин, Кристоф Джолиф, Чарльз МакКатиНевиль, Дэн Виншип, Дэвид Андерссон, Дэвид Фланаган, Дэвид Хасетер, Дэвид Левин, Дин Джексон, Денис Сюро, Доменик Деникола, Доминик Роттшес, Дуг Шеперс, Дуглас Ливингстон, Эугл Шпрен, Эллиот Гарольд, Эрик Лоуренс, Эрик Урхан, Эрик Арвидссон, Эрик Дальстрем, Ферас Мусса, Гидеон Кон, Гленн Адамс, Горм Хауг Эриксен, Грегори Терзиан, Хокон Вий Ли, Халворд Р. М. Стин, Анри Сивонуб, Хиакеш, Хироши Ян Клелланд, Ян Дэвис, Ян Хиксон, Иван Херман, Джейк Арчибальд, Джаред Джейкобс, Джарред Николс, Джефф Уолден, Дженс Линдстрем, Джим Диган, Джим Лей, Джо Фарро, Джонас Сикинг, Джулиан Решке, 송정기 (Jungkee Song), 송정기 Кан-Хао Лу), Ка Дубл, Кит Юнг, 田村 健 人 (Кент Тамура), Лахлан Хант, Мачей Стаховяк, Магнус Кристиансен, Маниш Горегаокар, Марк Хэдли, Маркос Касерес, Марк Бейкер, Марк Бирбек, Марк Ноттингем, Марк С. Миллер, Мартин Хассман, Майк Пенниси, Мохамед Зергауи, Ms2ger, Один Хёрт Омдал, Олли Петтай, Павел Гловаки, Питер Мишо, Филипп Ягенштедт, Филип Тейлор, Робин Берджон, Руне Ф. Халворсен, Рууд Стелтенпул, Рио Онодера, Самоудуалтумар Седон, Седондуду Сер Сигбьерн Финне, Саймон Питерс, Стюарт Броди, Сунава Датта, Такеши Куросава, Такеши Йошино, Томас Росслер, Томас Вишневски, Том Маглиери, Трэвис Лейтхед, Тройной подчеркивание, Ярон Тауски, Иегуда Кац, Юнен Тоубен и Юнен Фабет это стандарт.
Особая благодарность сотрудникам Microsoft, которые впервые реализовали интерфейс XMLHttpRequest, который впервые был широко развернут браузером Windows Internet Explorer.
Особая благодарность Иану Хиксону за составление первоначальной версии этой спецификации в стандарте HTML (затем Web Applications 1.0). [HTML]
Особая благодарность W3C SVG WG за разработку оригинального класса ProgressEvent в составе SVG Micro DOM.
Этот стандарт написан Анн ван Кестерен (Mozilla, annevk@annevk.nl).
Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). Это произведение лицензировано под международной лицензией Creative Commons Attribution 4.0.
Индекс
Термины, определенные в данной спецификации
«», in §4
abort, in §4.7
abort(), in §4.5.7
append(name, blobValue), in §5
append(name, blobValue, filename), in §5
append(name, value), in §5
«arraybuffer», in §4
arraybuffer response, in §4.6.6
author request headers, in §4.5
«blob», in §4
blob response, in §4.6.6
constructor()
constructor for FormData, in §5
constructor for XMLHttpRequest, in §4.1
constructor(form), in §5
constructor(type), in §6
constructor(type, eventInitDict), in §6
create an entry, in §5
delete(name), in §5
«document», in §4
document response, in §4.6.6
DONE, in §4.4
entries, in §5
entry, in §5
entry list, in §5
error, in §4.7
final charset, in §4.6.6
final MIME type, in §4.6.6
fire a progress event, in §6.1
FormData, in §5
FormData(), in §5
FormDataEntryValue, in §5
FormData(form), in §5
getAll(name), in §5
getAllResponseHeaders(), in §4.6.5
get(name), in §5
getResponseHeader(name), in §4.6.4
handle errors, in §4.5.6
handle response end-of-body, in §4.5.6
has(name), in §5
HEADERS_RECEIVED, in §4.4
«json», in §4
JSON response, in §4.6.6
legacy-uppercased-byte less than, in §4.6.5
lengthComputable
attribute for ProgressEvent, in §6
dict-member for ProgressEventInit, in §6
load, in §4.7
loaded
attribute for ProgressEvent, in §6
dict-member for ProgressEventInit, in §6
loadend, in §4.7
LOADING, in §4.4
loadstart, in §4.7
name, in §5
onabort, in §4.3
onerror, in §4.3
onload, in §4.3
onloadend, in §4.3
onloadstart, in §4.3
onprogress, in §4.3
onreadystatechange, in §4.3
ontimeout, in §4.3
OPENED, in §4.4
open(method, url), in §4.5.1
open(method, url, async), in §4.5.1
open(method, url, async, username), in §4.5.1
open(method, url, async, username, password), in §4.5.1
override MIME type, in §4.6.6
overrideMimeType(mime), in §4.6.7
progress, in §4.7
ProgressEvent, in §6
ProgressEventInit, in §6
ProgressEvent(type), in §6
ProgressEvent(type, eventInitDict), in §6
readyState, in §4.4
readystatechange, in §4.7
received bytes, in §4.6
request body, in §4.5
request error steps, in §4.5.6
request method, in §4.5
request URL, in §4.5
response
attribute for XMLHttpRequest, in §4.6.9
definition of, in §4.6
response MIME type, in §4.6.6
response object, in §4.6.6
responseText, in §4.6.10
responseType, in §4.6.8
responseURL, in §4.6.1
responseXML, in §4.6.11
send(), in §4.5.6
send(body), in §4.5.6
send() flag, in §4
set(name, blobValue), in §5
set(name, blobValue, filename), in §5
set(name, value), in §5
setRequestHeader(name, value), in §4.5.2
state, in §4
status, in §4.6.2
statusText, in §4.6.3
synchronous flag, in §4.5
sync-xhr, in §4.8
«text», in §4
text response, in §4.6.6
timed out flag, in §4.5
timeout
attribute for XMLHttpRequest, in §4.5.3
event for XMLHttpRequest, in §4.7
total
attribute for ProgressEvent, in §6
dict-member for ProgressEventInit, in §6
UNSENT, in §4.4
upload, in §4.5.5
upload complete flag, in §4.5
upload listener flag, in §4.5
value, in §5
withCredentials, in §4.5.4
XMLHttpRequest, in §4
XMLHttpRequest(), in §4.1
XMLHttpRequestEventTarget, in §4
XMLHttpRequestResponseType, in §4
XMLHttpRequestUpload, in §4
Термины, определенные ссылкой
[DOM] defines the following terms:
Document
Event
EventInit
EventTarget
bubbles
cancelable
content type
context object
dispatch
document
encoding
event
event listener
fire an event
html document
origin
type
url
xml document
[DOMPS] defines the following terms:
fragment serializing algorithm
[ENCODING] defines the following terms:
decode
getting an encoding
utf-8
utf-8 encode
[FEATURE-POLICY] defines the following terms:
default allowlist
policy-controlled feature
[FETCH] defines the following terms:
XMLHttpRequestBodyInit
aborted flag
body (for response)
client
combine
contains
cors protocol
cors-preflight request
credentials
credentials mode
done flag
errored
extract
extracting a mime type
fetch
forbidden header name
forbidden method
get
get a reader
header
header list (for response)
method (for request)
mode
name
network error
normalize (for method)
process request body
process request end-of-body
process response
read a chunk
read all bytes
request
set
sort and combine
status
status message
stream
synchronous flag
terminated
total bytes
transmitted bytes
unsafe-request flag
url (for response)
use-cors-preflight flag
use-url-credentials flag
value
[FILEAPI] defines the following terms:
Blob
File
name
type
[HTML] defines the following terms:
EventHandler
HTMLFormElement
Window
a known definite encoding
allowed to use
api base url
api url character encoding
constructing the entry list
current global object
event handler
event handler event type
fully active
in parallel
networking task source
origin
prescan a byte stream to determine its encoding
progress
queue a task
relevant settings object
responsible document
same origin
task
xml parser
xml scripting support disabled
[INFRA] defines the following terms:
append
ascii case-insensitive
byte less than
byte sequence
byte-case-insensitive
byte-uppercase
convert
exist
for each
list
parse json from bytes
remove
replace
set
sorting
[MIMESNIFF] defines the following terms:
html mime type
parameters
parse a mime type
parse a mime type from bytes
serialize a mime type to bytes
xml mime type
[URL] defines the following terms:
host
password
set the password
set the username
url parser
url serializer
username
[WEBIDL] defines the following terms:
AbortError
ArrayBuffer
ByteString
DOMException
DOMString
Exposed
InvalidAccessError
InvalidStateError
NetworkError
SameObject
SecurityError
SyntaxError
TimeoutError
USVString
boolean
throw
unsigned long
unsigned long long
unsigned short
value pairs to iterate over
Ссылки
Нормативные ссылки
[DOM] — Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[DOMPS] — Travis Leithead. DOM Parsing and Serialization. URL: https://w3c.github.io/DOM-Parsing/
[ECMASCRIPT] — ECMAScript Language Specification. URL: https://tc39.es/ecma262/
[ENCODING] — Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
[FEATURE-POLICY] — Ian Clelland. Feature Policy. URL: https://w3c.github.io/webappsec-feature-policy/
[FETCH] — Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[FILEAPI] — Marijn Kruisselbrink; Arun Ranganathan. File API. URL: https://w3c.github.io/FileAPI/
[HTML] — Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[HTTP] — R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
[INFRA] — Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[MIMESNIFF] — Gordon P. Hemsley. MIME Sniffing Standard. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[RFC2119] — S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[URL] — Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WEBIDL] — Boris Zbarsky. Web IDL. URL: https://heycam.github.io/webidl/
[XML] — Tim Bray; et al. Extensible Markup Language (XML) 1.0 (Fifth Edition). 26 November 2008. REC. URL: https://www.w3.org/TR/xml/
[XMLNS] — Tim Bray; et al. Namespaces in XML 1.0 (Third Edition). 8 December 2009. REC. URL: https://www.w3.org/TR/xml-names/
Индекс IDL
[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequestEventTarget : EventTarget {
// event handlers
attribute EventHandler onloadstart;
attribute EventHandler onprogress;
attribute EventHandler onabort;
attribute EventHandler onerror;
attribute EventHandler onload;
attribute EventHandler ontimeout;
attribute EventHandler onloadend;
};
[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
};
enum XMLHttpRequestResponseType {
"",
"arraybuffer",
"blob",
"document",
"json",
"text"
};
[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequest : XMLHttpRequestEventTarget {
constructor();
// event handler
attribute EventHandler onreadystatechange;
// states
const unsigned short UNSENT = 0;
const unsigned short OPENED = 1;
const unsigned short HEADERS_RECEIVED = 2;
const unsigned short LOADING = 3;
const unsigned short DONE = 4;
readonly attribute unsigned short readyState;
// request
void open(ByteString method, USVString url);
void open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null);
void setRequestHeader(ByteString name, ByteString value);
attribute unsigned long timeout;
attribute boolean withCredentials;
[SameObject] readonly attribute XMLHttpRequestUpload upload;
void send(optional (Document or XMLHttpRequestBodyInit)? body = null);
void abort();
// response
readonly attribute USVString responseURL;
readonly attribute unsigned short status;
readonly attribute ByteString statusText;
ByteString? getResponseHeader(ByteString name);
ByteString getAllResponseHeaders();
void overrideMimeType(DOMString mime);
attribute XMLHttpRequestResponseType responseType;
readonly attribute any response;
readonly attribute USVString responseText;
[Exposed=Window] readonly attribute Document? responseXML;
};
typedef (File or USVString) FormDataEntryValue;
[Exposed=(Window,Worker)]
interface FormData {
constructor(optional HTMLFormElement form);
void append(USVString name, USVString value);
void append(USVString name, Blob blobValue, optional USVString filename);
void delete(USVString name);
FormDataEntryValue? get(USVString name);
sequence getAll(USVString name);
boolean has(USVString name);
void set(USVString name, USVString value);
void set(USVString name, Blob blobValue, optional USVString filename);
iterable<USVString, FormDataEntryValue>;
};
[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface ProgressEvent : Event {
constructor(DOMString type, optional ProgressEventInit eventInitDict = {});
readonly attribute boolean lengthComputable;
readonly attribute unsigned long long loaded;
readonly attribute unsigned long long total;
};
dictionary ProgressEventInit : EventInit {
boolean lengthComputable = false;
unsigned long long loaded = 0;
unsigned long long total = 0;
};