XMLHttpRequest API window_and_worker_except_service
XMLHttpRequest(XHR)对象用于与服务器交互。通过 XMLHttpRequest 可以在不刷新页面的情况下请求特定 URL,获取数据。这允许网页在不影响用户操作的情况下,更新页面的局部内容。XMLHttpRequest 在 AJAX 编程中被大量使用。
尽管名称如此,XMLHttpRequest 可以用于获取任何类型的数据,而不仅仅是 XML。它甚至支持 HTTP 以外的协议(包括 file:// 和 FTP),尽管可能受到更多出于安全等原因的限制。
如果你的通信流程需要从服务器端接收事件或消息数据,请考虑通过 EventSource 接口使用服务器发送事件。对于全双工的通信,WebSocket 可能是更好的选择。
构造函数
- XMLHttpRequest.XMLHttpRequest
- : 该构造函数用于初始化一个
XMLHttpRequest实例对象。在调用下列任何其他方法之前,必须先调用该构造函数,或通过其他方式,得到一个实例对象。
- : 该构造函数用于初始化一个
属性
此接口继承了 XMLHttpRequestEventTarget 和 EventTarget 的属性。
-
XMLHttpRequest.onreadystatechange
- : 当
readyState属性发生变化时,调用的事件处理器。
- : 当
-
XMLHttpRequest.readyState
- : 返回 一个无符号短整型(
unsigned short)数字,代表请求的状态码。
- : 返回 一个无符号短整型(
-
XMLHttpRequest.response
- : 返回一个 ArrayBuffer、Blob、Document,或 String,具体是哪种类型取决于 XMLHttpRequest.responseType 的值。其中包含整个响应实体(response entity body)。
-
XMLHttpRequest.responseText
- : 返回一个 String,该 String 包含对请求的响应,如果请求未成功或尚未发送,则返回
null。
- : 返回一个 String,该 String 包含对请求的响应,如果请求未成功或尚未发送,则返回
-
XMLHttpRequest.responseType
- : 一个用于定义响应类型的枚举值(enumerated value)。
-
XMLHttpRequest.responseURL
- : 返回经过序列化(serialized)的响应 URL,如果该 URL 为空,则返回空字符串。
-
XMLHttpRequest.responseXML
- : 返回一个 Document,其中包含该请求的响应,如果请求未成功、尚未发送或是不能被解析为 XML 或 HTML,则返回
null。
- : 返回一个 Document,其中包含该请求的响应,如果请求未成功、尚未发送或是不能被解析为 XML 或 HTML,则返回
-
XMLHttpRequest.status
- : 返回一个无符号短整型(
unsigned short)数字,代表请求的响应状态。
- : 返回一个无符号短整型(
-
XMLHttpRequest.statusText
-
: 返回一个 String,其中包含 HTTP 服务器返回的响应状态。与 XMLHTTPRequest.status 不同的是,它包含完整的响应状态文本(例如,"
200 OK")。[!NOTE] 根据 HTTP/2 规范(8.1.2.4 Response Pseudo-Header Fields,响应伪标头字段),HTTP/2 没有定义任何用于携带 HTTP/1.1 状态行中包含的版本(version)或者原因短语(reason phrase)的方法。
-
-
XMLHttpRequest.timeout
- : 一个无符号长整型(
unsigned long)数字,表示该请求的最大请求时间(毫秒),若超出该时间,请求会自动终止。
- : 一个无符号长整型(
-
XMLHttpRequest.upload
- : XMLHttpRequestUpload,代表上传进度。
-
XMLHttpRequest.withCredentials
- : 一个Boolean,用来指定跨站
Access-Control请求是否应当带有授权信息,如 cookie 或身份验证标头。
- : 一个Boolean,用来指定跨站
非标准属性
XMLHttpRequest.mozAnon- : 一个布尔值,如果为真,请求将在没有 cookie 和身份验证标头的情况下发送。
XMLHttpRequest.mozSystem- : 一个布尔值,如果为真,则在请求时不会强制执行同源策略。
事件处理器
作为 XMLHttpRequest 实例的属性之一,所有浏览器都支持 onreadystatechange。
后来,许多浏览器实现了一些额外的事件(onload、onerror、onprogress 等)。详见使用 XMLHttpRequest。
更多现代浏览器,包括 Firefox,除了可以设置 on* 属性外,也提供标准的监听器 EventTarget.addEventListener API 来监听XMLHttpRequest 事件。
实例方法
- XMLHttpRequest.abort()
- : 如果请求已被发出,则立刻中止请求。
- XMLHttpRequest.getAllResponseHeaders()
- : 以字符串的形式返回所有用 CRLF 分隔的响应头,如果没有收到响应,则返回
null。
- : 以字符串的形式返回所有用 CRLF 分隔的响应头,如果没有收到响应,则返回
- XMLHttpRequest.getResponseHeader()
- : 返回包含指定响应头的字符串,如果响应尚未收到或响应中不存在该报头,则返回
null。
- : 返回包含指定响应头的字符串,如果响应尚未收到或响应中不存在该报头,则返回
- XMLHttpRequest.open()
- : 初始化一个请求。
- XMLHttpRequest.overrideMimeType()
- : 覆写由服务器返回的 MIME 类型。
- XMLHttpRequest.send()
- : 发送请求。如果请求是异步的(默认),那么该方法将在请求发送后立即返回。
- XMLHttpRequest.setRequestHeader()
- : 设置 HTTP 请求标头的值。必须在 XMLHttpRequest.open 之后、XMLHttpRequest.send 之前调用
setRequestHeader()方法。
- : 设置 HTTP 请求标头的值。必须在 XMLHttpRequest.open 之后、XMLHttpRequest.send 之前调用
事件
- XMLHttpRequest/abort_event
- : 当 request 被停止时触发,例如当程序调用 XMLHttpRequest.abort() 时。 也可以使用 XMLHttpRequestEventTarget/onabort 属性。
- XMLHttpRequest/error_event
- : 当 request 遭遇错误时触发。 也可以使用 XMLHttpRequestEventTarget/onerror 属性
- XMLHttpRequest/load_event
- : XMLHttpRequest请求成功完成时触发。 也可以使用 XMLHttpRequestEventTarget/onload 属性。
- XMLHttpRequest/loadend_event
- : 当请求结束时触发,无论请求成功 ( XMLHttpRequest/load_event) 还是失败 (XMLHttpRequest/abort_event 或 XMLHttpRequest/error_event)。 也可以使用 XMLHttpRequestEventTarget/onloadend 属性。
- XMLHttpRequest/loadstart_event
- : 接收到响应数据时触发。 也可以使用 XMLHttpRequestEventTarget/onloadstart 属性。
- XMLHttpRequest/progress_event
- : 当请求接收到更多数据时,周期性地触发。 也可以使用 XMLHttpRequestEventTarget/onprogress 属性。
- XMLHttpRequest/timeout_event
- : 在预设时间内没有接收到响应时触发。 也可以使用 XMLHttpRequestEventTarget/ontimeout 属性。
规范
浏览器兼容性
参见
- XMLSerializer:将 DOM 树解析为 XML 对象
- 使用 XMLHttpRequest
- Fetch API
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
