Warning:
This wiki has been archived and is now read-only.
XMLHttpRequest
Contents
介绍
这部分是非规范的
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 的功能子集,例如 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()
构造器必须按下列步骤运行:
- 令 xhr 为一个新的
XMLHttpRequest
对象。 - 将 xhr 的配置对象设置为与 xhr 接口全局对象相关联的配置对象。
- 返回 xhr。
垃圾回收
如果 XMLHttpRequest
对象的状态是 OPENED 并且已设置 send() 标识,或者它的状态是 HEADERS_RECEIVED,又或者它的状态是 LOADING 且它对以下事件注册了一个以上的事件监听:readystatechange
、progress
、about
、error
、load
、timeout
、loadend
,凡满足以上这些情况的 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)
-
open()
方法已经成功调用。在此期间可以使用setRequestHeader()
方法来设置请求头,并且可以调用send()
方法来请求。
OPENED
(数字值为 1)
- 所有的重定向都已经跳转(如果有的话),并且已经接收到了所有的HTTP响应头。
HEADERS_RECEIVED
(数字值为 2)
- 数据传输已经完成或者传输过程中出现错误(例如无限重定向)。
DONE
(数字值为 4)
初始的 XMLHttpRequest
对象必须为 UNSENT 状态.
send()
标志表示 send()
方法已经被调用。它初始状态不被设置,在 OPENED 状态期间被使用。
请求
每个 XMLHttpRequest 对象都有下面与请求相关的概念:请求方法、请求URL、作者请求头、请求主体、异步标识、上传完成标识以及上传事件标识。
作者请求头初始为空头列表。
请求主体初始为 null。
在发生致命错误时终止 XMLHttpRequest 对象操作的抓取算法来终止请求。
open() 方法
client . open(method, url [, async = true [, username = null [, password = null]]])
如果方法不是有效的 HTTP 方法或 url 无法解析则抛出 "SyntaxError" 异常。
如果方法是大小写不敏感的 `CONNECT`、`TRACE` 或 `TRACK` 其中之一则抛出一个 "SecurityError" 异常。
如果 async 为 false、JavaScript 全局环境是一个文档环境,并且满足下列其中之一:timeout 属性非零、 withCredentials 属性为 true、responseType 属性不是空字符串,抛出一个 "InvalidAccessError" 异常。
open(method, url, async, username, password) 方法必须以下面的步骤执行:
- 如果配置对象的可靠文档不是充分活跃的则抛出一个 "InvalidStateError" 异常。
- 将配置对象的API base URL设置为 base
- 如果 method 不是一个方法则抛出一个 "SyntaxError" 异常。
- 如果 method 是一个被禁用的方法则抛出一个 "SecurityError" 异常。
- 规范化 method。
- 令 parsedURL 为以 base 解析 url 的结果。
- 如果 parsedURL 是失败的则抛出一个 "SyntaxError" 异常。
- 如果 async 参数被省略则将 async 设置为 true,并且将 username 和 password 设置为 null。注:遗憾的是旧版中的 async 参数不能被省略,如果省略的话会被作为 undefined 处理。
- 如果 parsedURL 的相对标志有设置则以下面的步骤执行:
- 如果 async 为 false 且 JavaScript 全局环境是文档环境并且满足下列其中之一:timeout 属性非零、 withCredentials 属性为 true、responseType 属性不是空字符串,抛出一个 "InvalidAccessError" 异常。
- 终止请求。注:在这个点上抓取会被持续。Error creating thumbnail: Unable to save thumbnail to destination
- 设置变量与对象的关联:
- 将 请求方法 设置为 method。
- 将 请求 URL 设置为 parsedURL。
- 如果 async 为 false 且同步标志未设置,则设置同步标志。
- 清空作者请求头。
- 将响应设置为网络错误。
- 将响应的 ArrayBuffer 对象 设置为 null。
- 将响应的 Blob 对象 设置为 null。
- 将响应的 Document 对象 设置为 null。
- 将响应的 JSON 对象 设置为 null。
- 如果其状态不为 OPENED 则以下列步骤执行:
- 将其状态设置为 OPENED。
- 触发一个名为 readystatechange 的事件。
setRequestHeader() 方法
client . setRequestHeader(name, value) 并入一个头到作者请求头中。
如果状态不是 OPENED 或 send() 标识有设置则抛出一个 "InvalidStateError" 异常。
如果 name 不是请求头名称或 value 不是请求头值则抛出一个 "SyntaxError"。
timeout 属性
withCredentials 属性
upload 属性
send() 方法
about() 方法
响应
responseType
属性
responsetype
. [ = value ]
回传回应的类型。
也可以用来改变回应的类型,值包括:空字串(默认)、"arraybuffer
"、"blob
、"document
"、"json
"、"text
"設值時:若状态为 LOADING 或 DONE 则抛出 " InvalidStateError
。
XMLHttpRequest
文件的时候设上的,则抛出 "InvalidAccessError
"。responseType
属性必须回传该值。默认值必须是空字串。
设定 responseType
属性的时候,用户代理必须执行这些步骤:
- 若状态为 LOADING 或 DONE,则抛出 "
InvalidStateError
" 并结束这些步骤。 - 若有相连的
XMLHttpRequest
文件且XMLHttpRequest
设有同步标记,则抛出 "InvalidAccessError
" 并结束这些步骤。 - 设
responseType
的值为给定值。