XMLHttpRequest

From HTML5 Chinese Interest Group Wiki
Jump to: navigation, search

介绍

这部分是非规范的

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 变成一个单一的实体。

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


一致性

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

在这份规范的规范部分中,关键词“必须”、“必须不”、“需要”、“应该”、“不该”、“被推荐的”、“可能”和“可选的”,都要被作为 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 的功能子集,例如 BlobFile 接口。 [FILEAPI]


HTML

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


HTTP

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


Progress Events

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


Typed Array

合格的用户代理必须支持 ArrayBufferArrayBufferView 对象。 [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 且它对以下事件注册了一个以上的事件监听:readystatechangeprogressabouterrorloadtimeoutloadend,凡满足以上这些情况的 XMLHttpRequest 就必须不被垃圾回收机制回收。

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


事件处理

下列是事件处理(它们对应事件处理的事件类型),在对象实现一个继承于 XMLHttpRequestEventTarget 的接口时必须实现它们:


event handler event handler event type
onloadstart loadstart
onprogress progress
onabort abort
onerror error
onload load
ontimeout timeout
onloadend loadend


下面是必须由 XMLHttpRequest 对象单独支持的的事件处理(它对应事件处理的事件类型):


event handler event handler event type
onloadstart loadstart


状态

 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() 方法

注:

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

设置请求方法请求URL异步标识

如果方法不是有效的 HTTP 方法或 url 无法解析则抛出 "SyntaxError" 异常。

如果方法是大小写不敏感的 `CONNECT`、`TRACE` 或 `TRACK` 其中之一则抛出一个 "SecurityError" 异常。

如果 asyncfalseJavaScript 全局环境是一个文档环境,并且满足下列其中之一:timeout 属性非零、 withCredentials 属性为 trueresponseType 属性不是空字符串,抛出一个 "InvalidAccessError" 异常。

警告:开发者必须不在 JavaScript 全局环境文档环境时给 async 参数传递 false,它会造成不良的终端用户体验。强烈鼓励用户代理对这样的用法在开发者工具中抛出警告,而且当这种情况出现时候可以尝试抛出一个 "InvalidAccessError" 异常,如此一来最终可以将这个特性从平台上彻底移除 Note.png

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,并且将 usernamepassword 设置为 null
    注:遗憾的是旧版中的 async 参数不能被省略,如果省略的话会被作为 undefined 处理。
  9. 如果 parsedURL相对标志有设置则以下面的步骤执行:
    1. 如果 username 参数不为 null 则令 usernameparsedURL用户名
    2. 如果 password 参数不为 null 则令 passwordparsedURL密码
  10. 如果 asyncfalseJavaScript 全局环境文档环境并且满足下列其中之一:timeout 属性非零、 withCredentials 属性为 trueresponseType 属性不是空字符串,抛出一个 "InvalidAccessError" 异常。
  11. 终止请求
    注:在这个点上抓取会被持续。Question.png
  12. 设置变量与对象的关联:
  13. 如果其状态不为 OPENED 则以下列步骤执行:
    1. 将其状态设置为 OPENED
    2. 触发一个名为 readystatechange 的事件。


setRequestHeader() 方法

注:

client . setRequestHeader(name, value) 并入一个头到作者请求头中。

如果状态不是 OPENEDsend() 标识有设置则抛出一个 "InvalidStateError" 异常。

如果 name 不是请求头名称或 value 不是请求头值则抛出一个 "SyntaxError"


timeout 属性


withCredentials 属性


upload 属性


send() 方法


about() 方法

响应

responseType 属性

此区块中不是标准描述,实现要求在下面给出。client . responsetype . [ = value ]

回传回应的类型。

也可以用来改变回应的类型,值包括:空字串(默认)、"arraybuffer"、"blob、"document"、"json"、"text"Idea.png

設值時:若状态为 LOADINGDONE 则抛出 " InvalidStateError

設值時:若同步标记是在有相连 XMLHttpRequest 文件的时候设上的,则抛出 "InvalidAccessError"。

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

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

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


事件概述