mp-network

mp-network

小程序 网络请求 API（request/upload/download） 的二次封装，适配多个小程序平台。

• 支持 微信小程序、支付宝小程序、百度小程序、字节跳动小程序、QQ 小程序、uniapp、Taro
• 支持 Typescript 类型
• 支持 Promise
• 支持 拦截器
• 支持 取消请求
• 支持 上传/下载， 进度监听

安装

# npm
npm i mp-network
# yarn
yarn add mp-network
# pnpm
pnpm add mp-network

使用

原生小程序

由于 原生小程序不支持通过 包管理工具安装的方式，从 node_modules 中引入包， 需要手动从 dist/index.cjs 中复制代码，到你的本地项目文件中后，再进行引入。

注： dist/index.cjs 是 commonjs 格式的代码文件

其他小程序框架

引入

import { download, request, upload } from 'mp-network'

示例1：promise

// 发起 get 请求
request.get('https://example.com/a', { a: 1 })
  .then((response) => {
    console.log(response)
  })

// 发起 post 请求
request.post('https://example.com/b', { b: 1 })
  .then((response) => {
    console.log(response)
  })

// 上传文件
upload('https://example.com/upload', { filePath: '/local/1.txt', name: '1.txt' })
  .then((response) => {
    console.log(response)
  })

// 下载文件
download('https://example.com/download', 'local/1.txt')
  .then((response) => {
    console.log(response)
  })

示例2：async/await

async function fetchData() {
  const response = await request.get('https://example.com')
  console.log(response)
}

示例3：取消请求

const promise1 = request.get('https://example.com')

promise1.then((response) => console.log(response))
// 取消请求
promise1.abort()
// ----
// async / await
const promise2 = request.get('https://example.com')

// 取消请求
promise2.abort()

const response = await promise2

示例4：上传进度

const uploadPromise = upload('https://example.com/upload', { filePath: '/local/1.txt', name: '1.txt' })
uploadPromise.onProgressUpdate((res) => {
  // res.progress  上传进度百分比
  // res.totalBytesSent  已经上传的数据长度，单位 Bytes
  // res.totalBytesExpectedToSend  预期需要上传的数据总长度，单位 Bytes
})

示例5： 下载进度

const downloadPromise = download('https://example.com/download')
downloadPromise.onProgressUpdate((res) => {
  // res.progress   下载进度百分比
  // res.totalBytesWritten   已经下载的数据长度，单位 Bytes
  // res.totalBytesExpectedToWrite  预期需要下载的数据总长度，单位 Bytes
})

示例6： 请求拦截器

// 请求体拦截器
request.interceptor.request.use((config) => {
  // do something
  // 必须返回 config
  return config
})
request.interceptor.response.use((config) => {
  // do something
  
  // 返回处理后的数据
  return config.data
})

Methods

request

MPRequest 实例

• request.get(url[, data, options]): RequestPromise
• request.post(url[, data, options]): RequestPromise
• request.put(url[, data, options]): RequestPromise
• request.head(url[, data, options]): RequestPromise
• request.connect(url[, data, options]): RequestPromise
• request.trace(url[, data, options]): RequestPromise

参数说明

• url 必填。请求地址。 string
• data 选填。请求数据。 string/object/ArrayBuffer
• options 选填。请求设置 RequestOptions
  • RequestOptions

返回值说明

RequestPromise 是一个 promise， 支持以下方法：

• promise.then(fulfilled) fulfilled(response) 说明

  字段	描述
  data	服务器返回的数据
  statusCode	服务器返回的http状态码
  header	服务器返回的 header 响应头
  cookies	服务器返回的 cookies
  profile	请求调试信息

• promise.catch(rejected) rejected(error) 说明

  字段	描述
  errno	错误码
  errMsg	错误信息

• promise.abort() 中止请求
• promise.onChunkReceived(listener) 监听 Transfer-Encoding Chunk Received 事件。
• promise.offChunkReceived(listener) 取消监听
• promise.onHeadersReceived(listener) 监听 HTTP Response Header 事件
• promise.offHeadersReceived(listener) 取消监听

拦截器

• request.interceptor 拦截器
  • request.interceptor.request.use(fulfilled, rejected) 请求体拦截器
  • request.interceptor.response.use(fulfilled, rejected) 响应体拦截器

upload

文件上传请求

upload(url, data[, options]): UploadPromise

参数说明

• url 必填。上传请求地址. string
• data 必填。上传文件时发送的数据， object

  字段	必填	描述
  filePath	是	要上传文件资源的路径 (本地路径)
  name	是	文件对应的 key
  [string]	否	附加其他的数据

• options 选填。 请求设置。UploadRequestOptions
  • UploadRequestOptions

返回参数说明

UploadPromise 是一个 promise，支持以下方法：

• promise.then(fulfilled) fulfilled(response)

  字段	描述
  data	服务器返回的数据
  statusCode	服务器返回的http状态码
  profile	请求调试信息

• promise.catch(rejected) rejected(error) 说明

  字段	描述
  errno	错误码
  errMsg	错误信息

• promise.abort() 中止请求
• promise.onHeadersReceived(listener) 监听 HTTP Response Header 事件
• promise.offHeadersReceived(listener) 取消监听
• promise.onProgressUpdate(listener) 监听上传进度 listener(res) res 说明：

  字段	描述
  progress	上传进度百分比
  totalBytesSent	已经上传的数据长度，单位 Bytes
  totalBytesExpectedToSend	预期需要上传的数据总长度，单位 Bytes

• promise.offProgressUpdate(listener) 取消监听

download

文件上传请求

download(url[, filePath, options]): DownloadPromise

参数说明

• url 必填。下载请求地址. string
• filePath 选填。指定文件下载后存储的路径 (本地路径)， string
• options 选填。 请求设置。DownloadRequestOptions
  • DownloadRequestOptions

返回参数说明

DownloadPromise 是一个 promise，支持以下方法：

• promise.then(fulfilled) fulfilled(response)

  字段	描述
  tempFilePath	临时文件路径 (本地路径)
  filePath	用户文件路径 (本地路径)。
  statusCode	服务器返回的http状态码
  profile	请求调试信息

• promise.catch(rejected) rejected(error) 说明

  字段	描述
  errno	错误码
  errMsg	错误信息

• promise.abort() 中止请求
• promise.onHeadersReceived(listener) 监听 HTTP Response Header 事件
• promise.offHeadersReceived(listener) 取消监听
• promise.onProgressUpdate(listener) 监听下载进度 listener(res) res 说明：

  字段	描述
  progress	下载进度百分比
  totalBytesWritten	已经下载的数据长度，单位 Bytes
  totalBytesExpectedToWrite	预期需要下载的数据总长度，单位 Bytes

• promise.offProgressUpdate(listener) 取消监听

createRequest

createRequest(presetOptions: RequestOptions): MPRequest

• RequestOptions
• MPRequest

创建一个 请求实例, presetOptions 作为预设请求设置，会与请求接口的options 进行合并。

const customRequest = createRequest({
  baseUrl: 'http://example.com/',
  timeout: 60000,
  dataType: 'json',
  header: {
    'content-type': 'application/json'
  }
})

// 发起 post 请求
customRequest.post('/b', { b: 1 })
  .then((response) => {
    console.log(response)
  })

createUpload

createUpload(presetOptions: UploadRequestOptions): Upload

返回一个 新的 upload 函数，presetOptions 作为预设请求设置，会与 upload 函数中的 options 进行合并。

const customUpload = createUpload({
  baseUrl: 'http://example.com/',
  timeout: 60000
})

// 上传文件
customUpload('/upload', { filePath: '/local/1.txt', name: '1.txt' })
  .then((response) => {
    console.log(response)
  })

createDownload

createDownload(presetOptions: DownloadRequestOptions): Download

返回一个新的 download 函数，presetOptions 作为预设请求设置，会与 download 函数中的 options 进行合并。

const customDownload = createDownload({
  baseUrl: 'http://example.com/',
  timeout: 60000
})
// 下载文件
customDownload('/download', 'local/1.txt')
  .then((response) => {
    console.log(response)
  })

Type

RequestOptions

字段	类型	描述
baseUrl	string	请求路径公共前缀
timeout	number	超时时间，单位为毫秒。默认值为 60000
header	object	设置请求的 header
dataType	string	返回的数据格式
responseType	string	响应的数据类型
header	object	设置请求的 header
enableHttp2	boolean	开启 http2
enableQuic	boolean	开启 quic
enableCache	boolean	开启 cache
enableHttpDNS	boolean	是否开启 HttpDNS 服务。
httpDNSServiceId	string	HttpDNS 服务商 Id。
enableChunked	boolean	开启 transfer-encoding
forceCellularNetwork	boolean	wifi下使用移动网络发送请求

DownloadRequestOptions

字段	类型	描述
baseUrl	string	请求路径公共前缀
timeout	number	超时时间，单位为毫秒。
header	object	设置请求的 header

UploadRequestOptions

字段	类型	描述
baseUrl	string	请求路径公共前缀
timeout	number	超时时间，单位为毫秒。
header	object	设置请求的 header
filePath	string	要上传文件资源的路径 (本地路径)
name	string	文件对应的 key，开发者在服务端可以通过这个 key 获取文件的二进制内容

MPRequest

see request