XMLHttpRequest

介绍

这部分是非规范的

XMLHttpRequest 是用于获取资源的 API

其与Web兼容的对象名称为 XMLHttpRequest，这个名字可能会让人望文生义。 首先，这个对象支持所有基于文本的格式，包括 XML。 再者，它可以用于发起 HTTP 和 HTTPS 请求（一些实现支持 HTTP 和 HTTPS 之外的请求，但这样的功能没有涵盖在这份规范中）。 最后，它支持广义的 HTTP 语法，也就是所有与有定义的HTTP方法的请求或响应有关的行为。

处理从网络上获取到的 XML 文档数据的简易代码：

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

function handler() {
  if(this.readyState == this.DONE) {
    if(this.status == 200 &&
       this.responseXML != null &&
       this.responseXML.getElementById('test').textContent) {
      // 成功!
      processData(this.responseXML.getElementById('test').textContent);
      return;
    }
    // 出错
    processData(null);
  }
}

var client = new XMLHttpRequest();
client.onreadystatechange = 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.onreadystatechange = function() {
    // 在网络错误的情况下也许无法得到可靠结果
    if(this.readyState == this.DONE)
      returnStatus(this.status);
  }
  client.open("HEAD", address);
  client.send();
}

规范史

XMLHttpRequest 对象初定义于 WHATWG 的 HTML 项目中，很久之后微软发起了一个实现。它于 2006 年被移到 W3C。直到 2011 年底，XMLHttpRequest 的扩展（XMLHttpRequest Level 2）被开发于一份独立的草案中，这时两份草案被合并，XMLHttpRequest 又从一个 standards perspective 变成一个单一的实体。

历史讨论可以从以下邮件列表档案中找到：

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

一致性

同所有章节中明确标明了非规范的部分一样，这份规范中的所有的图表、范例及注释都是非规范的。其它的所有内容都是规范的。

在这份规范的规范部分中，关键词“必须”、“必须不”、“需要”、“应该”、“不该”、“被推荐的”、“可能”和“可选的”，都要被作为 RFC2119 中的描述来解读。为了确保可读性，这些单词不会以全大写的形式出现在这份文档中。[RFC2119]

依赖

这份规范依赖于一些基本规范。

Cross-Origin Resource Sharing

合格的用户代理必须支持 Cross-Origin Resource Sharing 规范中的算法。[CORS]

DOM4

合格的用户代理至少必须支持这份规范所依赖的定义于 DOM4 的功能子集，例如各种异常和 EventTarget。[DOM]

DOM Parsing and Serialization

合格的用户代理至少必须支持来自 DOM Parsing and Serialization 的序列化概念。[DOMPS]

Encoding Standard

合格的用户代理至少必须支持这份规范所依赖的定义于 Encoding Standard 的功能子集，例如 utf-8 encoding。 [ENCODING]

File API

合格的用户代理至少必须支持这份规范所依赖的定义于 File API 的功能子集，例如 Blob 和 File 接口。 [FILEAPI]

HTML

合格的用户代理至少必须支持这份规范所依赖的定义于 HTML 的功能子集，例如 Window 对象的基本支持和序列化一个 Document 对象。[HTML]

HTTP

合格的用户代理必须支持一些 HTTP 协议版本。对 HTTP 的需求贯穿了这整个规范。[HTTP]

Progress Events

合格的用户代理必须支持 Progress Events 规范。[PROGRESSEVENTS]

Typed Array

合格的用户代理必须支持 ArrayBuffer 和 ArrayBufferView 对象。 [TYPEDARRAY]

URL 合格的用户代理必须支持 URL 规范的 URL 解析算法。[URL]

Web IDL

合格的用户代理在这份规范中也必须是合格的 IDL 片段的实现，同描 Web IDL 规范的描述一致。[WEBIDL]

XML

合格的用户代理必须是合格的 XML 处理器，它应该报告完整结构命名空间的违规操作。[XML] [XMLNS]

它使用 HTML 的排版约定。[HTML]

扩展性

强烈鼓励用户代理、工作组和其它有兴趣的团体在相关的公共论坛中讨论新特性，最好是在 public-webapps@w3.org。如果出于一些原因无法参与讨论，那么请对扩展添加前缀。例如 Foo 公司希望添加特有方法 bar()，那么它可以命名为 fooBar() 来避免与潜在的非特有方法 bar() 冲突.

用语

条目“用户凭证”在这份规范中指的是 Cookie、HTTP 认证和客户端 SSL 证书。特别地，本规范不涉及代理认证和 Origin 头。[COOKIES]

XMLHttpRequest 接口

 [NoInterfaceObject,
  Exposed=(Window,Worker)]
 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,Worker)]
 interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
 };
 
 enum XMLHttpRequestResponseType {
   "",
   "arraybuffer",
   "blob",
   "document",
   "json",
   "text"
 };
 
 [Constructor,
  Exposed=(Window,Worker)]
 interface XMLHttpRequest : XMLHttpRequestEventTarget {
   // 事件处理
   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;
 
   // 请求
   void open(ByteString method, ScalarValueString url);
   void open(ByteString method, ScalarValueString url, boolean async, optional ScalarValueString? username = null, optional ScalarValueString? password = null);
   void setRequestHeader(ByteString name, ByteString value);
            attribute unsigned long timeout;
            attribute boolean withCredentials;
   readonly attribute XMLHttpRequestUpload upload;
   void send(optional (Document or FetchBodyInit)? body = null);
   void abort();
 
   // 响应
   readonly attribute ScalarValueString 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 ScalarValueString responseText;
   [Exposed=Window] readonly attribute Document? responseXML;
 };

每个 XMLHttpRequest 对象都有一个与之关联且唯一的 XMLHttpRequestUpload

构造器

XMLHttpRequest 对象有一个关联的配置对象。

 client = new XMLHttpRequest()

返回一个新的 XMLHttpRequest 对象。

XMLHttpRequest() 构造器必须按下列步骤运行：

1. 令 xhr 为一个新的 XMLHttpRequest 对象。
2. 将 xhr 的配置对象设置为与 xhr 接口全局对象相关联的配置对象。
3. 返回 xhr。

垃圾回收

如果 XMLHttpRequest 对象的状态是 OPENED 并且已设置 send() 标识，或者它的状态是 HEADERS_RECEIVED，又或者它的状态是 LOADING 且它对以下事件注册了一个以上的事件监听：readystatechange、progress、about、error、load、timeout、loadend，凡满足以上这些情况的 XMLHttpRequest 就必须不被垃圾回收机制回收。

如果 XMLHttpRequest 对象在连接尚存打开时被垃圾回收机制回收了，用户代理必须终止请求。

事件处理

下列是事件处理（它们对应事件处理的事件类型），在对象实现一个继承于 XMLHttpRequestEventTarget 的接口时必须实现它们：

下面是必须由 XMLHttpRequest 对象单独支持的的事件处理（它对应事件处理的事件类型）：

状态

 client . readyState
 返回当前状态。

XMLHttpRequest 对象可以有几个状态。readyState属性必须返回当前状态，它必须是下列值的其中之一：

UNSET（数字值为 0）

对象已创建。

OPENED（数字值为 1）

open() 方法已经成功调用。在此期间可以使用 setRequestHeader() 方法来设置请求头，并且可以调用 send() 方法来请求。

HEADERS_RECEIVED（数字值为 2）

所有的重定向都已经跳转（如果有的话），并且已经接收到了所有的HTTP响应头。

LOADING（数字值为 3）

响应的主体部分正在被接收。

DONE（数字值为 4）

数据传输已经完成或者传输过程中出现错误（例如无限重定向）。

初始的 XMLHttpRequest 对象必须为 UNSENT 状态.

send() 标志表示 send() 方法已经被调用。它初始状态不被设置，在 OPENED 状态期间被使用。

请求

每个 XMLHttpRequest 对象都有下面与请求相关的概念：请求方法、请求URL、作者请求头、请求主体、异步标识、上传完成标识以及上传事件标识。

作者请求头初始为空头列表。

请求主体初始为 null。

异步标识、上传完成标识、上传事件标识，初始都未设置。

在发生致命错误时终止 XMLHttpRequest 对象操作的抓取算法来终止请求。

open() 方法

open(method, url, async, username, password) 方法必须以下面的步骤执行：

1. 如果配置对象的可靠文档不是充分活跃的则抛出一个 "InvalidStateError" 异常。
2. 将配置对象的API base URL设置为 base
3. 如果 method 不是一个方法则抛出一个 "SyntaxError" 异常。
4. 如果 method 是一个被禁用的方法则抛出一个 "SecurityError" 异常。
5. 规范化 method。
6. 令 parsedURL 为以 base 解析 url 的结果。
7. 如果 parsedURL 是失败的则抛出一个 "SyntaxError" 异常。
8. 如果 async 参数被省略则将 async 设置为 true，并且将 username 和 password 设置为 null。
   注：遗憾的是旧版中的 async 参数不能被省略，如果省略的话会被作为 undefined 处理。
9. 如果 parsedURL 的相对标志有设置则以下面的步骤执行：
   1. 如果 username 参数不为 null 则令 username 为 parsedURL 的 用户名。
   2. 如果 password 参数不为 null 则令 password 为 parsedURL 的 密码。
10. 如果 async 为 false 且 JavaScript 全局环境是文档环境并且满足下列其中之一：timeout 属性非零、 withCredentials 属性为 true、responseType 属性不是空字符串，抛出一个 "InvalidAccessError" 异常。
11. 终止请求。
    注：在这个点上抓取会被持续。

    Error creating thumbnail: Unable to save thumbnail to destination
12. 设置变量与对象的关联:
    • 将 请求方法 设置为 method。
    • 将 请求 URL 设置为 parsedURL。
    • 如果 async 为 false 且同步标志未设置，则设置同步标志。
    • 清空作者请求头。
    • 将响应设置为网络错误。
    • 将响应的 ArrayBuffer 对象 设置为 null。
    • 将响应的 Blob 对象 设置为 null。
    • 将响应的 Document 对象 设置为 null。
    • 将响应的 JSON 对象 设置为 null。
13. 如果其状态不为 OPENED 则以下列步骤执行：
    1. 将其状态设置为 OPENED。
    2. 触发一个名为 readystatechange 的事件。

setRequestHeader() 方法

timeout 属性

withCredentials 属性

upload 属性

send() 方法

about() 方法

响应

responseType 属性

responseType 属性必须回传该值。默认值必须是空字串。

设定 responseType 属性的时候，用户代理必须执行这些步骤：

1. 若状态为 LOADING 或 DONE，则抛出 " InvalidStateError" 并结束这些步骤。
2. 若有相连的 XMLHttpRequest 文件且 XMLHttpRequest 设有同步标记，则抛出 "InvalidAccessError" 并结束这些步骤。
3. 设 responseType 的值为给定值。

事件概述