diff --git a/.gitignore b/.gitignore index cbe28cb..228fdf1 100644 --- a/.gitignore +++ b/.gitignore @@ -5,7 +5,7 @@ node_modules # Docs dist docs/.vitepress/cache -docs/pages/intro.md +docs/pages/guide/intro.md # Mac OS .DS_Store diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d660129..6da8cea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,13 +12,13 @@ pnpm install ``` -我们使用 VitePress 进行快速开发和文档编制。您可以通过以下方式在本地启动它。 +我们使用 VitePress 进行快速开发和文档编制。可以通过以下方式在本地启动它。 ```bash pnpm docs:dev ``` -我们使用 Vitest 进行单元测试。您可以通过以下方式在本地启动它。 +我们使用 Vitest 进行单元测试。可以通过以下方式在本地启动它。 ```bash pnpm test:watch diff --git a/README.md b/README.md index 4898029..d47f1f5 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ [中文文档](https://axios-miniprogram.com) -## 什么是 axios-miniprogram ? +## axios-miniprogram 是什么? axios-miniprogram 是一款为小程序平台量身定制的轻量级请求库,支持跨平台使用,同时也支持多种导入方式,可用于原生小程序项目,也可用于第三方框架项目,用法上同 [axios](https://github.com/axios/axios.git) 类似。 diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 09773c6..9dfdf90 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -11,13 +11,15 @@ export default defineConfig({ description: '基于 Promise 的 HTTP 请求库,适用于各大小程序平台。', srcDir: 'pages', lastUpdated: true, + cleanUrls: true, themeConfig: { // https://vitepress.dev/reference/default-theme-config nav: [ - { text: '指南', link: '/intro' }, - { text: '基础', link: '/basics/request' }, + { text: '指南', link: '/guide/intro', activeMatch: '/guide/' }, + { text: '请求', link: '/request/options', activeMatch: '/request/' }, + { text: '基础', link: '/basics/config', activeMatch: '/basics/' }, ], sidebar: sidebar(), @@ -82,115 +84,32 @@ function sidebar() { { text: '指南', items: [ - { text: '简介', link: '/intro' }, - { text: '开始', link: '/start' }, + { text: '简介', link: '/guide/intro' }, + { text: '开始', link: '/guide/quick-start' }, + ], + }, + { + text: '请求', + items: [ + { text: 'OPTIONS', link: '/request/OPTIONS' }, + { text: 'GET', link: '/request/GET' }, + { text: 'HEAD', link: '/request/HEAD' }, + { text: 'POST', link: '/request/POST' }, + { text: 'PUT', link: '/request/PUT' }, + { text: 'PATCH', link: '/request/PATCH' }, + { text: 'DELETE', link: '/request/DELETE' }, + { text: 'TRACE', link: '/request/TRACE' }, + { text: 'CONNECT', link: '/request/CONNECT' }, ], }, { text: '基础', items: [ - { text: '发送请求', link: '/basics/request' }, - { text: 'OPTIONS 请求', link: '/basics/options' }, - { text: 'GET 请求', link: '/basics/get' }, - { text: 'HEAD 请求', link: '/basics/head' }, - { text: 'POST 请求', link: '/basics/post' }, - { text: 'PUT 请求', link: '/basics/put' }, - { text: 'PATCH 请求', link: '/basics/patch' }, - { text: 'DELETE 请求', link: '/basics/delete' }, - { text: 'TRACE 请求', link: '/basics/trace' }, - { text: 'CONNECT 请求', link: '/basics/connect' }, + { text: '请求配置', link: '/basics/config' }, { text: '响应体', link: '/basics/response' }, - ], - }, - - { - text: '配置', - items: [ - { - text: '默认配置', - link: '/config/preview', - }, - { - text: 'method', - link: '/config/method', - }, - { - text: 'dataType', - link: '/config/data-type', - }, - { - text: 'responseType', - link: '/config/response-type', - }, - { - text: 'validateStatus', - link: '/config/validate-status', - }, - { - text: 'paramsSerializer', - link: '/config/params-serializer', - }, - { - text: 'transformRequest', - link: '/config/transform-request', - }, - { - text: 'transformResponse', - link: '/config/transform-response', - }, - { - text: 'errorHandler', - link: '/config/error-handler', - }, - { - text: 'upload', - link: '/config/upload', - }, - { - text: 'download', - link: '/config/download', - }, - { - text: 'adapter', - link: '/config/adapter', - }, - ], - }, - { - text: 'API', - items: [ - { - text: 'interceptors', - link: '/api/interceptors', - }, - { - text: 'CancelToken', - link: '/api/cancel-token', - }, - { - text: 'isCancel', - link: '/api/is-cancel', - }, - { - text: 'isAxiosError', - link: '/api/is-axios-error', - }, - { - text: 'getUri', - link: '/api/get-uri', - }, - { - text: 'create', - link: '/api/create', - }, - { - text: 'fork ', - link: '/api/fork', - }, - { - text: 'Axios', - link: '/api/axios', - }, + { text: '发送请求', link: '/basics/request' }, + { text: '上传文件', link: '/basics/upload' }, + { text: '下载文件', link: '/basics/download' }, ], }, { diff --git a/docs/.vitepress/utils/createIntroMD.ts b/docs/.vitepress/utils/createIntroMD.ts index 13a118c..9af2f33 100644 --- a/docs/.vitepress/utils/createIntroMD.ts +++ b/docs/.vitepress/utils/createIntroMD.ts @@ -2,7 +2,7 @@ import { copyFileSync } from 'node:fs'; import { resolve } from '../../../scripts/utils'; const readmePath = resolve('README.md'); -const introPath = resolve('docs/pages/intro.md'); +const introPath = resolve('docs/pages/guide/intro.md'); export function createIntroMD() { copyFileSync(readmePath, introPath); diff --git a/docs/pages/api/axios.md b/docs/pages/api/axios.md deleted file mode 100644 index 62eee10..0000000 --- a/docs/pages/api/axios.md +++ /dev/null @@ -1,19 +0,0 @@ -# Axios - -## `axios.Axios` - -`axios.Axios`是一个类,其实`axios`就是`axios.Axios`类的实例改造而来的,`axios.create(defaults)`创建的也是`axios.Axios`的实例。 - -直接实例化`axios.Axios`可以得到一个`原始实例`,不能当函数调用,传递的自定义配置就是`原始实例`的默认配置,而不会像`axios.create(defaults)`一样去合并`axios`中的默认配置。 - -```ts -const instance = new axios.Axios({ - beseURL: 'https://www.api.com', - params: { - id: 1, - }, -}); - -instance.get('/user'); -// 'https://www.api.com/user?id=1' -``` diff --git a/docs/pages/api/cancel-token.md b/docs/pages/api/cancel-token.md deleted file mode 100644 index 44ff5e8..0000000 --- a/docs/pages/api/cancel-token.md +++ /dev/null @@ -1,29 +0,0 @@ -# CancelToken - -## `axios.CancelToken`取消令牌 - -可以使用`CancelToken`取消已经发出的请求。 - -```ts -let cancel; - -axios('/api', { - cancelToken: new axios.CancelToken(function (c) { - cancel = c; - }), -}); - -cancel('取消请求'); -``` - -还可以使用`CancelToken.source`工厂方法创建`CancelToken`。 - -```ts -const source = axios.CancelToken.source(); - -axios('/api', { - cancelToken: source.token, -}); - -source.cancel('取消请求'); -``` diff --git a/docs/pages/api/create.md b/docs/pages/api/create.md deleted file mode 100644 index 51b08ed..0000000 --- a/docs/pages/api/create.md +++ /dev/null @@ -1,20 +0,0 @@ -# create - -## `axios.create(defaults)` - -创建一个`自定义实例`,传递的自定义默认配置`defaults`会和`axios`的默认配置`axios.defaults`合并成`自定义实例`的默认配置。 - -`自定义实例`拥有和`axios`相同的调用方式和请求方法的别名。 - -```ts -axios.defaults.baseURL = 'https://www.api.com'; - -const instance = axios.create({ - params: { - id: 1, - }, -}); - -instance('/user'); -// 'https://www.api.com/user?id=1' -``` diff --git a/docs/pages/api/fork.md b/docs/pages/api/fork.md deleted file mode 100644 index 7a74092..0000000 --- a/docs/pages/api/fork.md +++ /dev/null @@ -1,22 +0,0 @@ -# fork - -## `axios.fork(defaults)` - -现在很多公司后端采用的是微服务架构,您可以为每个服务单独派生一个领域进行请求管理。 - -派生领域,如果传递 `defaults.baseURL` 为相对路径,则会对 `axios.defaults.baseURL` 和 `defaults.baseURL` 进行拼接。 - -`domain` 除了拥有和 `axios` 相同的调用方式和请求方法的别名之外,同时还可以复用 `axios` 上的拦截器,这一点是 `axios.create(defaults)` 做不到了。 - -```ts -axios.defaults.baseURL = 'https://www.api.com'; - -const domain = axios.fork({ - baseURL: 'user', -}); - -domain.get('/:id', { id: 1 }); // get 'https://www.api.com/user/1?id=1' -domain.post('/', { id: 1 }); // post 'https://www.api.com/user/1' -domain.put('/:id', { id: 1 }); // put 'https://www.api.com/user/1?id=1' -domain.delete('/:id', { id: 1 }); // delete 'https://www.api.com/user/1?id=1' -``` diff --git a/docs/pages/api/get-uri.md b/docs/pages/api/get-uri.md deleted file mode 100644 index c99044e..0000000 --- a/docs/pages/api/get-uri.md +++ /dev/null @@ -1,15 +0,0 @@ -# getUri - -## `axios.getUri(config)` - -根据配置中的`url`和`params`生成一个`URI`。 - -```ts -const uri = axios.getUri({ - url: '/user', - params: { - id: 1, - }, -}); -// '/user?id=1' -``` diff --git a/docs/pages/api/interceptors.md b/docs/pages/api/interceptors.md deleted file mode 100644 index 428ce0f..0000000 --- a/docs/pages/api/interceptors.md +++ /dev/null @@ -1,49 +0,0 @@ -# interceptors - -## `axios.interceptors`拦截器 - -可以先拦截请求或响应,然后再由 then 或 catch 处理。 - -```ts -// 添加请求拦截器 -axios.interceptors.request.use( - function (config) { - // 在发送请求之前做些什么 - return config; - }, - function (error) { - //处理请求错误 - return Promise.reject(error); - }, -); - -// 添加响应拦截器 -axios.interceptors.response.use( - function (response) { - // 请求成功后做些什么 - return response; - }, - function (error) { - // 处理响应错误 - return Promise.reject(error); - }, -); -``` - -如果以后需要删除拦截器,则可以。 - -```ts -const myInterceptor = axios.interceptors.request.use(function () { - // 在发送请求之前做些什么 -}); -axios.interceptors.request.eject(myInterceptor); -``` - -还可以将拦截器添加到`axios`的`自定义实例`中。 - -```ts -const myInterceptor = instance.interceptors.request.use(function () { - // 在发送请求之前做些什么 -}); -instance.interceptors.request.eject(myInterceptor); -``` diff --git a/docs/pages/api/is-axios-error.md b/docs/pages/api/is-axios-error.md deleted file mode 100644 index b07028d..0000000 --- a/docs/pages/api/is-axios-error.md +++ /dev/null @@ -1,21 +0,0 @@ -# isAxiosError - -## `axios.isAxiosError` 是否是 AxiosError - -可以判断当前错误是否来自请求响应,而不是语法错误或者用户主动抛出的错误 - -```ts -axios('/user').catch((error) => { - if (axios.isAxiosError(error)) { - // 错误是否来自原生接口的 fail 回调 - // 如果错误来自对状态码的判断,这种情况是没有这个属性的 - error.isFail; - // 请求配置 - error.config; - // 请求任务 - error.request; - // 响应体 - error.response; - } -}); -``` diff --git a/docs/pages/api/is-cancel.md b/docs/pages/api/is-cancel.md deleted file mode 100644 index eed55f2..0000000 --- a/docs/pages/api/is-cancel.md +++ /dev/null @@ -1,13 +0,0 @@ -# isCancel - -## `axios.isCancel`是否取消 - -可以判断当前错误是否来自取消请求 - -```ts -axios('/user').catch((error) => { - if (axios.isCancel(error)) { - // 请求被取消了 - } -}); -``` diff --git a/docs/pages/basics/config.md b/docs/pages/basics/config.md new file mode 100644 index 0000000..05db93d --- /dev/null +++ b/docs/pages/basics/config.md @@ -0,0 +1,171 @@ +--- +title: 请求配置 +--- + +# {{ $frontmatter.title }} + +::: tip {{ $frontmatter.title }} +用于自定义请求行为。 +::: + +## 通用属性 + +可以设置这些属性。 + +```ts +import axios from 'axios-miniprogram'; + +axios({ + // 开发者服务器接口基础地址 + baseURL: 'https://api.com', + + // 开发者服务器接口地址 + url: '/test', + + // 请求方法 + method: 'POST', + + // 请求参数 + params: { + id: 1, + }, + + // 请求数据 + data: { + name: 'test', + }, + + // 请求头 + headers: { + 'Content-Type': 'application/json', + }, + + // 返回的数据格式 + dataType: 'json', + + // 响应的数据类型 + responseType: 'text', + + // 超时时间,单位为毫秒 + timeout: 10000, + + // 上传 + upload: false, + + // 下载 + download: false, + + // 请求参数系列化函数 + paramsSerializer(params) { + console.log(params); + }, + + // 转换请求数据 + transformRequest(data, headers) { + console.log(data); + }, + + // 转换响应数据 + transformResponse(data, headers) { + console.log(data); + }, + + // 监听上传进度 + onUploadProgress({ progress }) { + console.log(progress); + }, + + // 监听下载进度 + onDownloadProgress({ progress }) { + console.log(progress); + }, + + // 校验状态码 + validateStatus(status) { + console.log(status); + }, + + // 异常处理 + errorHandler(error) { + console.log(error); + }, + + // 适配器 + adapter(config) { + console.log(config); + }, +}) + .then((response) => { + // 成功之后做些什么 + }) + .catch((error) => { + // 失败之后做些什么 + }); +``` + +## 平台属性 + +也可以设置平台特有属性,具体情况取决于平台特性。 + +微信小程序示例: + +```ts +import axios from 'axios-miniprogram'; + +axios + .request({ + // 开启 http2 + enableHttp2: false, + + // 开启 quic + enableQuic: false, + + // 开启 cache + enableCache: false, + + // 是否开启 HttpDNS 服务。如开启,需要同时填入 httpDNSServiceId 。 + enableHttpDNS: false, + + // HttpDNS 服务商 Id。 + httpDNSServiceId: '123', + + // 开启 transfer-encoding chunked。 + enableChunked: false, + + // wifi 下使用移动网络发送请求 + forceCellularNetwork: false, + }) + .then((response) => { + // 成功之后做些什么 + }) + .catch((error) => { + // 失败之后做些什么 + }); +``` + +想要了解更多请自行参阅对应平台文档。 + +## 自定义属性 + +也可以设置自定义属性。 + +自定义属性可以根据需要随意设置。 + +```ts +import axios from 'axios-miniprogram'; + +axios + .request({ + // 这是一个自定义配置 + user: '123', + + // 这也是一个自定义配置 + showLoading: true, + }) + .then((response) => { + // 成功之后做些什么 + }) + .catch((error) => { + // 失败之后做些什么 + }); +``` diff --git a/docs/pages/basics/download.md b/docs/pages/basics/download.md new file mode 100644 index 0000000..10ad9fd --- /dev/null +++ b/docs/pages/basics/download.md @@ -0,0 +1,103 @@ +--- +title: 下载文件 +--- + +# {{ $frontmatter.title }} + +::: tip {{ $frontmatter.title }} +下载文件资源到本地,必须使用 `GET` 方法请求,并将请求配置的 `download` 属性设置为 `true`。 +::: + +## 普通的下载请求 + +可以下载文件资源到本地。 + +```ts +import axios from 'axios-miniprogram'; + +axios + .get( + 'https://api.com/test', + {}, + { + download: true, + }, + ) + .then((response) => { + const { + // 临时文件路径 (本地路径)。没传入 filePath 指定文件存储路径时会返回,下载后的文件会存储到一个临时文件 + tempFilePath, + } = response; + }) + .catch((error) => { + // 失败之后做些什么 + }); +``` + +## 携带参数的下载请求 + +也可以指定文件下载后存储的路径 (本地路径)。 + +```ts +import axios from 'axios-miniprogram'; + +axios + .get( + 'https://api.com/test', + { + filePath: '你的本地路径', + }, + { + download: true, + }, + ) + .then((response) => { + const { + // 指定文件下载后存储的路径 (本地路径) + filePath, + } = response; + }) + .catch((error) => { + // 失败之后做些什么 + }); +``` + +## 监听下载进度 + +也可以监听下载进度变化。 + +```ts +import axios from 'axios-miniprogram'; + +axios + .get( + 'https://api.com/test', + { + filePath: '你的本地路径', + }, + { + download: true, + onDownloadProgress(event) { + const { + // 下载进度 + progress, + + // 已经下载的数据长度 + totalBytesSent, + + // 预期需要下载的数据总长度 + totalBytesExpectedToSend, + } = event; + }, + }, + ) + .then((response) => { + const { + // 指定文件下载后存储的路径 (本地路径) + filePath, + } = response; + }) + .catch((error) => { + // 失败之后做些什么 + }); +``` diff --git a/docs/pages/basics/request.md b/docs/pages/basics/request.md index f77f617..bd58fb5 100644 --- a/docs/pages/basics/request.md +++ b/docs/pages/basics/request.md @@ -10,7 +10,7 @@ title: 发送请求 ## 基础用法 -您可以直接传递 `url` 发送请求,默认发送的是 `GET` 方法请求。 +可以直接传递 `url` 发送请求,默认发送的是 `GET` 方法请求。 ```ts import axios from 'axios-miniprogram'; @@ -25,9 +25,9 @@ axios }); ``` -## 携带自定义配置 +## 携带请求配置 -您也可以传递第二个参数 `config`,用于指定请求方法以及其他配置项。 +也可以传递第二个参数 `config`,用于指定请求方法以及其他配置项。 ```ts import axios from 'axios-miniprogram'; @@ -48,9 +48,9 @@ axios }); ``` -## 仅有自定义配置 +## 仅有请求配置 -您也可以忽略以上示例,直接传递 `config` 发送请求。 +也可以忽略以上示例,直接传递 `config` 发送请求。 ```ts import axios from 'axios-miniprogram'; @@ -72,6 +72,6 @@ axios ## 说明 -您可能发现 `axios.request()` 和 `axios()` 使用方式完全一致,为什么? +您可能发现 `axios.request()` 和 `axios()` 使用方式完全一致,为什么用法是一样的? -其实他们本就是同一个请求函数,`axios` 是基于 `axios.request` 添加了一系列工具函数改造而来,其目的是为了简化使用。 +其实它们本就是同一个请求函数,`axios` 是基于 `axios.request` 添加了一系列工具函数改造而来,其目的是为了简化使用。 diff --git a/docs/pages/basics/response.md b/docs/pages/basics/response.md index 20f13a3..31098f8 100644 --- a/docs/pages/basics/response.md +++ b/docs/pages/basics/response.md @@ -5,7 +5,7 @@ title: 响应体 # {{ $frontmatter.title }} ::: tip {{ $frontmatter.title }} -response 是响应正文。返回的数据类型为 String/Object/ArrayBuffer。这取决于请求的 responseType 属性。 +`response` 是响应正文。返回的数据类型为 `String/Object/ArrayBuffer`。这取决于请求配置的 `responseType` 属性。 ::: ## 通用属性 @@ -20,14 +20,19 @@ axios('https//api.com') const { // 开发者服务器返回的 HTTP 状态码 status, + // 状态文本 statusText, + // 开发者服务器返回的数据 data, + // 开发者服务器返回的响应头 headers, + // 请求配置 config, + // 请求任务 request, } = response; @@ -51,9 +56,9 @@ axios('https//api.com') const { // 开发者服务器返回的 cookies,格式为字符串数组 cookies, + // 网络请求过程中一些调试信息 profile, - // 开发者服务器返回的数据 } = response; }) .catch((error) => { @@ -61,4 +66,4 @@ axios('https//api.com') }); ``` -想要了解更多请自行参阅对应的小程序文档。 +想要了解更多请自行参阅对应平台文档。 diff --git a/docs/pages/basics/upload.md b/docs/pages/basics/upload.md new file mode 100644 index 0000000..e79cedd --- /dev/null +++ b/docs/pages/basics/upload.md @@ -0,0 +1,129 @@ +--- +title: 上传文件 +--- + +# {{ $frontmatter.title }} + +::: tip {{ $frontmatter.title }} +将本地资源上传到服务器,必须使用 `POST` 方法请求,并将请求配置的 `upload` 属性设置为 `true`。 +::: + +## 普通的上传请求 + +可以将本地资源上传到服务器。 + +```ts +import axios from 'axios-miniprogram'; + +axios + .post( + 'https//api.com/test', + { + // 文件对应的 key,开发者在服务端可以通过这个 key 获取文件的二进制内容 + name: 'fileName', + + // 要上传文件资源的路径 (本地路径) + filePath: '你的本地路径', + }, + { + upload: true, + }, + ) + .then((response) => { + const { + // 开发者服务器返回的数据 + data, + } = response; + }) + .catch((error) => { + // 失败之后做些什么 + }); +``` + +## 携带 `formData` 的上传请求 + +也可以携带额外的 `formData` 发送给服务端。 + +```ts +import axios from 'axios-miniprogram'; + +axios + .post( + 'https//api.com/test', + { + // 文件对应的 key,开发者在服务端可以通过这个 key 获取文件的二进制内容 + name: 'fileName', + + // 要上传文件资源的路径 (本地路径) + filePath: '你的本地路径', + + // 这是额外的 formData 属性 + id: 1, + + // 这是额外的 formData 属性 + user: '123', + }, + { + upload: true, + }, + ) + .then((response) => { + const { + // 开发者服务器返回的数据 + data, + } = response; + }) + .catch((error) => { + // 失败之后做些什么 + }); +``` + +## 监听上传进度 + +也可以监听上传进度变化。 + +```ts +import axios from 'axios-miniprogram'; + +axios + .post( + 'https//api.com/test', + { + // 文件对应的 key,开发者在服务端可以通过这个 key 获取文件的二进制内容 + name: 'fileName', + + // 要上传文件资源的路径 (本地路径) + filePath: '你的本地路径', + + // 这是额外的 formData 属性 + id: 1, + + // 这是额外的 formData 属性 + user: '123', + }, + { + upload: true, + onUploadProgress(event) { + const { + // 上传进度 + progress, + + // 已经上传的数据长度 + totalBytesSent, + + // 预期需要上传的数据总长度 + totalBytesExpectedToSend, + } = event; + }, + }, + ) + .then((response) => { + const { + // 开发者服务器返回的数据 + data, + } = response; + }) + .catch((error) => { + // 失败之后做些什么 + }); +``` diff --git a/docs/pages/config/adapter.md b/docs/pages/config/adapter.md deleted file mode 100644 index 8796714..0000000 --- a/docs/pages/config/adapter.md +++ /dev/null @@ -1,65 +0,0 @@ -# adapter - -## 自定义平台适配器`config.adapter` - -您可以手动适配当前所处的平台。 - -```ts -axios.defaults.adapter = function adapter(adapterConfig) { - const { - // 请求类型 - type, - // 请求地址 - url, - // 请求方法 - method, - // 请求参数 - params, - // 请求数据 - data, - // 请求头 同 headers - headers, - // 响应数据格式 - dataType, - // 响应数据类型 - responseType, - // 超时时间 - timeout, - // 成功的回调函数 - success, - // 失败的回调函数 - fail, - } = adapterConfig; - - // 在 adapterConfig 中选择您需要的参数发送请求 - switch (type) { - case 'request': // 数据请求 - return wx.request({ - url, - method, - data, - header: headers, - success, - fail, - }); - case 'upload': // 上传 - return wx.uploadFile({ - url, - method, - formData: data, - header: headers, - success, - fail, - }); - case 'download': // 下载 - return wx.downloadFile({ - url, - method, - filePath: params.filePath, - header: headers, - success, - fail, - }); - } -}; -``` diff --git a/docs/pages/config/data-type.md b/docs/pages/config/data-type.md deleted file mode 100644 index 420ca7b..0000000 --- a/docs/pages/config/data-type.md +++ /dev/null @@ -1,8 +0,0 @@ -# dataType - -## `config.dataType`的合法值 - -| 值 | 说明 | 全平台兼容 | -| :--- | :--------------------------------------------------------- | :--------- | -| json | 返回的数据为 JSON,返回后会对返回的数据进行一次 JSON.parse | 是 | -| 其他 | 不对返回的内容进行 JSON.parse | 是 | diff --git a/docs/pages/config/download.md b/docs/pages/config/download.md deleted file mode 100644 index 7c4274a..0000000 --- a/docs/pages/config/download.md +++ /dev/null @@ -1,27 +0,0 @@ -# download - -## 发送下载请求 - -可以从服务端下载文件到本地 - -- 只有 get 请求才生效 - -```ts -axios - .get( - '/file', - { - // 指定文件下载后存储的路径 (本地路径),选填 - filePath: '/file', - }, - { - download: true, - }, - ) - .then((response) => { - // 用户文件路径 (本地路径)。传递 filePath 时会返回,跟传递的 filePath 一致 - response.data.filePath; - // 用户文件路径 (本地临时路径)。 - response.data.tempFilePath; - }); -``` diff --git a/docs/pages/config/error-handler.md b/docs/pages/config/error-handler.md deleted file mode 100644 index 182fb95..0000000 --- a/docs/pages/config/error-handler.md +++ /dev/null @@ -1,30 +0,0 @@ -# errorHandler - -## 自定义错误处理`config.errorHandler` - -可以添加到默认配置中,统一处理错误。 - -```ts -axios.defaults.errorHandler = function errorHandler(error) { - // 做一些想做的事情 - return Promise.reject(error); -}; - -const instance = axios.create({ - errorHandler: function errorHandler(error) { - // 做一些想做的事情 - return Promise.reject(error); - }, -}); -``` - -也可以发送请求时通过自定义配置传递。 - -```ts -axios('/user', { - errorHandler: function errorHandler(error) { - // 做一些想做的事情 - return Promise.reject(error); - }, -}); -``` diff --git a/docs/pages/config/method.md b/docs/pages/config/method.md deleted file mode 100644 index 281e3a5..0000000 --- a/docs/pages/config/method.md +++ /dev/null @@ -1,16 +0,0 @@ -# method - -## `config.method`的合法值 - -可以使用大写,也可以使用小写。 - -| 值 | 说明 | 全平台兼容 | -| :------ | :--- | :--------- | -| OPTIONS | | | -| GET | | 是 | -| HEAD | | | -| POST | | 是 | -| PUT | | 是 | -| DELETE | | 是 | -| TRACE | | | -| CONNECT | | | diff --git a/docs/pages/config/params-serializer.md b/docs/pages/config/params-serializer.md deleted file mode 100644 index f941a71..0000000 --- a/docs/pages/config/params-serializer.md +++ /dev/null @@ -1,15 +0,0 @@ -# paramsSerializer - -## 自定义参数序列化`config.paramsSerializer` - -可以使用自己的规则去序列化参数。 - -```ts -axios('/user', { - paramsSerializer: function paramsSerializer(params) { - return qs.stringify(params, { - arrayFormat: 'brackets', - }); - }, -}); -``` diff --git a/docs/pages/config/preview.md b/docs/pages/config/preview.md deleted file mode 100644 index 7f092e2..0000000 --- a/docs/pages/config/preview.md +++ /dev/null @@ -1,69 +0,0 @@ -# 默认配置 - -## 全局默认配置`axios.defaults` - -```ts -axios.defaults.baseURL = 'https://www.api.com'; -axios.defaults.headers.common['Accept'] = 'application/json, test/plain, */*'; -axios.defaults.headers.post['Content-Type'] = - 'application/x-www-form-urlencoded; charset=utf-8'; -``` - -## 自定义实例默认配置 - -可以创建时传递。 - -```ts -const instance = axios.create({ - baseURL: 'https://www.api.com', - headers: { - common: { - Accept: 'application/json, test/plain, */*', - }, - post: { - 'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8', - }, - }, -}); -``` - -也可以创建后修改。 - -```ts -instance.defaults.baseURL = 'https://www.api.com'; -instance.defaults.headers.common['Accept'] = - 'application/json, test/plain, */*'; -instance.defaults.headers.post['Content-Type'] = - 'application/x-www-form-urlencoded; charset=utf-8'; -``` - -## 配置优先顺序 - -发送请求时,会使用默认配置`defaults`和自定义配置`config`合并出请求配置`requestConfig`,然后用合并出的请求配置`requestConfig`去发送请求,多数情况下,后者优先级要高于前者,具体合并策略可以参考 [mergeConfig.ts](https://github.com/early-autumn/axios-miniprogram/blob/master/src/core/mergeConfig.ts) 的实现。 - -## 配置表 - -非全平台兼容的属性只会在平台支持的情况下生效。 - -| 参数 | 类型 | 默认值 | 说明 | 全平台兼容 | -| :---------------- | :-----------------------: | :------------------------------------------------------------------------------------ | :----------------- | :--------- | -| adapter | Function | [查看](https://github.com/early-autumn/axios-miniprogram/blob/master/src/defaults.ts) | 自定义适配器 | 是 | -| baseURL | String | | 基础地址 | 是 | -| url | String | | 请求地址 | 是 | -| method | String | get | 请求方法 | | -| params | Object | | 请求参数 | 是 | -| data | String/Object/ArrayBuffer | | 请求数据 | 是 | -| headers | Object | [查看](https://github.com/early-autumn/axios-miniprogram/blob/master/src/defaults.ts) | 请求头 | 是 | -| validateStatus | Function | [查看](https://github.com/early-autumn/axios-miniprogram/blob/master/src/defaults.ts) | 自定义合法状态码 | 是 | -| paramsSerializer | Function | | 自定义参数序列化 | 是 | -| transformRequest | Function/Array\ | | 自定义转换请求数据 | 是 | -| transformResponse | Function/Array\ | | 自定义转换响应数据 | 是 | -| errorHandler | Function | | 自定义错误处理 | 是 | -| cancelToken | Object | | 取消令牌 | 是 | -| timeout | Number | 10000 | 超时时间 | | -| dataType | String | json | 响应数据格式 | 是 | -| responseType | String | text | 响应数据类型 | 是 | -| enableHttp2 | Boolean | false | 开启 http2 | | -| enableQuic | Boolean | false | 开启 quic | | -| enableCache | Boolean | false | 开启 cache | | -| sslVerify | Boolean | true | 验证 ssl 证书 | | diff --git a/docs/pages/config/response-type.md b/docs/pages/config/response-type.md deleted file mode 100644 index b9ffdf5..0000000 --- a/docs/pages/config/response-type.md +++ /dev/null @@ -1,8 +0,0 @@ -# responseType - -## `config.responseType`的合法值 - -| 值 | 说明 | 全平台兼容 | -| :---------- | :----------------------- | :--------- | -| text | 响应的数据为文本 | 是 | -| arraybuffer | 响应的数据为 ArrayBuffer | 是 | diff --git a/docs/pages/config/transform-request.md b/docs/pages/config/transform-request.md deleted file mode 100644 index c84b29b..0000000 --- a/docs/pages/config/transform-request.md +++ /dev/null @@ -1,16 +0,0 @@ -# transformRequest - -## `config.transformRequest`自定义转换请求数据 - -可以在请求发出之前转换请求数据。 - -```ts -axios('/user', { - transformRequest: [ - function transformRequest(data, headers) { - // 转换请求数据 - return data; - }, - ], -}); -``` diff --git a/docs/pages/config/transform-response.md b/docs/pages/config/transform-response.md deleted file mode 100644 index 0aee5ce..0000000 --- a/docs/pages/config/transform-response.md +++ /dev/null @@ -1,16 +0,0 @@ -# transformResponse - -## `config.transformResponse`自定义转换响应数据 - -可以在请求发出之前转换请求数据。 - -```ts -axios('/user', { - transformResponse: [ - function transformResponse(data, headers) { - // 转换请求数据 - return data; - }, - ], -}); -``` diff --git a/docs/pages/config/upload.md b/docs/pages/config/upload.md deleted file mode 100644 index 8074c11..0000000 --- a/docs/pages/config/upload.md +++ /dev/null @@ -1,25 +0,0 @@ -# upload - -## 发送上传请求 - -可以上传文件到服务端 - -- 只有 post 请求才生效 - -```ts -axios.post( - '/file', - { - // 文件名称,必填 - name: 'file', - // 文件路径,必填 - filePath: '/file/image.png', - // 可以传递更多自定义字段,这些自定义字段最终会以 formData 的形式发送给服务端 (前提是平台支持) - custom1: 'name', - custom2: 'id', - }, - { - upload: true, - }, -); -``` diff --git a/docs/pages/config/validate-status.md b/docs/pages/config/validate-status.md deleted file mode 100644 index 5203c44..0000000 --- a/docs/pages/config/validate-status.md +++ /dev/null @@ -1,14 +0,0 @@ -# validateStatus - -## 自定义合法状态码`config.validateStatus` - -可以让请求按照您的要求成功或者失败。 - -```ts -axios('/user', { - validateStatus: function validateStatus(status) { - // 这样,状态码在 200 到 400 之间都是请求成功 - return status >= 200 && status < 400; - }, -}); -``` diff --git a/docs/pages/start.md b/docs/pages/guide/quick-start.md similarity index 73% rename from docs/pages/start.md rename to docs/pages/guide/quick-start.md index 799322a..3935b02 100644 --- a/docs/pages/start.md +++ b/docs/pages/guide/quick-start.md @@ -1,8 +1,8 @@ --- -title: 快速上手 +title: 开始 --- -# 快速上手 +# {{ $frontmatter.title }} ## 安装 @@ -34,7 +34,7 @@ import axios from 'axios-miniprogram'; axios('test'); ``` -```ts [Commonjs] +```ts [CommonJS] const axios = require('axios-miniprogram').default; axios('test'); @@ -105,18 +105,18 @@ axios({ }); ``` -还可以使用请求方法的别名来简化请求。 +也可以使用请求方法简化请求。 -- [axios.request(url, config?) | axios.request(config)](./basics/request.md) -- [axios.options(url, config?)](./basics/options.md) -- [axios.get(url, params?, config?)](./basics/get.md) -- [axios.head(url, params?, config?)](./basics/head.md) -- [axios.post(url, data?, config?)](./basics/post.md) -- [axios.put(url, data?, config?)](./basics/put.md) -- [axios.patch(url, data?, config?)](./basics/patch.md) -- [axios.delete(url, params?, config?)](./basics/delete.md) -- [axios.trace(url, config?)](./basics/trace.md) -- [axios.connect(url, config?)](./basics/connect.md) +- [axios.request(url, config?) | axios.request(config)](/basics/request) +- [axios.options(url, config?)](/request/OPTIONS) +- [axios.get(url, params?, config?)](/request/GET) +- [axios.head(url, params?, config?)](/request/HEAD) +- [axios.post(url, data?, config?)](/request/POST) +- [axios.put(url, data?, config?)](/request/PUT) +- [axios.patch(url, data?, config?)](/request/PATCH) +- [axios.delete(url, params?, config?)](/request/DELETE) +- [axios.trace(url, config?)](/request/TRACE) +- [axios.connect(url, config?)](/request/CONNECT) 还提供了一系列工具方法。 diff --git a/docs/pages/index.md b/docs/pages/index.md index 8a34fe8..9b8e81b 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -9,10 +9,10 @@ hero: actions: - theme: alt text: 简介 - link: /intro + link: /guide/intro - theme: brand - text: 开始 - link: /start + text: 快速开始 + link: /guide/quick-start features: - title: 节省空间 diff --git a/docs/pages/basics/connect.md b/docs/pages/request/CONNECT.md similarity index 80% rename from docs/pages/basics/connect.md rename to docs/pages/request/CONNECT.md index 7fe7f63..1269696 100644 --- a/docs/pages/basics/connect.md +++ b/docs/pages/request/CONNECT.md @@ -10,7 +10,7 @@ title: CONNECT 请求 ## 普通的 `CONNECT` 请求 -您可以传递第一个参数 `url` 发送 `CONNECT` 请求。 +可以传递第一个参数 `url` 发送 `CONNECT` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -25,9 +25,9 @@ axios }); ``` -## 携带自定义配置的 `CONNECT` 请求 +## 携带请求配置的 `CONNECT` 请求 -您也可以额外传递第二个参数 `config` 发送携带自定义配置的 `CONNECT` 请求。 +也可以额外传递第二个参数 `config` 发送携带请求配置的 `CONNECT` 请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/delete.md b/docs/pages/request/DELETE.md similarity index 78% rename from docs/pages/basics/delete.md rename to docs/pages/request/DELETE.md index 6965059..99545fd 100644 --- a/docs/pages/basics/delete.md +++ b/docs/pages/request/DELETE.md @@ -10,7 +10,7 @@ HTTP DELETE 请求方法用于删除指定的资源。 ## 普通的 `DELETE` 请求 -您可以传递第一个参数 `url` 发送 `DELETE` 请求。 +可以传递第一个参数 `url` 发送 `DELETE` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -27,7 +27,7 @@ axios ## 携带参数的 `DELETE` 请求 -您也可以额外传递第二个参数 `params` 发送携带参数的 `DELETE` 请求。 +也可以额外传递第二个参数 `params` 发送携带参数的 `DELETE` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -44,9 +44,9 @@ axios }); ``` -## 携带自定义配置的 `DELETE` 请求 +## 携带请求配置的 `DELETE` 请求 -您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `DELETE` 请求。 +也可以额外传递第三个参数 `config` 发送携带请求配置的 `DELETE` 请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/get.md b/docs/pages/request/GET.md similarity index 79% rename from docs/pages/basics/get.md rename to docs/pages/request/GET.md index b875936..d452697 100644 --- a/docs/pages/basics/get.md +++ b/docs/pages/request/GET.md @@ -10,7 +10,7 @@ HTTP GET 方法请求指定的资源。使用 GET 的请求应该只用于获取 ## 普通的 `GET` 请求 -您可以传递第一个参数 `url` 发送 `GET` 请求。 +可以传递第一个参数 `url` 发送 `GET` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -27,7 +27,7 @@ axios ## 携带参数的 `GET` 请求 -您也可以额外传递第二个参数 `params` 发送携带参数的 `GET` 请求。 +也可以额外传递第二个参数 `params` 发送携带参数的 `GET` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -44,9 +44,9 @@ axios }); ``` -## 携带自定义配置的 `GET` 请求 +## 携带请求配置的 `GET` 请求 -您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `GET` 请求。 +也可以额外传递第三个参数 `config` 发送携带请求配置的 `GET` 请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/head.md b/docs/pages/request/HEAD.md similarity index 81% rename from docs/pages/basics/head.md rename to docs/pages/request/HEAD.md index 87e79b3..cd2c642 100644 --- a/docs/pages/basics/head.md +++ b/docs/pages/request/HEAD.md @@ -10,7 +10,7 @@ HTTP HEAD 方法请求资源的头部信息,并且这些头部与 HTTP GET 方 ## 普通的 `HEAD` 请求 -您可以传递第一个参数 `url` 发送 `HEAD` 请求。 +可以传递第一个参数 `url` 发送 `HEAD` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -27,7 +27,7 @@ axios ## 携带参数的 `HEAD` 请求 -您也可以额外传递第二个参数 `params` 发送携带参数的 `HEAD` 请求。 +也可以额外传递第二个参数 `params` 发送携带参数的 `HEAD` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -44,9 +44,9 @@ axios }); ``` -## 携带自定义配置的 `HEAD` 请求 +## 携带请求配置的 `HEAD` 请求 -您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `HEAD` 请求。 +也可以额外传递第三个参数 `config` 发送携带请求配置的 `HEAD` 请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/options.md b/docs/pages/request/OPTIONS.md similarity index 80% rename from docs/pages/basics/options.md rename to docs/pages/request/OPTIONS.md index 9629cc0..e1525a7 100644 --- a/docs/pages/basics/options.md +++ b/docs/pages/request/OPTIONS.md @@ -10,7 +10,7 @@ HTTP OPTIONS 方法用于获取目的资源所支持的通信选项。客户端 ## 普通的 `OPTIONS` 请求 -您可以传递第一个参数 `url` 发送 `OPTIONS` 请求。 +可以传递第一个参数 `url` 发送 `OPTIONS` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -25,9 +25,9 @@ axios }); ``` -## 携带自定义配置的 `OPTIONS` 请求 +## 携带请求配置的 `OPTIONS` 请求 -您也可以额外传递第二个参数 `config` 发送携带自定义配置的 `OPTIONS` 请求。 +也可以额外传递第二个参数 `config` 发送携带请求配置的 `OPTIONS` 请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/patch.md b/docs/pages/request/PATCH.md similarity index 82% rename from docs/pages/basics/patch.md rename to docs/pages/request/PATCH.md index 6e05803..4488411 100644 --- a/docs/pages/basics/patch.md +++ b/docs/pages/request/PATCH.md @@ -12,7 +12,7 @@ title: PATCH 请求 ## 普通的 `PATCH` 请求 -您可以传递第一个参数 `url` 发送 `PATCH` 请求。 +可以传递第一个参数 `url` 发送 `PATCH` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -29,7 +29,7 @@ axios ## 携带数据的 `PATCH` 请求 -您也可以额外传递第二个参数 `data` 发送携带数据的 `PATCH` 请求。 +也可以额外传递第二个参数 `data` 发送携带数据的 `PATCH` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -47,9 +47,9 @@ axios }); ``` -## 携带自定义配置的 `PATCH` 请求 +## 携带请求配置的 `PATCH` 请求 -您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `PATCH` 请求。 +也可以额外传递第三个参数 `config` 发送携带请求配置的 `PATCH` 请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/post.md b/docs/pages/request/POST.md similarity index 80% rename from docs/pages/basics/post.md rename to docs/pages/request/POST.md index 3d0e58a..3739a20 100644 --- a/docs/pages/basics/post.md +++ b/docs/pages/request/POST.md @@ -10,7 +10,7 @@ HTTP POST 方法发送数据给服务器。请求主体的类型由 Content-Type ## 普通的 `POST` 请求 -您可以传递第一个参数 `url` 发送 `POST` 请求。 +可以传递第一个参数 `url` 发送 `POST` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -27,7 +27,7 @@ axios ## 携带数据的 `POST` 请求 -您也可以额外传递第二个参数 `data` 发送携带数据的 `POST` 请求。 +也可以额外传递第二个参数 `data` 发送携带数据的 `POST` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -45,9 +45,9 @@ axios }); ``` -## 携带自定义配置的 `POST` 请求 +## 携带请求配置的 `POST` 请求 -您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `POST` 请求。 +也可以额外传递第三个参数 `config` 发送携带请求配置的 `POST` 请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/put.md b/docs/pages/request/PUT.md similarity index 80% rename from docs/pages/basics/put.md rename to docs/pages/request/PUT.md index 6428af5..4d9e905 100644 --- a/docs/pages/basics/put.md +++ b/docs/pages/request/PUT.md @@ -10,7 +10,7 @@ HTTP PUT 请求方法使用请求中的数据创建或者替换目标资源。 ## 普通的 `PUT` 请求 -您可以传递第一个参数 `url` 发送 `PUT` 请求。 +可以传递第一个参数 `url` 发送 `PUT` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -27,7 +27,7 @@ axios ## 携带数据的 `PUT` 请求 -您也可以额外传递第二个参数 `data` 发送携带数据的 `PUT` 请求。 +也可以额外传递第二个参数 `data` 发送携带数据的 `PUT` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -46,9 +46,9 @@ axios }); ``` -## 携带自定义配置的 `PUT` 请求 +## 携带请求配置的 `PUT` 请求 -您也可以额外传递第三个参数 `config` 发送携带自定义配置的 `PUT` 请求。 +也可以额外传递第三个参数 `config` 发送携带请求配置的 `PUT` 请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/trace.md b/docs/pages/request/TRACE.md similarity index 80% rename from docs/pages/basics/trace.md rename to docs/pages/request/TRACE.md index b90b25c..ce93834 100644 --- a/docs/pages/basics/trace.md +++ b/docs/pages/request/TRACE.md @@ -10,7 +10,7 @@ HTTP TRACE 方法实现沿通向目标资源的路径的消息环回(loop-back ## 普通的 `TRACE` 请求 -您可以传递第一个参数 `url` 发送 `TRACE` 请求。 +可以传递第一个参数 `url` 发送 `TRACE` 请求。 ```ts import axios from 'axios-miniprogram'; @@ -25,9 +25,9 @@ axios }); ``` -## 携带自定义配置的 `TRACE` 请求 +## 携带请求配置的 `TRACE` 请求 -您也可以额外传递第二个参数 `config` 发送携带自定义配置的 `TRACE` 请求。 +也可以额外传递第二个参数 `config` 发送携带请求配置的 `TRACE` 请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/src/core/Axios.ts b/src/core/Axios.ts index 2fe0193..0f868c3 100644 --- a/src/core/Axios.ts +++ b/src/core/Axios.ts @@ -85,8 +85,17 @@ export type AxiosRequestData = AnyObject | AxiosRequestFormData; export type AxiosResponseData = undefined | number | AxiosAdapterResponseData; export interface AxiosProgressEvent { + /** + * 下载进度 + */ progress: number; + /** + * 已经下载的数据长度 + */ totalBytesSent: number; + /** + * 预期需要下载的数据总长度 + */ totalBytesExpectedToSend: number; } diff --git a/test/core/mergeConfig.test.ts b/test/core/mergeConfig.test.ts index 7be708a..866c49a 100644 --- a/test/core/mergeConfig.test.ts +++ b/test/core/mergeConfig.test.ts @@ -174,7 +174,7 @@ describe('src/core/mergeConfig.ts', () => { }); }); - test('应该支持自定义配置', () => { + test('应该支持请求配置', () => { const c1 = { custom1: 1, custom2: 'c1',