# 周边拓展

# 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

        详细:同时匹配请求中的 paramsquery

      • data

        类型:object

        详细:匹配请求中的 data

      • header

        类型:object

        详细:匹配请求中的 header

      • method

        类型:Method | Method[]

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

      • custom

        类型:function

        详细:自定义匹配规则,参数会注入原始请求配置,结果需返回 truefalse

        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