周边拓展

mpx-fetch

mpx-fetch提供了一个实例xfetch ，该实例包含以下api

fetch(config)

正常的promisify风格的请求方法

• 参数：

  • {Object} config

    config 可指定以下属性：

    • url

      类型：string

      设置请求url

    • method

      类型：string

      设置请求方式，默认为GET

    • data

      类型：Object

      设置请求参数

    • params

      类型：Object

      设置请求参数，参数会以 Query String 的形式进行传递

    • timeout

      类型：Number

      单位为毫秒。若不传，默认读取app.json文件中__networkTimeout属性。 对于超时的处理可在 catch 方法中进行

    • emulateJSON

      类型：Boolean

      设置为 true 时，等价于 header = {'content-type': 'application/x-www-form-urlencoded'}

• 示例：

import mpx from '@mpxjs/core'
import mpxFetch from '@mpxjs/fetch'
mpx.use(mpxFetch)
// 第一种访问形式
mpx.xfetch.fetch({
	url: 'http://xxx.com',
	method: 'POST',
	params: {
		age: 10
	},
	data: {
		name: 'test'
	},
	emulateJSON: true 
}).then(res => {
	console.log(res.data)
})

mpx.createApp({
	onLaunch() {
		// 第二种访问形式
		this.$xfetch.fetch({url: 'http://test.com'})
	}
})

CancelToken

命名导出，用于创建一个取消请求的凭证。

• 示例:

import { CancelToken } from '@mpxjs/fetch'
const cancelToken = new CancelToken()
mpx.xfetch.fetch({
	url: 'http://xxx.com',
	data: {
		name: 'test'
	},
	cancelToken: cancelToken.token
})
cancelToken.exec('手动取消请求') // 执行后请求中断，返回abort fail

XFetch

命名导出，用于创建一个新的mpx-fetch实例进行独立使用

• 示例:

import { XFetch } from '@mpxjs/fetch'
const newFetch = new XFetch(options) // 生成新的mpx-fetch实例

interceptors

实例属性，用于添加拦截器，包含两个属性，request & response

• 示例:

mpx.xfetch.interceptors.request.use(function(config) {
    console.log(config)
    // 也可以返回promise
    return config
})
mpx.xfetch.interceptors.response.use(function(res) {
    console.log(res)
    // 也可以返回promise
    return res
})

proxy 代理

setProxy

配置代理项，可以传入一个数组或者一个对象，请求会按设置的规则进行代理

• 参数：

  类型： {Array | Object}

  • test

    类型：object

    • url

      类型：string

      详细：全路径匹配，规则可以参考path-to-regexp (opens new window)，也可参考下面的简单示例。

      WARNING

      如果设置了此项，则 protocol、host、port、path 规则不再生效。此项支持 path-to-regexp 匹配，protocol、host、port、path 为全等匹配。

    • protocol

      类型：string

      详细：待匹配的协议头

    • host

      类型：string

      详细：不包含端口的 host

    • port

      类型：string

      详细：待匹配的端口

    • path

      类型：string

      详细：待匹配的路径

    • params

      类型：object

      详细：同时匹配请求中的 params 和 query

    • data

      类型：object

      详细：匹配请求中的 data

    • header

      类型：object

      详细：匹配请求中的 header

    • method

      类型：Method | Method[]

      详细：匹配请求方法，不区分大小写，可以传一个方法，也可以传一个方法数组

    • custom

      类型：function

      详细：自定义匹配规则，参数会注入原始请求配置，结果需返回 true 或 false

      WARNING

      如果设置了此项，匹配结果以此项为准，以上规则均不再生效。

  • proxy

    类型：object

    • url

      类型：string

      详细：代理的 url

    • protocol

      类型：string

      详细：修改原请求的协议头

    • host

      类型：string

      详细：代理的 host，不包含端口号

    • port

      类型：string

      详细：修改端口号

    • path

      类型：string

      详细：修改原请求路径

    • params

      类型：object

      详细：合并原请求的 params

    • data

      类型：object

      详细：合并原请求的 data

    • header

      类型：object

      详细：合并原请求的 header

    • method

      类型：Method

      详细：替换原请求的方法

    • custom

      类型：function

      详细：自定义代理规则，会注入两个参数，第一个是上一个匹配规则处理后的请求配置，第二个是 match 的参数对象，结果需返回要修改的请求配置对象。

      WARNING

      如果设置了此项，最终代理配置将以此项为准，其他配置规则均不再生效。

  • waterfall

    类型：boolean

    详细：默认为 false，为 false 时，命中当前规则处理完就直接返回；为 true 时，命中当前匹配规则处理完成后将结果传递给下面命中匹配规则继续处理。

• 示例：

mpx.xfetch.setProxy([{
    test: { // 此项匹配之后，会按下面 proxy 配置的修改请求配置
		header: {
            'content-type': 'application/x-www-form-urlencoded'
        },
        method: 'get',
        params: {
            a: 1
        },
        data: {
            test1: 'abc'
        }
	},
	proxy: {
		header: {
			env: 'env test'
		},
		params: {
			b: 2
        },
        data: {
            test2: 'cba'
        }
	},
	waterfall: true // 为 true 时会将此次修改后的请求配置继续传递给下面的规则处理
}, {
    test: {// 可以分别单独匹配 protocol、host、port、path；代理规则同样
        protocol: 'http:',
		host: 'mock.didi.com',
		port: '',
		path: '/mock/test'
    },
    proxy: {
        host: 'test.didi.com',
        port: 8888
    },
    waterfall: true
}, {
    test: { // 自定义匹配规则
        custom (config) { // config 为原始的请求配置
            // 自定义匹配逻辑
			if (xxx) {
				return true
			}
			return false
		}
    },
    proxy: { // 自定义代理配置
        custom (config, params) {
			// config 为上面匹配后修改过的请求配置
            // params 为 match 后的参数对象
            // 返回需要修改的请求配置对象
			return {
                params: {
                    c: 3
                },
				data: {
					test3: 'aaa'
				}
			}
		}
    },
    waterfall: true
}, {
    test: {
        // : 可以匹配目标项，并将 match 结果返回到代理 custom 函数中
        // :和?都属于保留符号，若不想做匹配时需用 '\\' 转义
        // (.*)为全匹配
        url: ':protocol\\://mock.didi.com/mock/:id/oneapi/router/forum/api/v1/(.*)',
        method: ['get', 'post']
    },
    proxy: {
        url: 'https://127.0.0.1:8080/go/into/$id/api/v2/abcd' // '$'项在代理生效后会替换匹配规则中的':'项
    },
    waterfall: false // false 时不会继续匹配后面的规则
}])

prependProxy

向前追加代理规则

• 示例：

mpx.xfetch.prependProxy({
	test: {},
	proxy: {},
	waterfall: true
})

appendProxy

向后追加代理规则

• 示例：

mpx.xfetch.appendProxy({
	test: {},
	proxy: {},
	waterfall: true
})

getProxy

查看已有的代理配置

• 示例：

console.log(mpx.xfetch.getProxy())

clearProxy

解除所有的代理配置

• 示例：

mpx.xfetch.clearProxy()

api-proxy

Mpx目前已经支持的API转换列表，供参考

方法/平台	wx	ali	web
getSystemInfo	✅	✅	✅
getSystemInfoSync	✅	✅	✅
nextTick	✅	✅	✅
showToast	✅	✅	✅
hideToast	✅	✅	✅
showModal	✅	✅	✅
showLoading	✅	✅	✅
hideLoading	✅	✅	✅
showActionSheet	✅	✅	✅
showNavigationBarLoading	✅	✅	❌
hideNavigationBarLoading	✅	✅	❌
setNavigationBarTitle	✅	✅	✅
setNavigationBarColor	✅	✅	✅
request	✅	✅	✅
downloadFile	✅	✅	❌
uploadFile	✅	✅	❌
setStorageSync	✅	✅	✅
removeStorageSync	✅	✅	✅
getStorageSync	✅	✅	✅
saveImageToPhotosAlbum	✅	✅	❌
previewImage	✅	✅	❌
compressImage	✅	✅	❌
chooseImage	✅	✅	❌
getLocation	✅	✅	❌
saveFile	✅	✅	❌
removeSavedFile	✅	✅	❌
getSavedFileList	✅	✅	❌
getSavedFileInfo	✅	✅	❌
addPhoneContact	✅	✅	❌
setClipboardData	✅	✅	❌
getClipboardData	✅	✅	❌
setScreenBrightness	✅	✅	❌
getScreenBrightness	✅	✅	❌
makePhoneCall	✅	✅	❌
stopAccelerometer	✅	✅	❌
startAccelerometer	✅	✅	❌
stopCompass	✅	✅	❌
startCompass	✅	✅	❌
stopGyroscope	✅	✅	❌
startGyroscope	✅	✅	❌
scanCode	✅	✅	❌
login	✅	✅	❌
checkSession	✅	✅	❌
getUserInfo	✅	✅	❌
requestPayment	✅	✅	❌
createCanvasContext	✅	✅	❌
canvasToTempFilePath	✅	✅	❌
canvasPutImageData	✅	✅	❌
canvasGetImageData	✅	✅	❌
createSelectorQuery	✅	✅	✅
onWindowResize	✅	✅	✅
offWindowResize	✅	✅	✅
arrayBufferToBase64	❌	❌	✅
base64ToArrayBuffer	❌	❌	✅

webview-bridge

Mpx 支持小程序跨平台后，多个平台的小程序里都提供了 webview 组件，webview 打开的 H5 页面可以通过小程序提供的 API 来与小程序通信以及调用一些小程序的能力，但是各家小程序对于 webview 提供的API是不一样的。

比如微信的 webview 打开的 H5 页面里是通过调用 wx.miniProgram.navigateTo 来跳转到原生小程序页面的，而在支付宝是通过调用 my.navigateTo 来实现跳转的，那么我们开发 H5 时候为了让 H5 能适应各家小程序平台就需要写多份对应逻辑。

为解决这个问题，Mpx 提供了抹平平台差异的bridge库：@mpxjs/webview-bridge。

安装：

npm install @mpxjs/webview-bridge

使用：

import mpx from '@mpxjs/webview-bridge'
mpx.navigateBack()
mpx.env // 输出：wx/qq/ali/baidu/tt
mpx.checkJSApi()

cdn地址引用：

<!-- 开发环境版本，方便调试 -->
<script src="https://dpubstatic.udache.com/static/dpubimg/D2JeLyT0_Y/2.2.43.webviewbridge.js"></script>

<!-- 生产环境版本，压缩了体积 -->
<script src="https://dpubstatic.udache.com/static/dpubimg/PRg145LZ-i/2.2.43.webviewbridge.min.js"></script>


<!-- 同时支持 ES Module 引入的 -->
// index.html
<script type="module" src="https://dpubstatic.udache.com/static/dpubimg/6MQOo-ocI4/2.2.43.webviewbridge.esm.browser.min.js"></script>
// main.js
import mpx from "https://dpubstatic.udache.com/static/dpubimg/6MQOo-ocI4/2.2.43.webviewbridge.esm.browser.min.js"

//ES Module 开发版本地址： https://dpubstatic.udache.com/static/dpubimg/cdhpNhmWmJ/2.2.43.webviewbridge.esm.browser.js

基础方法提供：

方法/平台	wx	qq	ali	baidu	tt
navigateTo	✅	✅	✅	✅	✅
navigateBack	✅	✅	✅	✅	✅
switchTab	✅	✅	✅	✅	✅
reLaunch	✅	✅	✅	✅	✅
redirectTo	✅	✅	✅	✅	✅
getEnv	✅	✅	✅	✅	✅
postMessage	✅	✅	✅	✅	✅
getLoadError	✅	✅	✅	✅	✅
onMessage	❌	❌	✅	❌	❌

扩展方法提供：

方法/平台	wx	qq	ali	baidu	tt
checkJSApi	✅	❌	❌	❌	❌
chooseImage	✅	❌	✅	✅	❌
previewImage	✅	❌	✅	✅	❌
uploadImage	✅	❌	❌	❌	❌
downloadImage	✅	❌	❌	❌	❌
getLocalImgData	✅	❌	❌	❌	❌
startRecord	✅	❌	❌	❌	❌
stopRecord	✅	❌	❌	❌	❌
onVoiceRecordEnd	✅	❌	❌	❌	❌
playVoice	✅	❌	❌	❌	❌
pauseVoice	✅	❌	❌	❌	❌
stopVoice	✅	❌	❌	❌	❌
onVoicePlayEnd	✅	❌	❌	❌	❌
uploadVoice	✅	❌	❌	❌	❌
downloadVoice	✅	❌	❌	❌	❌
translateVoice	✅	❌	❌	❌	❌
getNetworkType	✅	❌	✅	✅	❌
openLocation	✅	❌	✅	✅	❌
getLocation	✅	❌	✅	✅	❌
stopSearchBeacons	✅	❌	❌	❌	❌
onSearchBeacons	✅	❌	❌	❌	❌
scanQRCode	✅	❌	❌	❌	❌
chooseCard	✅	❌	❌	❌	❌
addCard	✅	❌	❌	❌	❌
openCard	✅	❌	❌	❌	❌
alert	✅	✅	❌
showLoading	✅	✅	❌
hideLoading	✅	✅	❌
setStorage	✅	✅	✅
getStorage	✅	✅	✅
removeStorage	✅	✅	✅
clearStorage	✅	✅	✅
getStorageInfo	✅	✅	✅
startShare	✅	✅	❌
tradePay	✅	✅	❌
onMessage	❌	❌	✅	❌	❌

WARNING

这个库仅提供给 H5 使用，请勿在小程序环境引入

mpx-mock

• 请参考 数据 mock