AJAX – XMLHttpRequest – 接口

虽然名称如此, XMLHttpRequest 可以用于获取任何类型的数据, 而不仅仅是 XML, 它甚至支持 HTTP 以外的协议(包括file:// 和 FTP)

假如您的通信流程需要从服务器接收事件或者消息数据, 可以选择SSE, 对于全双工的通信, WebSocket 则可能是更好的选择

一. 构造函数

XMLHttpRequest()

? 该构造函数用于初始化一个 XMLHttpRequest 对象. 在调用下列任何其余方法之前, 必需先调用该构造函数, 或者通过其余方式间接得到一个 XMLHttpRequest

/**   * @name: 创立一个 XMLHttpRequest 对象   * @return: XMLHttpRequest 对象   */var myRequest = new XMLHttpRequest();

二. 属性

此接口继承了 XMLHttpRequestEventTarget 和 EventTarget 的属性。

1. readyState: 请求状态码(只读)

? 返回一个 XMLHttpRequest 代理商当前所处的状态. 一个 XHR 代理商总是处于下列状态中的一个:

// 示例 -- 状态为2的无法检测到?var xhr = new XMLHttpRequest(); // readyState 为 0xhr.open('GET', '/api', true); // readyState 为 1xhr.onprogress = function () {   // readyState 为 3}xhr.onload = function () {    // readyState 为 4}xhr.send(null);

2. responseType: 响应类型(可写)

是一个枚举类型的属性, 返回响应数据的类型. 允许手动设置返回数据的类型. 默认为 ‘text’ 类型(设置为空字符串时, 采用 ‘text’ 类型)

当手动设置为一个特定的类型时, 你需要确保服务器所返回的类型和你所设置的返回值类型是兼容的.

当服务器返回的返回值类型 和 所设置的响应类型不兼容时, 服务器返回的数据变成了 null, 即便服务器返回了数据

给一个同步模式的请求, 设置 responseType 会抛出一个 InvalidAccessError 的异常

要在 open() 初始化请求之后调用, 并且要在调用 send() 发送请求到服务器之前调用

3. response: 响应数据(只读)

返回的类型可以是 ArrayBuffer 、 Blob 、 Document 、 JavaScript Object 或者 DOMString 。取决于 responseType 属性设置的值

响应的类型如下所示(与responseType一致):

let xhr = new XMLHttpRequest();      xhr.responseType = "arraybuffer";      xhr.open("GET", "/url/api/system/system-dic/listAll");      xhr.onload = function(e) {        /*            onabort: null            onerror: null            onload: ? (e)            onloadend: null            onloadstart: null            onprogress: null            onreadystatechange: null            ontimeout: null            readyState: 4            response: ArrayBuffer(65) {}            responseText: (...)            responseType: "arraybuffer"            responseURL: "http://localhost:8080/url/api/system/system-dic/listAll"            responseXML: (...)            status: 200            statusText: "OK"            timeout: 0            upload: XMLHttpRequestUpload {onloadstart: null, onprogress: null, onabort: null, onerror: null, onload: null, …}            withCredentials: false          */        console.log(xhr);      };      xhr.send(null);

4. responseText: 请求响应(DOMString)(只读)

解决的是 DOMString 数据, 是返回的纯文本的值

当responseType为”text” 或者者 “”时, 此属性才会存储着后台返回的数据

// 当 xhr.responseType = "json",  // xhr.responseText: 报错信息(未能从“XMLHttpRequest”读取“responseText”属性：仅当对象的“responseType”为“”或者“text”（为“json”）时才可访问该值。)// 当 xhr.responseType="text" 或者为默认值 "",// xhr.responseText: {"msg":"您不允许访问该资源，请重新登录","ret":401}

5. responseXML: 请求响应(Document)(只读)

解决的是Document数据, 假如请求未成功, 尚未发送, 或者者检索的数据无法正确解析为 XML 或者 HTML, 则为null

默认是当作“text / xml” 来解析。当 responseType 设置为 “document” 并且请求已异步执行时，响应将被当作 “text / html” 来解析。responseXML 对于任何其余类型的数据以及 data: URLs 为 null

// 当 xhr.responseXML = "json",  // xhr.responseXML: 报错信息(无法从“XMLHttpRequest”读取“responseXML”属性：仅当对象的“responseType”为“”或者“document”（为“json”）时，才可访问该值。)// 当 xhr.responseType="document",// xhr.responseXML: null(解析错误)

6. responseURL: 响应序列化URL(只读)

返回响应的序列化URL, 假如URL为空则返回空字符串. 假如URL有锚点, 则位于URL#后面的内容会被删除. 假如URL有重定向, responseURL 的值回事经过屡次重定向后的最终URL

xhr.responseURL = 'http://localhost:8080/url/api/system/system-dic/listAll'

7. status: 响应状态码(只读)

返回响应中的数字状态码, 在请求完成前, status的值为0. 值得注意的是, 假如 XMLHttpRequest 出错, 浏览器返回的 status 也为0

status码是标准的 HTTP status codes. 假如服务器响应中没有明确指定 status 码, XMLHttpRequest.status 将会默认为200

var xhr = new XMLHttpRequest();console.log('UNSENT', xhr.status);xhr.open('GET', '/server', true);console.log('OPENED', xhr.status);xhr.onprogress = function () {  console.log('LOADING', xhr.status);};xhr.onload = function () {  console.log('DONE', xhr.status);};xhr.send(null);/** * 输出如下： * * UNSENT（未发送） 0 * OPENED（已打开） 0 * LOADING（载入中） 200 * DONE（完成） 200 */

8. statusText: 响应状态(DOMString)(只读)

不同于 status 属性的区别, 这个属性包含了返回状态对应的文本信息, 例如 “OK” 或者是 “Not Found”.

假如服务器未明确指定一个状态文本信息, 则 statusText 的值将会被自动赋值为 “OK”

var xhr = new XMLHttpRequest();console.log('0 UNSENT', xhr.statusText);xhr.open('GET', '/server', true);console.log('1 OPENED', xhr.statusText);xhr.onprogress = function () {  console.log('3 LOADING', xhr.statusText);};xhr.onload = function () {  console.log('4 DONE', xhr.statusText);};xhr.send(null);/** * 输出如下: * * 0 UNSENT * 1 OPENED * 3 LOADING OK * 4 DONE OK */

9. upload: 上传过程(只读)

**返回一个 XMLHttpRequestUpload 对象, 用来表示上传的进度. **

这个对象相似于 XMLHttpRequestUpload, 专门用来表示上传过程, 可用来实现上传过程中的相关事件

10. timeout: 超时时间(可读写)

表示请求的最大请求时间(毫秒), 若超出该时间, 则请求会自动结束

是一个无符号长整型数, 默认值为0, 意味着没有超时, 当超时发生, timeout 事件将会被触发

在 IE 中, 超时属性可能只能在调用 open() 方法之后且在调用 send() 方法之前设置

var xhr = new XMLHttpRequest();xhr.open('GET', '/server', true);xhr.timeout = 2000; // 超时时间，单位是毫秒xhr.onload = function () {  // 请求完成。在此进行解决。  // 超时不会触发这个事件  };xhr.ontimeout = function (e) {  // XMLHttpRequest 超时。在此做某事。};xhr.send(null);

11. withCredentials: 跨域请求能否带有受权信息(cookie 或者 受权 header 头)

是一个布尔值, 它指示了能否该使用相似cookies,authorization headers(头部受权)或者者TLS用户端证书这一类资格证书来创立一个跨站点访问控制（cross-site Access-Control）请求。

**注意:　在同一个站点下（就是没有产生跨域）使用withCredentials 属性是无效的, 这个指示也会被用做响应中 cookies 被忽视的标示. **

假如在发送来自其余域的XMLHttpRequest请求之前，未设置withCredentials 为true，那么就不能为它自己的域设置cookie值。而通过设置withCredentials 为true取得的第三方cookies，将会仍旧享受同源策略，因而不能被通过document.cookie或者者从头部相应请求的脚本等访问。

注意: 永远不会影响到同源请求

注意: 不同域下的XmlHttpRequest 响应，不管其Access-Control- header 设置什么值，都无法为它自身站点设置cookie值，除非它在请求之前将withCredentials 设为true。

var xhr = new XMLHttpRequest();xhr.open('GET', 'http://example.com/', true);xhr.withCredentials = true;xhr.send(null);

12. 非标准属性

三. 方法

1. open(): 初始化一个请求.

注意: 为已激活的请求调用此方法( open() 已被调用) 相当于调用 abort()

/**     * @name: 初始化一个请求     * @param {String} 要使用的 HTTP 方法(GET, POST, PUT...), 对于非 HTTP(S) URL 被忽略     * @param {String} 要发送请求的URL     * @param {Boolean?} 请求模式, true(默认值, 异步模式) | false(同步模式)     * @param {any?} 可选的客户名用于认证用途；默认为null。     * @param {any?} 可选的密码用于认证用途，默认为null。     */xhrReq.open(method, url, async?, user?, password?);

2. setResponseHeader(): 设置 HTTP 请求头的值

此方法必需在 open() 和 send() 之间调用. 假如屡次对同一请求头赋值, 只会生成一个合并了多个值得请求头

自己设置少量 header 属性进行跨域请求时, 可能会遇到 “not allowed by Access-Control-Allow-Headers in preflight response” 你可能需要在你的服务器端设置 “Access-Control-Allow-Headers

/**    * @name: 设置 HTTP 请求头的值    * @param: {String} 属性的名称    * @param: {String} 属性的值**/xhr.setRequestHeader(header, value);

3. getResponseHeader(): 返回指定响应头的字符串

假如响应尚未收到或者响应中不存在该响应, 则返回 null

必需要指定响应头名称, 也就是必需要有一个参数, 可通过 getAllResponseHeaders() 获取一律可获取的响应头

假如在返回头中有多个一样的名称, 那么返回的值就会使用逗号和空号分隔的字符串. 搜索标题名称是不区分大小写的。

/**    * @name: 获取 HTTP 请求头的值    * @param: {String} 响应头名称    * @return: 指定响应头内容, 假如响应尚未收到, 或者者响应中不存在, 则返回 null**/xhr.getRequestHeader(name);

4. getAllResponseHeaders(): 返回所有用 CRLF 分隔的响应头

注意： 对于复合请求 （ multipart requests ），这个方法返回当前请求的头部，而不是最初的请求的头部。

/**    * @name: 获取 HTTP 请求头的值    * @return: 返回所有的响应头，以 CRLF 分割的字符串，或者者 null 假如没有收到任何响应。**/xhr.getAllResponseHeaders();/*返回示例:cache-control: no-cache, no-store, max-age=0, must-revalidateconnection: closecontent-type: application/json;charset=UTF-8date: Thu, 12 Dec 2019 14:53:35 GMTexpires: 0pragma: no-cachetransfer-encoding: chunkedvary: Origin, Access-Control-Request-Method, Access-Control-Request-Headersx-content-type-options: nosniffx-powered-by: Expressx-xss-protection: 1; mode=block */

5. send(): 发送请求

用于发送 HTTP 请求, 假如是异步请求(默认为异步请求), 则此方法会在请求发送后立即返回；假如是同步请求，则此方法直到响应到达后才会返回。

/**    * @name: 发送请求    * @param: {any?} 请求方法为 GET 或者者 HEAD 时, 应该讲请求主题设置为 null. 请求方法为其余方法时, 其参数将作为请求主体发送至服务器**/xhr.send(data?);/*数据类型: 1. ArrayBuffer2. ArrayBufferView3. Blob4. Document5. DOMString(也就是String)6. FormData注意: 应该在发送请求即调用 send() 方法之前使用 setRequestHeader() 方法设置 Content-Type 头部来指定请求主体的数据流的 MIME 类型*/

6. abort(): 停止请求

假如请求已被发出, abort() 方法将终止该请求. 当一个请求被终止, 它的readyStete 属性将被置为0

/**    * @name: 停止请求(会回到 open()[打开请求状态之前] )**/xhr.abort();

7. overrideMimeType():重写由服务器返回的 MIME 类型

指定一个 MIME 类型用于替代服务器指定的类型, 使服务器响应信息中传输的数据按照该指定 MIME 类型解决. 例如强制使流方式解决为”text/xml”类型解决时会被使用到，即便服务器在响应头中并没有这样指定.

此方法必需在 send 方法之前调用才有效

假如服务器没有指定一个Content-Type 头, XMLHttpRequest 默认MIME类型为”text/xml”. 假如接受的数据不是有效的XML，将会出现格”格式不正确“的错误。你能够通过调用 overrideMimeType() 指定各种类型来避免这种情况。

/**    * @name: 重写响应 MIME 类型    * @param: {MIME类型} 指定具体的 MIME 类型去代替服务器指定的 MIME 类型. 假如服务器没有指定类型, 那么默认为 "text/xml"**/xhr.overrideMimeType(mimeType)

8. 非标准方法

四. 事件

**下列事件可在 XMLHttpRequest 对象中触发, 同时大部分事件(具体见 upload属性)也可在 xhr.upload 返回 XMLHttpRequestUpload(代表上传过程)中调用 **

1. readystatechange: 当 readyState 状态变化时调用

会在 XMLHttpRequest 的 readyState 属性发生改变时调用(不该用于同步的 requests 对象

xhr.onreadystatechange = function () {  if(xhr.readyState === XMLHttpRequest.DONE && xhr.status === 200) {    // 在这里说明调用成功了    console.log(xhr.responseText)  }}

2. load: 请求成功完成时调用

xhr.addEventListener('load', function(e) {    // 在这里说明调用成功了, xhr.readyState === 4})

3. loadstart: 开始传送数据时触发

开始传送数据时触发, 只会触发一次

xhr.addEventListener("loadstart", function(e) {  // 在 response 状态为1(调用了 send() 方法, 已经开始建立连接, 但是 response 还是为1  console.log("开始传送数据时", xhr.response);});

4. progress: 下载和上传的传输周期触发

周期性触发, 可用来实现进度条(具体发送数据在 event 中)

xhr.addEventListener("progress", function(e) {   // e.loaded: 在周期性调用中接受到了多少信息   // e.total: 该请求一共多少信息    console.log("周期性发送数据", e);});

5. loadend: 请求结束时触发

当请求结束时触发, 无论请求成功(load) 还是失败(abort 或者 error)

需要注意的是，没有方法可以确切的知道 loadend 事件接收到的信息是来自何种条件引起的操作终止；但是你可以在所有传输结束的时候使用这个事件解决。

xhr.addEventListener("loadend", function(e) {   // 无论请求成功还是失败都会调用, 但是这里不是很好区分成功起因 或者 失败起因吧   console.log("请求结束", xhr);});

6. abort: 当请求中止时触发

当请求终止时 abort 事件被触发, 例如调用了 abort() 方法

xhr.addEventListener("abort", function(e) {   console.log("请求中止", xhr);});

7. timeout: 请求超时时触发

当请求时间超出预约时间而终止请求时发出

xhr.addEventListener("timeout", function(e) {   console.log("请求超时", xhr);});

8. error: 请求错误时触发

xhr.addEventListener("error", function(e) {   console.log("请求错误", xhr);});

参考文档

• MDN-XMLHttpRequest

• MDN-使用 XMLHttpRequest