XMLHttpRequest

1. 介绍

本节为非规范性内容。

XMLHttpRequest 对象是一个用于获取资源的API。

名称XMLHttpRequest 是历史遗留的，名称本身与其功能无关。

function processData(data) {
  // 处理数据
}

function handler() {
  if(this.status == 200 &&
    this.responseXML != null &&
    this.responseXML.getElementById('test').textContent) {
    // 成功！
    processData(this.responseXML.getElementById('test').textContent);
  } else {
    // 发生错误
    …
  }
}

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工作中定义的。（基于微软多年前的实现。）它于2006年移交给W3C。扩展功能（如进度事件和跨域请求）被单独的草案（XMLHttpRequest Level 2）开发，直到2011年底，此时两个草案合并，XMLHttpRequest 从标准角度再次成为单一实体。到2012年底，它又回到了WHATWG。

当前草案的讨论可以在以下邮件列表档案中找到：

• whatwg@whatwg.org
• public-webapps@w3.org
• public-webapi@w3.org
• public-appformats@w3.org

2. 术语

本规范依赖于Infra标准。[INFRA]

本规范使用来自DOM、DOM解析与序列化、编码、Fetch、文件API、HTML、URL、Web IDL和XML的术语。

[DOM] [DOM-PARSING] [ENCODING] [FETCH] [FILEAPI] [HTML] [URL] [WEBIDL] [XML] [XML-NAMES]

3. 接口 XMLHttpRequest

[Exposed=(Window,DedicatedWorker,SharedWorker)]
interface XMLHttpRequestEventTarget : EventTarget {
  // 事件处理程序
  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();

  // 事件处理程序
  attribute EventHandler onreadystatechange;

  // 状态
  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;

  // 请求
  undefined open(ByteString method, USVString url);
  undefined open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null);
  undefined setRequestHeader(ByteString name, ByteString value);
           attribute unsigned long timeout;
           attribute boolean withCredentials;
  [SameObject] readonly attribute XMLHttpRequestUpload upload;
  undefined send(optional (Document or XMLHttpRequestBodyInit)? body = null);
  undefined abort();

  // 响应
  readonly attribute USVString responseURL;
  readonly attribute unsigned short status;
  readonly attribute ByteString statusText;
  ByteString? getResponseHeader(ByteString name);
  ByteString getAllResponseHeaders();
  undefined overrideMimeType(DOMString mime);
           attribute XMLHttpRequestResponseType responseType;
  readonly attribute any response;
  readonly attribute USVString responseText;
  [Exposed=Window] readonly attribute Document? responseXML;
};

一个XMLHttpRequest 对象关联了：

上传对象

一个XMLHttpRequestUpload 对象。

状态

其中之一：未发送、已打开、头信息已接收、加载中、已完成； 初始状态为未发送。

send()标志

一个标志，初始未设置。

超时时间

一个无符号整数，初始为0。

跨域凭据

一个布尔值，初始为false。

请求方法

一个方法。

请求URL

一个URL。

自定义请求头

一个头信息列表，初始为空。

请求体

初始为null。

同步标志

一个标志，初始未设置。

上传完成标志

一个标志，初始未设置。

上传监听标志

一个标志，初始未设置。

超时标志

一个标志，初始未设置。

响应

一个响应，初始为网络错误。

接收的字节

一个字节序列，初始为空字节序列。

响应类型

以下之一：空字符串、"arraybuffer"、"blob"、 "document"、"json"和"text"；初始为空字符串。

响应对象

一个对象、失败或null，初始为null。

请求控制器

一个请求控制器，初始为一个新的请求控制器。在send() 方法被调用时会设置为一个有用的请求控制器，但为简单起见，它总是持有一个请求控制器。

覆盖的MIME类型

一个MIME类型或null，初始为null。在调用overrideMimeType() 时可以获取值。

3.1. 构造函数

client = new XMLHttpRequest()

返回一个新的XMLHttpRequest 对象。

new XMLHttpRequest() 构造函数的步骤如下：

1. 将this的上传对象设置为一个新的 XMLHttpRequestUpload对象。

3.2. 垃圾回收

当XMLHttpRequest 对象的状态为已打开，且设置了send()标志， 或者状态为头信息已接收或加载中，并且注册了一个或多个事件监听器时，该对象不能被垃圾回收。事件类型为：readystatechange、 progress、 abort、 error、 load、 timeout、 和loadend。

如果一个XMLHttpRequest 对象在其连接仍然打开的情况下被垃圾回收，用户代理必须终止该XMLHttpRequest 对象的请求控制器。

3.3. 事件处理程序

以下是事件处理程序（及其对应的事件类型） ，在继承自XMLHttpRequestEventTarget接口的对象上必须作为属性支持：

以下是事件处理程序（及其对应的事件类型），仅在XMLHttpRequest 对象上作为属性支持：

3.4. 状态

client . readyState

返回client的状态。

readyState获取步骤如下，返回表格第二列的值，对应第一列中this的状态：

3.5. 请求

在XMLHttpRequestUpload 对象上注册一个或多个事件监听器将导致一个CORS预检请求。（这是因为注册事件监听器会导致上传监听标志被设置，而这会导致使用CORS预检标志被设置。）

3.5.1. open()方法

client . open(method, url [, async = true [, username = null [, password = null]]])

设置请求方法，请求URL，以及同步标志。

如果method不是有效方法，或者url无法解析，则抛出"SyntaxError"DOMException。

如果method与`CONNECT`、`TRACE`或`TRACK`不区分大小写匹配，则抛出"SecurityError"DOMException。

如果async为false，当前全局对象是Window对象，且timeout属性不为零，或者responseType属性不为空，则抛出"InvalidAccessError"DOMException。

在非工作者环境中的同步XMLHttpRequest正在逐步从Web平台移除，因为它对终端用户体验有不利影响。（这是一个需要多年才能完成的过程。）开发者不得在Window对象作为当前全局对象时传递async参数为false。用户代理强烈建议在开发者工具中对此类用法发出警告，并可尝试抛出一个"InvalidAccessError"DOMException。

open(method, url)和open(method, url, async, username, password)方法的步骤如下：

1. 如果this的相关全局对象是一个Window对象，并且其相关Document不是完全活动状态，则抛出一个"InvalidStateError" DOMException。

2. 如果method不是有效方法，则抛出一个"SyntaxError"DOMException。

3. 如果method是一个禁用方法，则抛出一个"SecurityError"DOMException。

4. 规范化method。

5. 将parsedURL设置为通过编码解析URL url的结果，相对于this的相关设置对象。

6. 如果parsedURL解析失败，则抛出一个"SyntaxError"DOMException。

7. 如果未指定async参数，则将async设置为true，并将username和password设置为null。

   遗憾的是，遗留内容阻止了将async参数为undefined的情况与省略该参数视为相同。

8. 如果parsedURL的主机非空，则：

   1. 如果username参数不为null，设置用户名为parsedURL和username。

   2. 如果password参数不为null，设置密码为parsedURL和password。

9. 如果async为false，当前全局对象是一个Window对象，并且this的timeout不为0，或者this的response type不为空，则抛出一个"InvalidAccessError"DOMException。

10. 终止this的fetch控制器。

    此时可能仍有一个fetch正在进行。

11. 将对象相关的变量设置如下：

    • 取消设置this的send()标志。

    • 取消设置this的上传监听器标志。

    • 将this的请求方法设置为method。

    • 将this的请求URL设置为parsedURL。

    • 如果async为false，设置this的同步标志；否则取消设置this的同步标志。

    • 清空this的作者请求头。

    • 将this的响应设置为网络错误。

    • 将this的接收的字节设置为空字节序列。

    • 将this的响应对象设置为null。

    覆盖的MIME类型不会在此被覆盖，因为overrideMimeType()方法可以在open()方法之前调用。

12. 如果this的状态不是opened，则：

    1. 将this的状态设置为opened。

    2. 触发一个事件，事件名为readystatechange，在this上。

定义了两个open()方法的原因是由于编写XMLHttpRequest标准时使用的编辑软件的限制。

3.5.2. setRequestHeader() 方法

client . setRequestHeader(name, value)

将一个值追加到现有请求头，或添加一个新的请求头。

如果状态不是opened，或send()标志已设置，则抛出 "InvalidStateError" DOMException。

如果name不是一个头名称，或者value不是头值，则抛出"SyntaxError" DOMException。

setRequestHeader(name, value) 方法必须按以下步骤执行：

1. 如果this的 状态不是opened，则抛出 "InvalidStateError" DOMException。

2. 如果this的 send()标志已设置，则抛出 "InvalidStateError" DOMException。

3. 规范化 value。

4. 如果name不是头名称，或value不是头值，则抛出 "SyntaxError" DOMException。

   空字节序列表示空的头值。

5. 如果 (name, value) 是一个禁止的请求头，则返回。

6. 合并 (name, value) 到this的作者请求头。

// 下面的脚本：
var client = new XMLHttpRequest();
client.open('GET', 'demo.cgi');
client.setRequestHeader('X-Test', 'one');
client.setRequestHeader('X-Test', 'two');
client.send();

// ……结果发送了如下头：
// X-Test: one, two

3.5.3. timeout 获取器和设置器

client . timeout

可以设置为以毫秒为单位的时间。当设置为非零值时，在指定时间过去后，如果fetch 还没有完成，并且this的同步标志未设置，则会触发一个timeout事件，否则将抛出一个 "TimeoutError" DOMException。

设置时：如果同步标志设置了，并且当前全局对象是Window对象，则抛出一个 "InvalidAccessError" DOMException。

timeout 获取器步骤为返回this的timeout。

timeout 设置器步骤为：

1. 如果当前全局对象是Window对象，并且this的同步标志设置了，则抛出 "InvalidAccessError" DOMException。

2. 设置this的timeout为给定值。

这意味着timeout 属性可以在fetch进行过程中被设置。如果发生这种情况，仍然会相对于fetch的开始时间进行计时。

3.5.4. withCredentials 获取器和设置器

client . withCredentials

在跨域请求中，当凭证被包含时为 true，当它们被排除并且响应中忽略 cookie 时为 false。默认值为 false。

设置时：如果状态不是 unsent 或 opened，或者send() 标志已设置，则抛出 "InvalidStateError" DOMException。

withCredentials 获取器步骤为返回this的跨域凭证。

withCredentials 设置器步骤为：

1. 如果this的状态不是 unsent 或 opened，则抛出 "InvalidStateError" DOMException。

2. 如果this的send() 标志已设置，则抛出 "InvalidStateError" DOMException。

3. 设置this的跨域凭证为给定值。

3.5.5. upload 获取器

client . upload

返回关联的 XMLHttpRequestUpload 对象。它可以用于在数据传输到服务器时收集传输信息。

upload 获取器步骤是返回 this 的 上传对象。

3.5.6. send() 方法

client . send([body = null])

启动请求。body 参数提供了 请求体（如果有的话）， 如果 请求方法是 GET 或 HEAD，则忽略该参数。

如果 状态 不是 opened 或者 send() 标志已设置，抛出 "InvalidStateError" DOMException。

send(body) 方法的步骤为：

1. 如果 this 的 state 不是 opened，则 抛出 "InvalidStateError" DOMException。

2. 如果 this 的 send() 标志已设置， 则 抛出 "InvalidStateError" DOMException。

3. 如果 this 的 请求方法 是 `GET` 或 `HEAD`，则将 body 设置为 null。

4. 如果 body 不是 null，则：

   1. 让 extractedContentType 为 null。

   2. 如果 body 是一个 Document，则将 this 的 请求体 设置为 body，序列化，转换，并以 UTF-8 编码。

   3. 否则：

      1. 让 bodyWithType 成为安全提取 body 的结果。

      2. 将 this 的 请求体 设置为 bodyWithType 的 body。

      3. 将 extractedContentType 设置为 bodyWithType 的 类型。

   4. 让 originalAuthorContentType 成为 获取 `Content-Type` 从 this 的 作者请求头 的结果。

   5. 如果 originalAuthorContentType 不为 null，则：

      1. 如果 body 是一个 Document 或一个 USVString，则：

         1. 让 contentTypeRecord 成为 解析 originalAuthorContentType 的结果。

         2. 如果 contentTypeRecord 不是失败，contentTypeRecord 的 参数["charset"] 存在， 且 参数["charset"] 不是 ASCII不区分大小写匹配 "UTF-8"，则：

            1. 设置 contentTypeRecord 的 参数["charset"] 为 "UTF-8"。

            2. 让 newContentTypeSerialized 成为 序列化 contentTypeRecord 的结果。

            3. 设置 (`Content-Type`, newContentTypeSerialized) 到 this 的 作者请求头 中。

   6. 否则：

      1. 如果 body 是一个 HTML文档，则 设置 (`Content-Type`， `text/html;charset=UTF-8`) 到 this 的 作者请求头 中。

      2. 否则，如果 body 是一个 XML文档，则 设置 (`Content-Type`， `application/xml;charset=UTF-8`) 到 this 的 作者请求头 中。

      3. 否则，如果 extractedContentType 不为 null，则 设置 (`Content-Type`， extractedContentType) 到 this 的 作者请求头 中。

5. 如果一个或多个事件监听器被注册到 this 的 上传对象，则设置 this 的 上传监听器标志。

6. 让 req 成为一个新的 请求，初始化如下：

   方法

   此的 请求方法。

   URL

   此的 请求 URL。

   头列表

   此的 作者请求头。

   不安全请求标志

   设置。

   请求体

   此的 请求体。

   客户端

   此的 相关设置对象。

   模式

   "cors"。

   使用 CORS 预检标志

   如果 此的 上传监听器标志已设置。

   凭证模式

   如果 此的 跨源凭证 为 true，则 "include"； 否则 "same-origin"。

   使用 URL 凭证标志

   如果 此的 请求 URL 包括凭证。

   发起者类型

   "xmlhttprequest"。

7. 取消设置 此的 上传完成标志。

8. 取消设置 此的 超时标志。

9. 如果 req 的 请求体为 null，则设置 此的 上传完成标志。

10. 设置 此的 send()标志。

11. 如果 此的 同步标志未设置，则：

    1. 触发进度事件名为 loadstart 在 此，并传递 0 和 0。

    2. 让 requestBodyTransmitted 为 0。

    3. 让 requestBodyLength 为 req 的 请求体的 长度，如果 req 的 请求体非空；否则为 0。

    4. 断言：requestBodyLength 是一个整数。

    5. 如果 此的 上传完成标志未设置且 此的 上传监听器标志已设置，则 触发进度事件名为 loadstart 在 此的 上传对象，并传递 requestBodyTransmitted 和 requestBodyLength。

    6. 如果 此的 状态不是 已打开，或 此的 send() 标志未设置，则返回。

    7. 让 processRequestBodyChunkLength，给定一个 bytesLength，执行以下步骤：

       1. 将 requestBodyTransmitted 增加 bytesLength。

       2. 如果自上次调用这些步骤以来大约没有经过 50 毫秒，则返回。

       3. 如果 此的 上传监听器标志已设置，则 触发一个进度事件名为 progress 在 此的 上传对象，传递 requestBodyTransmitted 和 requestBodyLength。

       这些步骤仅在传输新字节时调用。

    8. 让 processRequestEndOfBody 执行以下步骤：

       1. 设置 此的 上传完成标志。

       2. 如果 此的 上传监听器标志未设置，则返回。

       3. 触发一个进度事件名为 progress 在 此的 上传对象，传递 requestBodyTransmitted 和 requestBodyLength。

       4. 触发一个进度事件名为 load 在 此的 上传对象，传递 requestBodyTransmitted 和 requestBodyLength。

       5. 触发一个进度事件名为 loadend 在 此的 上传对象，传递 requestBodyTransmitted 和 requestBodyLength。

    9. 让 processResponse，给定一个 response，执行以下步骤：

       1. 将 此的 响应 设置为 response。

       2. 处理错误 对 此。

       3. 如果 此的 响应 是一个 网络错误，则返回。

       4. 设置 此的 状态 为 头接收。

       5. 触发一个事件 名为 readystatechange 在 此。

       6. 如果 此的 状态 不是 头接收，则返回。

       7. 如果 此的 响应的 主体为 null，则为 处理响应主体结束 并返回。

       8. 让 length 是 提取的长度从 此的 响应的 头列表。

       9. 如果 length 不是一个整数，则将其设置为 0。

       10. 让 processBodyChunk 给定 bytes，执行以下步骤：

           1. 将 bytes 附加到 此的 接收到的字节。

           2. 如果自上次调用这些步骤以来大约没有经过 50 毫秒，则返回。

           3. 如果 此的 状态是已接收头部，则将 此的 状态设置为加载中。

           4. 触发一个事件名为 readystatechange 在 此。

              出于 Web 兼容性的原因，readystatechange 事件触发的频率要比 此的 状态 更频繁。

           5. 触发一个进度事件名为 progress 在 此，传递 此的 接收到的字节的 长度 和 length。

       11. 将 processEndOfBody 设为此步骤：为 处理响应的结束部分 运行 此对象。

       12. 将 processBodyError 设为以下步骤：

           1. 将 此对象 的 响应 设为 网络错误。

           2. 为 处理错误 运行 此对象。

       13. 根据 processBodyChunk、processEndOfBody、processBodyError 和 此对象 的 相关全局对象，逐步读取 此对象 的 响应 的 主体。

    10. 将 此对象 的 fetch 控制器 设置为 fetching req 的结果，其中 processRequestBodyChunkLength 设置为 processRequestBodyChunkLength，processRequestEndOfBody 设置为 processRequestEndOfBody，processResponse 设置为 processResponse。

    11. 将 now 设为当前时间。

    12. 并行运行以下步骤：并行：

        1. 等待直到 req 的 完成标志 被设置，或 此对象 的 超时时间 不为 0 并且自 now 以来已经过去了 超时时间 毫秒。

        2. 如果 req 的 完成标志 未设置，则将 此对象 的 超时标志 设置并终止 此对象 的 fetch 控制器。

12. 否则，如果 此对象 的 同步标志 已设置：

    1. 将 processedResponse 设为 false。

    2. 将 processResponseConsumeBody 设为以下步骤，给定 response 和 nullOrFailureOrBytes：

       1. 如果 nullOrFailureOrBytes 不是失败，则将 此对象 的 响应 设置为 response。

       2. 如果 nullOrFailureOrBytes 是 字节序列，则将 nullOrFailureOrBytes 添加到 此对象 的 接收到的字节。

       3. 将 processedResponse 设置为 true。

    3. 将 此对象 的 fetch 控制器 设置为 fetching req 的结果，processResponseConsumeBody 设置为 processResponseConsumeBody，并将 useParallelQueue 设置为 true。

    4. 将 now 设为当前时间。

    5. 暂停 直到 processedResponse 为 true 或 此对象 的 超时 不为 0，并且自 now 以来已经过去了 超时时间 毫秒。

    6. 如果 processedResponse 为 false，则将 此对象 的 超时标志 设置，并终止 此对象 的 fetch 控制器。

    7. 报告时间，针对 此对象 的 fetch 控制器，给定 当前全局对象。

    8. 为 处理响应的结束部分 运行 此对象。

为 XMLHttpRequest 对象 xhr 处理响应结束部分，运行以下步骤：

1. 为 xhr 处理错误。

2. 如果 xhr 的 响应 是 网络错误，则返回。

3. 将 transmitted 设为 xhr 的 接收到的字节的 长度。

4. 将 length 设为从 此对象 的 响应 的 头部列表 中 提取的长度的结果。

5. 如果 length 不是整数，则将其设为 0。

6. 如果 xhr 的 同步标志 未设置，则在 xhr 上，使用 transmitted 和 length 触发一个名为 progress 的进度事件。

7. 将 xhr 的 状态 设置为 完成。

8. 取消 xhr 的 send() 标志。

9. 在 xhr 上 触发一个名为 readystatechange 的事件。

10. 在 xhr 上，使用 transmitted 和 length 触发一个名为 load 的进度事件。

11. 在 xhr 上，使用 transmitted 和 length 触发一个名为 loadend 的进度事件。

为 XMLHttpRequest 对象 xhr 处理错误，运行以下步骤：

1. 如果 xhr 的 send() 标志 未设置，则返回。

2. 如果 xhr 的 超时标志 已设置，则为 xhr 运行 请求错误步骤，timeout，并使用“TimeoutError” DOMException。

3. 否则，如果 xhr 的 响应 的 终止标志 已设置，则为 xhr 运行 请求错误步骤， abort，并使用“AbortError”DOMException。

4. 否则，如果 xhr 的 响应 是 网络错误，则为 xhr 运行 请求错误步骤，error， 并使用“NetworkError” DOMException。

为 XMLHttpRequest 对象 xhr、event 和可选的 exception 执行 请求错误步骤：

1. 将 xhr 的 状态 设置为 完成。

2. 取消 xhr 的 send() 标志。

3. 将 xhr 的 响应 设为 网络错误。

4. 如果 xhr 的 同步标志 已设置，则 抛出 exception。

5. 在 xhr 上 触发一个名为 readystatechange 的事件。

   此时显然 xhr 的 同步标志 未设置。

6. 如果 xhr 的 上传完成标志 未设置，则：

   1. 将 xhr 的 上传完成标志 设置。

   2. 如果 xhr 的 上传监听器标志 已设置，则：

      1. 在 xhr 的 上传对象 上 触发一个名为 event 的进度事件，使用 0 和 0。

      2. 在 xhr 的 上传对象 上 触发一个名为 loadend 的进度事件，使用 0 和 0。

7. 在 xhr 上 触发一个名为 event 的进度事件，使用 0 和 0。

8. 在 xhr 上 触发一个名为 loadend 的进度事件，使用 0 和 0。

3.5.7. abort() 方法

client . abort()

取消任何网络活动。

abort() 方法步骤为：

1. 终止 此对象的 fetch 控制器。

2. 如果 此对象的 状态为 打开 且 send() 标志已设置，已接收头部或 加载中，则为 此对象 运行 请求错误步骤 和 abort。

3. 如果 此对象的 状态为 完成，则将 此对象的 状态设置为 未发送，并将 此对象的 响应设置为 网络错误。

   不会派发 readystatechange 事件。

3.6. 响应

3.6.1. responseURL 获取器

responseURL 获取器的步骤是，如果 此对象 的 响应 的 URL 为空，则返回空字符串； 否则返回其设置了 排除片段标志 的 序列化结果。

3.6.2. status 获取器

status 获取器的步骤是返回 此对象 的 响应 的 状态。

3.6.3. statusText 获取器

statusText 获取器的步骤是返回 此对象 的 响应 的 状态消息。

3.6.4. getResponseHeader() 方法

getResponseHeader(name) 方法步骤是返回从 此对象 的 响应 的 头部列表中获取 name 的结果。

Fetch 标准过滤了 此对象 的 响应的 头部列表。[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"));
  }
}

text/plain; charset=UTF-8

3.6.5. getAllResponseHeaders() 方法

如果以下步骤返回 true，则字节序列 a 被定义为 传统大写字节小于 字节序列 b：

1. 将 A 设为 a 的 大写字节。

2. 将 B 设为 b 的 大写字节。

3. 返回 A 是否 小于 B。

getAllResponseHeaders() 方法的步骤是：

1. 将 output 设为空字节序列。

2. 将 initialHeaders 设为对 此对象 的 响应 的 头部列表 执行 排序和合并 的结果。

3. 将 headers 设为对 initialHeaders 进行 升序排序 的结果，其中当 a 的 名称 比 b 的名称 传统大写字节小于 时，a 小于 b。

   不幸的是，这在与已部署内容的兼容性方面是必要的。

4. 对于每个 header 在 headers 中，附加 header 的 名称，后跟 0x3A 0x20 字节对，再跟 header 的 值，最后跟 0x0D 0x0A 字节对，添加到 output。

5. 返回 output。

Fetch 标准过滤了 此对象 的 响应的 头部列表。[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());
  }
}

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

3.6.6. 响应主体

要为 XMLHttpRequest 对象 xhr 获取响应 MIME 类型，执行以下步骤：

1. 将 mimeType 设为从 xhr 的 响应 的 头部列表中 提取 MIME 类型 的结果。

2. 如果 mimeType 失败，则将 mimeType 设置为 text/xml。

3. 返回 mimeType。

要为 XMLHttpRequest 对象 xhr 获取最终的 MIME 类型，执行以下步骤：

1. 如果 xhr 的 覆盖 MIME 类型 为空，则返回为 xhr 获取响应 MIME 类型 的结果。

2. 返回 xhr 的 覆盖 MIME 类型。

要为 XMLHttpRequest 对象 xhr 获取最终编码，执行以下步骤：

1. 将 label 设为空。

2. 将 responseMIME 设为为 xhr 获取响应 MIME 类型 的结果。

3. 如果 responseMIME 的 参数["charset"] 存在， 则将 label 设置为它。

4. 如果 xhr 的 覆盖 MIME 类型 的 参数["charset"] 存在， 则将 label 设置为它。

5. 如果 label 为空，则返回空。

6. 将 encoding 设为从 label 获取编码 的结果。

7. 如果 encoding 失败，则返回空。

8. 返回 encoding。

以上步骤故意不使用 获取最终 MIME 类型，因为这将不与 Web 兼容。

要为 XMLHttpRequest 对象 xhr 设置文档响应，执行以下步骤：

1. 如果 xhr 的 响应的 主体 为空，则返回。

2. 将 finalMIME 设为为 xhr 获取最终 MIME 类型 的结果。

3. 如果 finalMIME 不是 HTML MIME 类型 或 XML MIME 类型，则返回。

4. 如果 xhr 的 响应类型 为空字符串且 finalMIME 为 HTML MIME 类型，则返回。

   这是限制 xhr 的 响应类型 为 "document" 以防止破坏遗留内容。

5. 如果 finalMIME 是 HTML MIME 类型， 则：

   1. 将 charset 设为为 xhr 获取最终编码 的结果。

   2. 如果 charset 为空，则预扫描 xhr 的前 1024 字节的 接收到的字节，如果该操作未失败，则将 charset 设置为返回值。

   3. 如果 charset 为空，则将 charset 设置为 UTF-8。

   4. 将 document 设为 文档，其表示按照 HTML 标准中关于禁用脚本的 HTML 解析器和确定编码 charset 解析 xhr 的接收到的字节的结果。 [HTML]

   5. 将 document 标记为 HTML 文档。

6. 否则，将 document 设为 文档，其表示在 xhr 的 接收到的字节上运行 XML 解析器且禁用XML 脚本支持 的结果。如果失败（不支持的字符编码、命名空间格式错误等），则返回空。 [HTML]

   不会加载引用的资源，也不会应用任何相关的 XSLT。

7. 如果 charset 为空，则将 charset 设置为 UTF-8。

8. 将 document 的 编码设置为 charset。

9. 将 document 的 内容类型设置为 finalMIME。

10. 将 document 的 URL设置为 xhr 的 响应的 URL。

11. 将 document 的 来源设置为 xhr 的 相关设置对象的 来源。

12. 将 xhr 的 响应对象 设置为 document。

要为 XMLHttpRequest 对象 xhr 获取文本响应，执行以下步骤：

1. 如果 xhr 的 响应的 主体 为空，则返回空字符串。

2. 将 charset 设为为 xhr 获取最终编码 的结果。

3. 如果 xhr 的 响应类型为空字符串，charset为空，且为 xhr 获取最终 MIME 类型 的结果为 XML MIME 类型，则使用 XML 规范中规定的规则确定编码。将 charset 设置为确定的编码。 [XML] [XML-NAMES]

   这是为了保持非遗留的 xhr 响应类型值 "text" 的简洁。

4. 如果 charset 为空，则将 charset 设置为 UTF-8。

5. 返回在 xhr 的 接收到的字节上使用回退编码 charset 解码的结果。

作者强烈建议始终使用 UTF-8 编码其资源。

3.6.7. overrideMimeType() 方法

client . overrideMimeType(mime)

作用是使响应的 `Content-Type` 头部值看起来像是 mime。（它不会更改头部。）

如果 状态 为 loading 或 done，则抛出 "InvalidStateError" DOMException。

overrideMimeType(mime) 方法的步骤为：

1. 如果 此对象 的 状态 为 loading 或 done，则 抛出 "InvalidStateError" DOMException。

2. 将 此对象 的 覆盖 MIME 类型 设置为对 mime 解析 的结果。

3. 如果 此对象 的 覆盖 MIME 类型 失败，则将 此对象 的 覆盖 MIME 类型 设置为 application/octet-stream。

3.6.8. responseType 获取器和设置器

client . responseType [ = value ]

返回响应类型。

可以设置以更改响应类型。值包括： 空字符串（默认）， "arraybuffer"， "blob"， "document"， "json" 和 "text"。

设置时：如果 当前全局对象 不是 Window 对象，则忽略设置为 "document"。

设置时：如果 InvalidStateError DOMException 将被抛出，如果 状态 是 loading 或 done。

设置时：如果 InvalidAccessError DOMException 将被抛出，如果 同步标志 已设置并且 当前全局对象 是 Window 对象。

responseType 获取器的步骤是返回 此对象 的 响应类型。

responseType 设置器的步骤为：

1. 如果 当前全局对象 不是 Window 对象且给定值为 "document"，则返回。

2. 如果 此对象 的 状态 为 loading 或 done，则 抛出 "InvalidStateError" DOMException。

3. 如果 当前全局对象 是 Window 对象并且 此对象 的 同步标志 已设置，则 抛出 "InvalidAccessError" DOMException。

4. 将 此对象 的 响应类型 设置为给定值。

3.6.9. response 获取器

client . response

返回响应主体。

response 获取器的步骤为：

1. 如果 此对象 的 响应类型为空字符串或 "text"，则：

   1. 如果 此对象 的 状态 不是 loading 或 done，则返回空字符串。

   2. 返回为 此对象 获取文本响应 的结果。

2. 如果 此对象 的 状态 不是 done，则返回 null。

3. 如果 此对象 的 响应对象 失败，则返回 null。

4. 如果 此对象 的 响应对象 非空，则返回它。

5. 如果 此对象 的 响应类型 为 "arraybuffer"，则将 此对象 的 响应对象 设置为表示 此对象 接收到的字节 的 ArrayBuffer 对象。如果此操作抛出异常，则将 此对象 的 响应对象 设置为失败并返回 null。

   分配 ArrayBuffer 对象不能保证成功。 [ECMASCRIPT]

6. 否则，如果 此对象 的 响应类型 为 "blob"，则将 此对象 的 响应对象 设置为表示 此对象 的 接收到的字节的 Blob 对象，并将 type 设置为为 此对象 获取最终 MIME 类型 的结果。

7. 否则，如果 此对象 的 响应类型 为 "document"，则 设置文档响应 为 此对象。

8. 否则：

   1. 断言：此对象 的 响应类型 为 "json"。

   2. 如果 此对象 的 响应 的 主体为空，则返回 null。

   3. 将 jsonObject 设为对 此对象 的 接收到的字节运行 从字节解析 JSON 的结果。如果此操作抛出异常，则返回 null。

   4. 将 此对象 的 响应对象 设置为 jsonObject。

9. 返回 此对象 的 响应对象。

3.6.10. responseText 获取器

client . responseText

返回响应为文本格式。

如果 responseType 不是空字符串或 "text"， 则抛出 "InvalidStateError" DOMException。

responseText 获取器的步骤为：

1. 如果 此对象 的 响应类型 不是空字符串或 "text"，则 抛出 "InvalidStateError" DOMException。

2. 如果 此对象 的 状态 不是 loading 或 done，则返回空字符串。

3. 返回为 此对象 获取文本响应 的结果。

3.6.11. responseXML 获取器

client . responseXML

返回响应为文档格式。

如果 responseType 不是空字符串或 "document"， 则抛出 "InvalidStateError" DOMException。

responseXML 获取器的步骤为：

1. 如果 this 的 响应类型 不是空字符串或 "document"，则 抛出 "InvalidStateError" DOMException。

2. 如果 this 的 状态 不是 done， 则返回 null。

3. 断言：this 的 响应对象 没有失败。

4. 如果 this 的 响应对象 非空，则返回它。

5. 设置文档响应 为 this。

6. 返回 this 的 响应对象。

3.7. 事件概要

本节为非规范性内容。

以下事件会在 XMLHttpRequest 或 XMLHttpRequestUpload 对象上被触发：

4. 接口 FormData

typedef (File or USVString) FormDataEntryValue;

[Exposed=(Window,Worker)]
interface FormData {
  constructor(optional HTMLFormElement form, optional HTMLElement? submitter = null);

  undefined append(USVString name, USVString value);
  undefined append(USVString name, Blob blobValue, optional USVString filename);
  undefined delete(USVString name);
  FormDataEntryValue? get(USVString name);
  sequence<FormDataEntryValue> getAll(USVString name);
  boolean has(USVString name);
  undefined set(USVString name, USVString value);
  undefined set(USVString name, Blob blobValue, optional USVString filename);
  iterable<USVString, FormDataEntryValue>;
};

每个 FormData 对象都有一个关联的 entry list （一个 条目列表）。它最初是空的。

本节曾定义了 条目、条目的 名称 和 值，以及 创建条目 的算法。这些定义已被移至 HTML 标准中。[HTML]

new FormData(form, submitter) 构造器步骤如下：

1. 如果 form 被提供，则：

   1. 如果 submitter 非空，则：

      1. 如果 submitter 不是 提交按钮，则 抛出 一个 TypeError。

      2. 如果 submitter 的 表单所有者 不是 form，则 抛出一个 "NotFoundError" DOMException。

   2. 令 list 为 构建表单数据集 的结果，针对 form 和 submitter。

   3. 如果 list 为 null，则 抛出 一个 "InvalidStateError" DOMException。

   4. 将 this 的 条目列表 设置为 list。

append(name, value) 和 append(name, blobValue, filename) 方法步骤如下：

1. 如果给定值，则将 value 设为 value；否则设为 blobValue。

2. 令 entry 为通过 创建条目 得到的结果，使用 name、value 和可选的 filename。

3. 将 entry 添加到 this 的 条目列表 中。

参数 value 和 blobValue 同时存在的原因是因为用于编写 XMLHttpRequest 标准的编辑软件的限制。

delete(name) 方法步骤是 删除 所有 名称为 name 的 条目。

get(name) 方法的步骤如下：

1. 如果 entry 中没有名称为 name 的 this 的 条目列表，则返回 null。

2. 返回第一个名称为 name 的 entry 的 value，从 this 的 条目列表 中。

getAll(name) 方法的步骤如下：

1. 如果 entry 中没有名称为 name 的 this 的 条目列表，则返回空列表。

2. 返回所有名称为 name 的 entry 的 值，按顺序从 this 的 条目列表 中。

has(name) 方法的步骤是：如果 entry 中有名称为 name 的条目存在于 this 的 条目列表 中，则返回 true；否则返回 false。

set(name, value) 和 set(name, blobValue, filename) 方法的步骤如下：

1. 如果给定了 value，则令其为 value；否则令其为 blobValue。

2. 使用 name、value 和（如果给定）filename 的值，执行 创建条目 的操作，令其结果为 entry。

3. 如果在 this 的 条目列表 中有名称为 name 的 条目，则 替换第一个这样的 条目 为 entry，并 移除其他条目。

4. 否则，追加 entry 到 this 的 条目列表 中。

命名为 value 和 blobValue 的参数是由于编写 XMLHttpRequest 标准时使用的编辑软件的限制。

要迭代的键值对是 this 的 条目列表 中的 条目，键为 名称，值为 值。

5. 接口 ProgressEvent

[Exposed=(Window,Worker)]
interface ProgressEvent : Event {
  constructor(DOMString type, optional ProgressEventInit eventInitDict = {});

  readonly attribute boolean lengthComputable;
  readonly attribute double loaded;
  readonly attribute double total;
};

dictionary ProgressEventInit : EventInit {
  boolean lengthComputable = false;
  double loaded = 0;
  double total = 0;
};

事件 使用 ProgressEvent 接口表示某种进展。

lengthComputable、loaded 和 total getter 的步骤是返回它们的初始值。

5.1. 使用 ProgressEvent 接口触发事件

为了 触发一个名为 e 的进度事件 在 target 上，给定 transmitted 和 length，意味着使用 触发一个事件 名为 e 在 target 上，使用 ProgressEvent，并将 loaded 属性初始化为 transmitted，如果 length 不为 0，则将 lengthComputable 属性初始化为 true，并将 total 属性初始化为 length。

5.2. 使用 ProgressEvent 接口的建议事件名称

本节非规范性。

使用 事件 和 ProgressEvent 接口时，建议的 type 属性值总结在下表中。规范编辑者可以根据具体情况调整细节，但强烈建议与 WHATWG 社区讨论他们的使用，以确保从熟悉该主题的人那里获得意见。

error、abort、timeout 和 load 事件类型是互斥的。

在整个 Web 平台中，error、abort、timeout 和 load 事件类型的 bubbles 和 cancelable 属性初始值为 false，因此建议为了保持一致，所有使用 事件 和 ProgressEvent 接口的事件都遵循此规则。

5.3. 安全注意事项

对于跨域请求，需要某种类型的选择加入，例如 Fetch 标准中定义的 CORS 协议，在 事件 使用 ProgressEvent 接口之前，因为会泄露无法通过其他方式获得的信息（例如大小）。[FETCH]

5.4. 示例

<!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>

致谢

感谢 Addison Phillips, Adrian Bateman, Ahmed Kamel, Alan Thomas, Alex Hopmann, Alex Vincent, Alexey Proskuryakov, Ali Alabbas, Andrea Marchesini, Asbjørn Ulsberg, Bertrand Guay-Paquet, Björn Höhrmann, Boris Zbarsky, Caitlin Potter, Cameron McCormack, 白丞祐 (Cheng-You Bai), Chris Marrin, Christophe Jolif, Charles McCathieNevile, Chirag S Kumar, Dan Winship, David Andersson, David Flanagan, David Håsäther, David Levin, Dean Jackson, Denis Sureau, Domenic Denicola, Dominik Röttsches, Doug Schepers, Douglas Livingstone, Elliott Sprehn, Elliotte Harold, Eric Lawrence, Eric Uhrhane, Erik Arvidsson, Erik Dahlström, Feras Moussa, Gideon Cohn, Glenn Adams, Gorm Haug Eriksen, Gregory Terzian, Håkon Wium Lie, Hallvord R. M. Steen, Henri Sivonen, Hiroshige Hayashizaki, Huub Schaeks, Ian Clelland, Ian Davis, Ian Hickson, Ivan Herman, Jake Archibald, Jared Jacobs, Jarred Nicholls, Jeff Walden, Jens Lindström, Jim Deegan, Jim Ley, Joe Farro, Jonas Sicking, Julian Reschke, 송정기 (Jungkee Song), 呂康豪 (Kang-Hao Lu), Karl Dubost, Keith Yeung, 田村健人 (Kent TAMURA), Lachlan Hunt, Maciej Stachowiak, Magnus Kristiansen, Manish Goregaokar, Marc Hadley, Marcos Caceres, Mark Baker, Mark Birbeck, Mark Nottingham, Mark S. Miller, Martin Hassman, Mike Pennisi, Mohamed Zergaoui, Ms2ger, Noam Rosenthal, Odin Hørthe Omdal, Olli Pettay, Pawel Glowacki, Peter Michaux, Philip Jägenstedt, Philip Taylor, Rashika Jaggi, Robin Berjon, Rune F. Halvorsen, Ruud Steltenpool, Ryo Onodera, Sam Sneddon, Sergiu Dumitriu, Shivakumar Jagalur Matt, Sigbjørn Finne, Simon Pieters, Stewart Brodie, Sunava Dutta, Takeshi Kurosawa, Takeshi Yoshino, Thomas Roessler, Thomas Wisniewski, Tom Magliery, Travis Leithead, triple-underscore, Yaron Tausky, Yehuda Katz, Youenn Fablet,和 Zhenbin Xu 等人为该标准做出的贡献。

特别感谢首次实现 XMLHttpRequest 接口的微软员工，该接口首次通过 Windows Internet Explorer 浏览器广泛部署。

特别感谢 Ian Hickson 起草了最初版本的本规范，该规范最初在 HTML 标准（当时是 Web Applications 1.0）中。[HTML]

特别感谢 W3C SVG 工作组在 SVG 微型 DOM 中起草了原始的 ProgressEvent 类。

本标准由 Anne van Kesteren（Apple，annevk@annevk.nl）撰写。

知识产权声明

版权所有 © WHATWG（Apple、Google、Mozilla、Microsoft）。本作品采用 Creative Commons Attribution 4.0 International License 进行许可。若部分内容已被纳入源代码，则源代码中的该部分根据 BSD 3-Clause License 许可。

这是现行标准。对专利审查版本感兴趣的用户应查看 现行标准审查草案。