周边拓展

mpx-fetch

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

fetch(config)

正常的promisify风格的请求方法

{Object} config
config 可指定以下属性：
- url
  string
  设置请求url
- method
  string
  设置请求方式，默认为GET
- data
  object
  设置请求参数
- params
  object
  设置请求参数，参数会以 Query String 的形式进行传递
- header
  object
  设置请求的 header，header 中不能设置 Referer。 content-type 默认为 application/json
- timeout
  number
  单位为毫秒。若不传，默认读取app.json文件中__networkTimeout属性。对于超时的处理可在 catch 方法中进行
- emulateJSON
  boolean
  设置为 true 时，等价于 header =
- usePre
  boolean
  预请求开关，若设置为 true，则两次请求间隔在有效期内且请求参数和请求方式对比一致的情况下，会返回上一次的请求结果
- cacheInvalidationTime
  number
  预请求缓存有效时长，单位 ms，默认为 5000ms。当两次请求时间间隔超过设置时长后再发起二次请求时，上一次的请求缓存会失效然后重新发起请求
- ignorePreParamKeys
  array | string
  在判断缓存请求是否可用对比前后两次请求参数时，默认对比的是 options 传入的所有参数（包括 params 和 data ）。但在具体业务场景下某些参数不一致时的缓存结果依旧可使用（比如参数中带有时间戳），所以提供 ignorePreParamKeys 来设置对比参数过程中可忽略的参数的 key，支持字符串数组和字符串（字符串传多个 key 时使用英文逗号分隔）类型。配置后在进行参数对比时，不会对比在 ignorePreParamKeys 设置的参数。

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'
    },
    header: {
      'content-type': 'application/x-www-form-urlencoded',
    },
    emulateJSON: true,
    usePre: true,
    cacheInvalidationTime: 3000,
    ignorePreParamKeys: ['timestamp']
}).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实例进行独立使用

interface FetchOptions{
    useQueue: boolean // 是否开启队列功能
    proxy: boolean // 是否开启代理功能
}

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，也可参考下面的简单示例。
    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()

useFetch

useFetch(options?: FetchOptions):xfetch

在组合式 API 中使用，用来获取 @mpxjs/fetch 插件的 xfetch 实例，等用于 mpx.xfetch。关于 xfetch 实例的详细介绍，请点击查看

此外该方法可选择传入 options 参数，若传入参数，则会创建一个新的 XFetch 实例返回，若不传入参数，则默认将全局 xfetch 实例返回。

// app.mpx
import mpx from '@mpxjs/core'
import mpxFetch from '@mpxjs/fetch'
mpx.use(mpxFetch)

// script-setup.mpx
import { useFetch } from '@mpxjs/fetch'
useFetch().fetch({
  url: 'http://xxx.com',
  method: 'POST',
  params: {
    age: 10
  },
  data: {
    name: 'test'
  },
  emulateJSON: true,
  usePre: true,
  cacheInvalidationTime: 3000,
  ignorePreParamKeys: ['timestamp']
}).then(res => {
  console.log(res.data)
})

注意： options 参数同 XFetch 章节。

size-report

Mpx框架项目包体积可以进行分组、分包、页面、冗余Npm包等维度的分析和对比，详细请见

插件配置项

server
object
本地可视化服务相关配置
filename
string
构建生成的包体积详细输出文件地址
threshold
object
配置项目总体积和分包体积阈值，包含两个字段，size 为项目总体积阈值，packages 为分包体积阈值
html
```
{
   size: '16MB', // 项目总包体积限额 16M
   packages: '2MB' // 项目每个分包体积限额 2M
}
```
groups
Array<object>
配置体积计算分组，以输入分组为维度对体积进行分析，当没有该配置时结果中将不会包含分组体积信息
- name
  string
  分组名称
- threshold
  string | object
  分组相关体积阈值，若不配置则该分组不校验体积阈值，同时也支持对分组中占各分包体积阈值
  html
```
// 分组体积限额 500KB
threshold: '500KB'
// 或者如下方，分组体积限额500KB，分组占主包体积限额160KB
threshold: {
  size: '500KB',
  packages: {
    main: '160KB'
  }
}
```
- entryRules
  object
  配置分组 entry 匹配规则，小程序中所有的页面和组件都可被视为 entry
  - include: 包含符合条件的入口文件，默认为空数组，规则数组中支持函数、正则、字符串
  - exclude: 剔除符合条件的入口文件，默认为空数组，规则数组中支持函数、正则、字符串
  html
```
include: [/@someGroup\/some-npm-package/],
exclude: [/@someGroup\/some-two-pack/]
```
- noEntryRules
  object
  配置计算分组中纯 js 入口引入的体积（不包含组件和页面）
  - include: 包含符合条件的 js 文件，默认为空数组，规则数组中支持函数、正则、字符串
  - exclude: 剔除符合条件的 js 文件，默认为空数组，规则数组中支持函数、正则、字符串
  html
```
include: [/@someGroup\/some-npm-package/],
exclude: [/@someGroup\/some-two-pack/]
```
reportPages
boolean
是否收集页面维度体积详情，默认 false
reportAssets
boolean
是否收集资源维度体积详情，默认 false
reportRedundance
boolean
是否收集冗余资源，默认 false
showEntrysPackages
Array<string>
展示某些分包资源的引用来源信息，例如 ['main'] 为查看主包资源的引用来源信息，默认为 []

配置使用示例：

html

{
  // 本地可视化服务相关配置
  server: {
    enable: true, // 是否启动本地服务，非必填，默认 true
    autoOpenBrowser: true, // 是否自动打开可视化平台页面，非必填，默认 true
    port: 0, // 本地服务端口，非必填，默认 0(随机端口)
    host: '127.0.0.1', // 本地服务host，非必填
  },
  // 体积报告生成后输出的文件地址名，路径相对为 dist/wx 或者 dist/ali
  filename: '../report.json',
  // 配置阈值，此处代表总包体积阈值为 16MB，分包体积阈值为 2MB，超出将会触发编译报错提醒，该报错不阻断构建
  threshold: {
    size: '16MB',
    packages: '2MB'
  },
  // 配置体积计算分组，以输入分组为维度对体积进行分析，当没有该配置时结果中将不会包含分组体积信息
  groups: [
    {
      // 分组名称
      name: 'vant',
      // 配置分组 entry 匹配规则，小程序中所有的页面和组件都可被视为 entry，如下所示的分组配置将计算项目中引入的 vant 组件带来的体积占用
      entryRules: {
        include: '@vant/weapp'
      }
    },
    {
      name: 'pageGroup',
      // 每个分组中可分别配置阈值，如果不配置则表示
      threshold: '500KB',
      entryRules: {
        include: ['src/pages/index', 'src/pages/user']
      }
    },
    {
      name: 'someSdk',
      entryRules: {
        include: ['@somegroup/someSdk/index', '@somegroup/someSdk2/index']
      },
      // 有的时候你可能希望计算纯 js 入口引入的体积（不包含组件和页面），这种情况下需要使用 noEntryRules
      noEntryRules: {
        include: 'src/lib/sdk.js'
      }
    }
  ],
  // 是否收集页面维度体积详情，默认 false
  reportPages: true,
  // 是否收集资源维度体积详情，默认 false
  reportAssets: true,
  // 是否收集冗余资源，默认 false
  reportRedundance: true,
  // 展示某些分包资源的引用来源信息，默认为 []
  showEntrysPackages: ['main']
}

i18n

useI18n

组合式 API 中使用，用来获取 i18n 实例。

参数选项

locale

Locale

设置语言环境

注意： 只传 locale，不传 messages 属性时不起作用

fallbackLocale

Locale

预设的语言环境，找不到语言环境时进行回退。

messages

LocaleMessages

本地化的语言环境信息。

返回实例属性和方法

locale

WritableComputedRef<Locale>

可响应性的 ref 对象，表示当前 i18n 实例所使用的 locale。

修改 ref 值会对局部或者全局语言集的 locale 进行更改，并触发翻译方法重新执行。

fallbackRoot

boolean

本地化失败时是否回归到全局作用域。

getLocaleMessage( locale )

function getLocaleMessage (locale: string): LocaleMessageObject

获取语言环境的 locale 信息。

setLocaleMessage( locale, message )

function setLocaleMessage(locale: Locale, messages: LocaleMessageObject): void

设置语言环境的 locale 信息。

mergeLocaleMessage( locale, message )

function mergeLocaleMessage(locale: Locale, messages: LocaleMessageObject): void

将语言环境信息 locale 合并到已注册的语言环境信息中。

messages

readonly messages: ComputedRef<{
   [K in keyof Messages]: Messages[K];
}>;

只读

局部或者全局的语言环境信息。

isGlobal

boolean

是否是全局 i18n 实例。

t

function t(key: string, choice?: number, values: Array | Object): TranslateResult

文案翻译函数

根据传入的 key 以及当前 locale 环境获取对应文案，文案来源是全局作用域还是本地作用域取决于 useI18n 执行时是否传入对应的 messages、locale 等值。

choice 参数可选 ，当传入 choice 时，t 函数的表现为使用复数进行翻译，和老版本中的 tc 函数表现一致。

html

<template>
  <view>{{t('car', 1)}}</view>
  <view>{{t('car', 2)}}</view>

  <view>{{t('apple', 0)}}</view>
  <view>{{t('apple', 1)}}</view>
  <view>{{t('apple', 10, {count: 10})}}</view>
</template>

<script>
  // 语言环境信息如下：
  const messages = {
    en: {
      car: 'car | cars',
      apple: 'no apples | one apple | {count} apples'
    }
  }
</script>

输入如下：

html

<view>car</view>
<view>cars</view>

<view>no apples</view>
<view>one apple</view>
<view>10 apples</view>

关于复数的更多信息可以点击查看

values 参数可选 ，如果需要对文案信息即逆行格式化处理，则需要传入 values。

html

<template>
  // 模版输出 hello world
  <view>{{t('message.hello', { msg: 'hello'})}}</view>
</template>
<script>
  import {createComponent, useI18n} from "@mpxjs/core"

  const messages = {
    en: {
      message: {
        hello: '{msg} world'
      }
    }
  }

  createComponent({
    setup(){
        const { t } = useI18n({
          messages: {
              'en-US': en
          }
        })
      return {t}
    }
  })

</script>

te

function te(key: string): boolean

检查 key 是否存在。

周边拓展 ​

mpx-fetch ​

fetch(config) ​

CancelToken ​

XFetch ​

interceptors ​

proxy 代理 ​

setProxy ​

prependProxy ​

appendProxy ​

getProxy ​

clearProxy ​

useFetch ​

size-report ​

插件配置项 ​

i18n ​

useI18n ​

locale ​

fallbackLocale ​

messages ​

locale ​

fallbackRoot ​

getLocaleMessage( locale ) ​

setLocaleMessage( locale, message ) ​

mergeLocaleMessage( locale, message ) ​

messages ​

isGlobal ​

t ​

te ​

周边拓展

mpx-fetch

fetch(config)

CancelToken

XFetch

interceptors

proxy 代理

setProxy

prependProxy

appendProxy

getProxy

clearProxy

useFetch

size-report

插件配置项

i18n

useI18n

locale

fallbackLocale

messages

locale

fallbackRoot

getLocaleMessage( locale )

setLocaleMessage( locale, message )

mergeLocaleMessage( locale, message )

messages

isGlobal

t

te