diff --git a/docs/pages/advanced/adapter.md b/docs/pages/advanced/adapter.md index 22adc86..2dfdc05 100644 --- a/docs/pages/advanced/adapter.md +++ b/docs/pages/advanced/adapter.md @@ -4,4 +4,249 @@ title: 适配器 # {{ $frontmatter.title }} -待续... +::: tip {{ $frontmatter.title }} +用于支持更多小程序平台或小程序框架。 +::: + +## 基本配置 + +可以接收基本配置。 + +```ts +import axios from 'axios-miniprogram'; + +axios.defaults.adapter = (config) => { + // 配置项 + const { + // 请求类型 + // 'request' | 'upload' | 'download' + type, + + // 开发者服务器接口地址 + url, + + // HTTP 请求方法 + method, + + // 请求参数 + params, + + // 请求数据 + data, + + // 请求头 + headers, + + // 返回的数据格式 + dataType, + + // 响应的数据类型 + responseType, + + // 超时时间 + timeout, + + // 成功的回调 + success, + + // 失败的回调 + fail, + } = config; +}; +``` + +## 其他配置 + +可以接收任意多个其他配置。 + +```ts +import axios from 'axios-miniprogram'; + +axios.defaults.adapter = (config) => { + const { + // 其他配置 + other1, + + // 其他配置 + other2, + } = config; +}; + +axios('https://api.com', { + other1: true, + other2: true, +}); +``` + +## 实现一个适配器 + +适配的本质就是对配置项进行转换,甚至可以零逻辑完成适配。 + +这里用适配 uni-app 举例,适配其他平台其实大同小异。 + +```ts +import axios from 'axios-miniprogram'; + +// 适配器 +axios.defaults.adapter = (config) => { + switch (config.type) { + case 'request': + // 适配请求数据 + return uni.request({ + url: config.url, + data: config.data, + header: config.headers, + method: config.method, + timeout: config.timeout, + dataType: config.dataType, + responseType: config.responseType, + sslVerify: config.sslVerify, + withCredentials: config.withCredentials, + firstIpv4: config.firstIpv4, + enableHttp2: config.enableHttp2, + enableQuic: config.enableQuic, + enableCache: config.enableCache, + enableHttpDNS: config.enableHttpDNS, + httpDNSServiceId: config.httpDNSServiceId, + enableChunked: config.enableChunked, + forceCellularNetwork: config.forceCellularNetwork, + enableCookie: config.enableCookie, + cloudCache: config.cloudCache, + defer: config.defer, + success: (response) => { + config.success({ + // 状态码 + status: response.statusCode, + + // 状态文本 + statusText: 'OK', + + // 响应头 + headers: response.header ?? {}, + + // 响应数据 + data: response.data, + + // cookie 列表 + cookies: response.cookies, + }); + }, + fail: (error) => { + config.fail({ + // 状态码 + status: '400', + + // 状态文本 + statusText: 'Fail Adapter', + + // 响应头 + headers: {}, + + // 响应数据 + data: error, + }); + }, + }); + case 'upload': + // 适配上传文件 + const { files, fileType, file, filePath, name, ...formData } = + config.data; + return uni.uploadFile({ + url: config.url, + files, + fileType, + file, + filePath, + name, + formData, + header: config.headers, + timeout: config.timeout, + success: (response) => { + config.success({ + // 状态码 + status: response.statusCode, + + // 状态文本 + statusText: 'OK', + + // 响应头 + headers: response.header ?? {}, + + // 响应数据 + data: response.data, + }); + }, + fail: (error) => { + config.fail({ + // 状态码 + status: '400', + + // 状态文本 + statusText: 'Fail Adapter', + + // 响应头 + headers: {}, + + // 响应数据 + data: error, + }); + }, + }); + case 'download': + // 适配下载文件 + return uni.downloadFile({ + url: config.url, + filePath: config.params?.filePath, + header: config.headers, + timeout: config.timeout, + success: (response) => { + config.success({ + // 状态码 + status: response.statusCode, + + // 状态文本 + statusText: 'OK', + + // 响应头 + headers: response.header ?? {}, + + // 响应数据 + data: { + filePath: response.filePath, + tempFilePath: response.tempFilePath, + }, + }); + }, + fail: (error) => { + config.fail({ + // 状态码 + status: '400', + + // 状态文本 + statusText: 'Fail Adapter', + + // 响应头 + headers: {}, + + // 响应数据 + data: error, + }); + }, + }); + } +}; +``` + +## 使用 `createAdapter` 实现适配 + +可以使用 `createAdapter` 简化适配流程,但这不能保证完美适配小程序以外的其他平台,如 h5,APP。 + +```ts +import axios from 'axios-miniprogram'; + +axios.defaults.adapter = axios.createAdapter({ + request: uni.request, + upload: uni.uploadFile, + download: uni.downloadFile, +}); +```