ajax
一个脚本专用的ajax封装库,集成了GM_xmlhttpRequest和XMLHttpRequest。
Today's Installations
4
Total Installations
102,323
Creation Date
2022-07-23T04:09:51+00:00
Update Date
2022-10-15T14:42:08+00:00
User Rating
10.0
// @require https://scriptcat.org/lib/532/1.0.2/ajax.js
Forum Post
v1.0.2@require库

一个脚本专用的ajax封装库,集成了GM_xmlhttpRequest和XMLHttpRequest。当运行环境中存在GM_xmlhttpRequest或GM.xmlHttpRequest时,请求将自动使用他们,否则使用XMLHttpRequest(指定_mode参数可改变这一行为)。

注意:库本身没有声明脚本权限的能力,必要的油猴参数仍需要在自己的脚本中声明,如@grant GM_xmlhttpRequest和@connect。

发送请求

使用ajax函数发送请求,使用示例:

const json = await ajax('https://www.example.com/', {
    method: 'post',
    data: {
        message: 'hello world'
    },
    responseType: 'json',
    _nocatch: true
})

ajax函数接收两个参数,第一个参数为url,第二个参数为请求的配置对象(可省),返回值为包含响应内容的Promise(取决于_detail参数)。配置对象的参数说明如下:

method
默认值get。不区分大小写。

data
post请求下,data和Content-Type具有自适应的特点。

若未指定Content-Type:
data为字符串时:
Content-Type将被自动设置为application/x-www-form-urlencoded。

data为普通的简单对象时:
转换为以&拼接的url字符串,Content-Type设置为application/x-www-form-urlencoded。

data为嵌套对象的简单对象时:
转换为json字符串,Content-Type设置为application/json。

其他情况(FormData、Blob等):
Content-Type留空,由浏览器自动处理。

若指定了以下Content-Type:

application/x-www-form-urlencoded:
非字符串的data将被转换为url字符串。

application/json:
非字符串的data将被转换为json字符串。

特别地,get请求也可以指定data,数据将被转换为url字符串并拼接到url中,可以在数据较多时写成对象形式并利用此特性。

responseType
默认值text。指定响应类型,若为json将尽可能解析为对象(部分请求的json字符串可能被序列化多次),解析失败发生错误。对于旧版油猴的document和旧版脚本猫的text、json等bug表现均做了兼容处理。

其他受GM_xhr和xhr支持的参数
请自行查询相关文档(注意两者支持的参数不尽相同),不受支持的参数将被忽略。

以下参数由库内部管理,因此必定被忽略:
onload
onerror
onabort
ontimeout

以下参数是此库特有的:
_mode
规定请求使用的API,应是以下字符串之一:
GM_xmlhttpRequest、GM_xhr、GM.xmlHttpRequest、GM.xhr、XMLHttpRequest、xhr

_status
默认值[200]。一个包含成功状态码的数组,通常情况下只有状态码为200才被认为是成功的,否则视为错误。如果你想指定其他状态码为成功响应,将其加入此数组。

_nocatch
默认值false。规定是否不对返回的Promise做错误处理(即不发生reject),若为true且发生错误,Promise将不再抛出错误,而是返回null(受_detail影响)。这一参数主要用于async/await模式,可避免频繁的try...catch语句。
注意:即便_nocatch为true,当请求404或因跨域等问题失败时,控制台仍可能抛出错误。这是xhr的设计所致,此类错误无法通过脚本捕获,但不阻塞代码的运行。

_detail
默认值false。为false时,返回值即响应内容;为true时,返回包含响应信息的对象,包括finalUrl、status、response和responseHeaders。若_nocatch_detail均为true,发生错误时将返回错误信息,包括url、status和error。

默认配置

当ajax的第一个参数为字符串default时,函数功能改为指定默认配置,后续请求的配置对象将与默认配置合并。示例:

ajax('default', {
    method: 'post',
    responseType: 'json',
    _nocatch: true
});
ajax('https://www.example.com/', {
    data: {
        message: 'hello'
    }
});
ajax('https://www.example.com/', {
    data: {
        message: 'world'
    }
});

中断请求

当ajax的第一个参数为字符串abort时,函数功能改为中断请求,第二个参数必须是请求返回的Promise。示例:

const request = ajax('https://www.example.com/', {
    onreadystatechange: xhr => {
        if (xhr.readyState === 2) {
            ajax('abort', request);
        }
    }
});

注意:在GM_xmlhttpRequest中,响应较快的请求可能导致abort不生效;在GM.xmlHttpRequest中,abort必定不生效;旧版脚本猫无法abort。这些均是脚本管理器自身的问题,意味着中断命令并不总是可靠的

更新日志

1.0.0 初始版本
1.0.1 优化错误信息的toString函数。
1.0.2 对响应头中的重复字段做合并处理。

Script Score