JavaScript 的 XMLHttpRequest 对象

XMLHttpRequest 对象允许脚本执行 HTTP 客户端功能，例如提交表单数据或从服务器异步加载数据。

XMLHttpRequest API 是W3C XHR Level 1 标准的部分实现，但有以下例外：

它不强制执行同源策略。

发送请求

请按照以下步骤使用XMLHttpRequest API 发送请求：

创建一个XMLHttpRequest 对象。
为onreadystatechange信号处理程序分配一个回调函数。
调用open()方法，并传入相应的 HTTP 方法和要请求的 URL。
调用send()

回调函数负责处理请求的 HTTP 响应。在处理程序中，使用以下方法之一读取响应之前，建议先检查 `readyState` 是否为 `DONE `：

以下示例演示了如何发送请求并读取响应：

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls
import "request.js" as XHR

ApplicationWindow {
      width: 640
      height: 640
      visible: true

      ColumnLayout {
           anchors.fill: parent

           RowLayout {
               Layout.fillWidth: true

               TextField {
                   id: urlTextField
                   text: "https://www.example.com/index.html"
                   Layout.fillWidth: true
               }
               Button {
                   text: qsTr("Send!")
                   onClicked: XHR.sendRequest(urlTextField.text, function(response) {
                       statusTextField.text = response.status;
                       let isPlainText = response.contentType.length === 0

                       contentTypeTextField.text = isPlainText ? "text" : response.contentType;

                       if (isPlainText)
                           contentTextArea.text = response.content;
                   });
               }
           }

           GridLayout {
               columns: 2

               Layout.fillWidth: true

               Label {
                   text: qsTr("Status code")

                   Layout.fillWidth: true
               }
               Label {
                   text: qsTr("Response type")

                   Layout.fillWidth: true
               }
               TextField {
                    id: statusTextField

                    Layout.fillWidth: true
               }
               TextField {
                    id: contentTypeTextField

                    Layout.fillWidth: true
               }
           }
           Flickable {
               clip: true
               contentWidth: contentTextArea.width
               contentHeight: contentTextArea.height
               Text {
                    id: contentTextArea
               }

               Layout.fillWidth: true
               Layout.fillHeight: true
               ScrollBar.vertical: ScrollBar {}
               ScrollBar.horizontal: ScrollBar {}
           }
      }
}

前面的代码片段将按钮的点击信号连接到一个外部的 `sendRequest ` 函数。资源 URL 作为第一个参数传递，用于处理 UI 更新的回调函数作为第二个参数传递。位于外部文件 `request.js ` 中的 `sendRequest ` 函数可以这样实现：

function sendRequest(url, callback)
{
    let request = new XMLHttpRequest();

    request.onreadystatechange = function() {
        if (request.readyState === XMLHttpRequest.DONE) {
            let response = {
                status : request.status,
                headers : request.getAllResponseHeaders(),
                contentType : request.responseType,
                content : request.response
            };

            callback(response);
        }
    }

    request.open("GET", url);
    request.send();
}

前面的代码片段遵循了开头提到的四个简单步骤。它首先实例化XMLHttpRequest 对象，并为其分配一个用于处理响应的回调函数。在向服务器发送请求之前，它还会调用open() 方法，并传入 HTTP 方法和 URL。请注意，sendRequest 的第二个参数会在onreadystatechange 事件结束时被调用，以便根据 HTTP 响应处理 UI 更新。

若需调试请求，请将QML_XHR_DUMP 环境变量设置为1 。这将记录以下信息：

发送请求的方法类型（GET 或 POST）、URL 以及请求正文。
接收到的响应的 URL 和正文。
如有网络错误，则记录该错误。

访问本地文件

默认情况下，您无法使用XMLHttpRequest 对象从本地文件系统读取文件。若要使用此功能访问本地文件，请将以下环境变量设置为1 。

QML_XHR_ALLOW_FILE_READ
QML_XHR_ALLOW_FILE_WRITE

警告： 仅当您确信应用程序运行的是可信的 QML 和 JavaScript 代码时，才应使用 此功能。

responseXML 文档

QML 当前支持的responseXML XML DOM 树是 Web 浏览器中支持的DOM Level 3 CoreAPI 的精简子集。QML 实现支持以下对象和属性：

Node	Document	Element	Attr	CharacterData	文本
节点名称节点值 nodeType 父节点 childNodes firstChild lastChild 前一个同级节点下一个同级节点属性	xmlVersion xmlEncoding xmlStandalone documentElement	标签名	name value 所有者元素	data 长度	isElementContentWhitespace wholeText

void XMLHttpRequest::abort()

取消当前请求。

它将readyState属性更改为XMLHttpRequest.UNSENT ，并发出readystatechange 信号。

string XMLHttpRequest::getAllResponseHeaders()

返回一个包含从上次响应中接收到的头信息的String 。

以下是一个响应头示例：

content-encoding: gzip
content-type: text/html; charset=UTF-8
date: Mon, 06 Feb 2023 09:00:08 GMT
expires: Mon, 13 Feb 2023 09:00:08 GMT
last-modified: Thu, 17 Oct 2019 07:18:26 GMT

string XMLHttpRequest::getResponseHeader(headerName)

返回来自上一次响应的headerName 值；如果headerName 缺失，则返回空的String 。

void XMLHttpRequest::open(method, url, async)

指定请求要使用的HTTPmethod ，以及要请求的url 。请务必在调用send()之前先调用此函数。可选的第三个参数async 用于决定请求是否应为异步。默认值为true 。

发出readystatechange 信号，该信号会调用onreadystatechange处理程序，并将readyState属性设置为XMLHttpRequest.OPENED 。

void XMLHttpRequest::send(data)

将请求发送至服务器。您可以使用可选参数data 向请求主体添加额外数据。这对于 POST 请求非常有用，因为此类请求通常需要包含额外数据。

一旦从服务器收到响应，并在处理响应的过程中，`readyState`属性会进行更新。它将首先被设置为 `HEADERS_RECEIVED`，随后变为 `LOADING`，待响应完全处理完毕后，最终变为 `DONE`。每次`readyState`更新时，都会触发 `readystatechange ` 信号。

void XMLHttpRequest::setRequestHeader(header, value)

向您即将发送的下一个请求添加一个新标头。这是一个键值对，其名称为header ，对应值为value 。

void XMLHttpRequest::overrideMimeType(mime)

强制XMLHttpRequest 将下一次 HTTP 响应中接收到的数据解释为 MIME 类型mime ，而非服务器提供的 MIME 类型。

function XMLHttpRequest::onreadystatechange

选择一个回调函数，当XMLHttpRequest 对象的readyState发生变化时，该函数将被调用。

枚举 XMLHttpRequest::readyState

指示XMLHttpRequest 对象的当前状态。

其值可以是以下之一：

常量	描述
`XMLHttpRequest.UNSENT`	请求尚未初始化，这是调用open() 之前的状态。
`XMLHttpRequest.OPENED`	请求已初始化，即此前已调用open()，但未进行进一步处理。
`XMLHttpRequest.HEADERS_RECEIVED`	已从服务器收到响应，但请求尚未完全处理完毕。
`XMLHttpRequest.LOADING`	正在从服务器下载数据。
`XMLHttpRequest.DONE`	已完成请求的处理。

字符串 XMLHttpRequest::responseURL

返回用于检索响应数据的 URL，该 URL 已考虑所有重定向情况。

string XMLHttpRequest::responseText

返回一个包含从最后一次响应中接收到的数据的 `String `。

var XMLHttpRequest::responseXML

返回一个Document ，或者在响应内容无法解析为XML或HTML时返回null 。有关更多信息，请参阅responseXML文档部分。

var XMLHttpRequest::response

根据上一次请求的responseType，返回String 、ArrayBuffer 或Document 之一。

string XMLHttpRequest::responseType

返回一个String ，描述最后收到的响应的内容类型。

如果响应类型为“text”或一个空的String ，则响应内容是一个 UTF-16 编码的String 。
如果响应类型为“arraybuffer”，则表示响应内容是一个包含二进制数据的ArrayBuffer 。
如果响应类型为“json”，则响应内容应为 JSONDocument 。
如果响应类型为“document”，则表示响应内容是一个 XMLDocument ，可以使用responseXML属性安全地读取。

int XMLHttpRequest::status

返回最后收到的响应的状态码。

string XMLHttpRequest::statusText

返回一个String ，其中包含与上次接收到的响应的状态码相关的状态消息。

另请参阅 getResponseHeader()、getAllResponseHeaders()、readyState、onreadystatechange、responseXML、responseText、responseType、response、statusText 和status。

JavaScript 对象 Date JavaScript 对象和函数列表

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.