使用手册

mpvue 继承自 Vue.js,其技术规范和语法特点与 Vue.js 保持一致。

本文档适用于有一定 Vue.js 使用经验的开发者。我们默认你已经掌握 Vue.js 技术体系,如果你是新手,你可能需要先熟悉 Vue.js 官方文档

五分钟教程

通过 Vue.js 命令行工具 vue-cli,你只需在终端窗口输入几条简单命令,即可快速创建和启动一个带热重载、保存时静态检查、内置代码构建功能的小程序项目:

# 全局安装 vue-cli
$ npm install --global vue-cli

# 创建一个基于 mpvue-quickstart 模板的新项目
$ vue init mpvue/mpvue-quickstart my-project

# 安装依赖
$ cd my-project
$ npm install
# 启动构建
$ npm run dev

接下来,你只需要启动微信开发者工具,引入项目即可预览到你的第一个 mpvue 小程序。

框架原理

Vue 实例

支持 官方文档:Vue 实例,同时我们做了一些修改,来适应小程序的独特加载逻辑。

实例生命周期

同 vue,不同的是我们会在小程序 onReady 后,再去触发 vue mounted 生命周期,详细的 vue 生命周期文档请看生命周期钩子

除了 Vue 本身的生命周期外,mpvue 还兼容了小程序生命周期,这部分生命周期钩子的来源于微信小程序的 Page, 除特殊情况外,不建议使用小程序的生命周期钩子。

app 部分:

page 部分:

用法示例:

new Vue({
  data: {
    a: 1
  },
  created () {
    // `this` 指向 vm 实例
    console.log('a is: ' + this.a)
  },
  onShow () {
    // `this` 指向 vm 实例
    console.log('a is: ' + this.a, '小程序触发的 onshow')
  }
})
// => "a is: 1"

注意点:

  1. 不要在选项属性或回调上使用箭头函数,比如 created: () => console.log(this.a)vm.$watch('a', newValue => this.myMethod())。因为箭头函数是和父级上下文绑定在一起的,this 不会是如你做预期的 Vue 实例,且 this.athis.myMethod 也会是未定义的。

  2. 微信小程序的页面的 query 参数是通过 onLoad 获取的,mpvue 对此进行了优化,直接通过 this.$root.$mp.query 获取相应的参数数据,其调用需要在 onLoad 生命周期触发之后使用,比如 onShow 等,具体生命周期调用顺序,见下图。

生命周期图示

你不需要立马弄明白所有的东西,不过随着你的不断学习和使用,它的参考价值会越来越高。

生命周期的调用关系和顺序图。

模板语法

几乎全支持 官方文档:模板语法,下面讲下不支持的情况。

不支持 纯-HTML

小程序里所有的 BOM/DOM 都不能用,也就是说 v-html 指令不能用。

不支持部分复杂的 JavaScript 渲染表达式

我们会把 template 中的 {{}} 双花括号的部分,直接编码到 wxml 文件中,由于微信小程序的能力限制(数据绑定),所以无法支持复杂的 JavaScript 表达式。

目前可以使用的有 + - * % ?: ! == === > < [] .,剩下的还待完善。

<!-- 这种就不支持,建议写 computed -->
<p>{{ message.split('').reverse().join('') }}</p>

<!-- 但写在 @event 里面的表达式是都支持的,因为这部分的计算放在了 vdom 里面 -->
<ul>
    <li v-for="item in list">
        <div @click="clickHandle(item, index, $event)">{{ item.value }}</p>
    </li>
</ul>

不支持过滤器

渲染部分会转成 wxml ,wxml 不支持过滤器,所以这部分功能不支持。

计算属性

支持 官方文档:计算属性

不支持函数

不支持在 template 内使用 methods 中的函数。

Class 与 Style 绑定

为节约性能,我们将 Class 与 Style 的表达式通过 compiler 硬编码到 wxml 中,支持语法和转换效果如下:

class 支持的语法:

<p :class="{ active: isActive }">111</p>
<p class="static" v-bind:class="{ active: isActive, 'text-danger': hasError }">222</p>
<p class="static" :class="[activeClass, errorClass]">333</p>
<p class="static" v-bind:class="[isActive ? activeClass : '', errorClass]">444</p>
<p class="static" v-bind:class="[{ active: isActive }, errorClass]">555</p>

将分别被转换成:

<view class="_p {{[isActive ? 'active' : '']}}">111</view>
<view class="_p static {{[isActive ? 'active' : '', hasError ? 'text-danger' : '']}}">222</view>
<view class="_p static {{[activeClass, errorClass]}}">333</view>
<view class="_p static {{[isActive ? activeClass : '', errorClass]}}">444</view>
<view class="_p static {{[[isActive ? 'active' : ''], errorClass]}}">555</view>

style 支持的语法:

<p v-bind:style="{ color: activeColor, fontSize: fontSize + 'px' }">666</p>
<p v-bind:style="[{ color: activeColor, fontSize: fontSize + 'px' }]">777</p>

将分别被转换成:

<view class="_p" style=" {{'color:' + activeColor + ';' + 'font-size:' + fontSize + 'px' + ';'}}">666</view>
<view class="_p" style=" {{'color:' + activeColor + ';' + 'font-size:' + fontSize + 'px' + ';'}}">777</view>

不支持 官方文档:Class 与 Style 绑定 中的 classObjectstyleObject 语法。

最佳实践见上文支持的语法,从性能考虑,建议不要过度依赖此。

此外还可以用 computed 方法生成 class 或者 style 字符串,插入到页面中,举例说明:

<template>
    <!-- 支持 -->
    <div class="container" :class="computedClassStr"></div>
    <div class="container" :class="{active: isActive}"></div>

    <!-- 不支持 -->
    <div class="container" :class="computedClassObject"></div>
</template>
<script>
    export default {
        data () {
            return {
                isActive: true
            }
        },
        computed: {
            computedClassStr () {
                return this.isActive ? 'active' : ''
            },
            computedClassObject () {
                return { active: this.isActive }
            }
        }
    }
</script>

用在组件上

暂不支持在组件上使用 Class 与 Style 绑定

条件渲染

全支持 官方文档:条件渲染

列表渲染

全支持 官方文档:列表渲染

只是需要注意一点,嵌套列表渲染,必须指定不同的索引!

示例:

<!-- 在这种嵌套循环的时候, index 和 itemIndex 这种索引是必须指定,且别名不能相同,正确的写法如下 -->
<template>
    <ul v-for="(card, index) in list">
        <li v-for="(item, itemIndex) in card">
            {{item.value}}
        </li>
    </ul>
</template>

事件处理器

几乎全支持啦 官方文档:事件处理器

我们引入了 Vue.js 的虚拟 DOM ,在前文模版中绑定的事件会被挂在到 vnode 上,同时我们的 compiler 在 wxml 上绑定了小程序的事件,并做了相应的映射,所以你在真实点击的时候通过 runtime 中 handleProxy 通过事件类型分发到 vnode 的事件上,同 Vue 在 WEB 的机制一样,所以可以做到无损支持。同时还顺便支持了自定义事件和 $emit 机制。

// 事件映射表,左侧为 WEB 事件,右侧为 小程序 对应事件
{
    click: 'tap',
    touchstart: 'touchstart',
    touchmove: 'touchmove',
    touchcancel: 'touchcancel',
    touchend: 'touchend',
    tap: 'tap',
    longtap: 'longtap',
    input: 'input',
    change: 'change',
    submit: 'submit',
    blur: 'blur',
    focus: 'focus',
    reset: 'reset',
    confirm: 'confirm',
    columnchange: 'columnchange',
    linechange: 'linechange',
    error: 'error',
    scrolltoupper: 'scrolltoupper',
    scrolltolower: 'scrolltolower',
    scroll: 'scroll'
}

inputtextareachange 事件会被转为 blur 事件。

踩坑注意:

表单控件绑定

几乎全支持 官方文档:表单控件绑定,不支持的还没测出来,之所以说几乎,是因为 WEB 表单这么复杂,谁特么知道会出什么奇怪的特性。

建议开发过程中直接使用 微信小程序:表单组件 。用法示例:

select 组件用 picker 组件进行代替

<template>
  <div>
    <picker @change="bindPickerChange" :value="index" :range="array">
      <view class="picker">
        当前选择:{{array[index]}}
      </view>
    </picker>
  </div>
</template>

<script>
export default {
  data () {
    return {
      index: 0,
      array: ['A', 'B', 'C']
    }
  },
  methods: {
    bindPickerChange (e) {
      console.log(e)
    }
  }
}

</script>

表单元素 radio 用 radio-group 组件进行代替

<template>
  <div>
    <radio-group class="radio-group" @change="radioChange">
      <label class="radio" v-for="(item, index) in items" :key="item.name">
        <radio :value="item.name" :checked="item.checked"/> {{item.value}}
      </label>
    </radio-group>
  </div>
</template>

<script>
export default {
  data () {
    return {
      items: [
        {name: 'USA', value: '美国'},
        {name: 'CHN', value: '中国', checked: 'true'},
        {name: 'BRA', value: '巴西'},
        {name: 'JPN', value: '日本'},
        {name: 'ENG', value: '英国'},
        {name: 'TUR', value: '法国'}
      ]
    }
  },
  methods: {
    radioChange (e) {
      console.log('radio发生change事件,携带value值为:', e.target.value)
    }
  }
}

</script>

组件

Vue 组件

组件是整个 Vue.js 中最复杂的部分,当然要支持 官方文档:组件

有且只能使用单文件组件(.vue 组件)的形式进行支持。其他的诸如:动态组件,自定义 render,和<script type="text/x-template"> 字符串模版等都不支持。原因很简单,因为我们要预编译出 wxml。

如果未来小程序支持了动态增删改查 wxml 节点信息,那我们就能做到全支持。

详细的不支持列表:

小程序组件

mpvue 可以支持小程序的原生组件,比如: picker,map 等,需要注意的是原生组件上的事件绑定,需要以 vue 的事件绑定语法来绑定,如 bindchange="eventName" 事件,需要写成 @change="eventName"

示例代码:

<picker mode="date" :value="date" start="2015-09-01" end="2017-09-01" @change="bindDateChange">
    <view class="picker">
      当前选择: {{date}}
    </view>
</picker>

TypeScript支持

目前mpvue-loader是可以支持TypeScript选项的,配置方法在此。具体Demo可以见mpvue-ts-demo

最佳实践

1. 精简 data 数据

冗余数据不要挂在 data 里,所有在 data/props/computed 中的数据,每次变更都会从微信小程序的 JSCore 进程,通过 setData 序列化成字符串后发送到 JSRender 进程。所以,如果你的数据量巨大的时候,会导致页面非常卡顿。

2. 优化长列表性能

一般情况下这种页面会有大量的数据,除了遵从上面的建议外还有额外的建议。

注:我们对其进行了专门优化,最佳实践时和原生小程序代码的性能相差无几。

3. 合理使用双向绑定 mpvue 建议使用 v-model.lazy 绑定方式以优化性能,此外 v-model 在老基础库下输入框输入时可能存在光标重设的问题。

4. 谨慎选择直接使用小程序的 API 如果你有小程序和H5复用代码的需要,业务代码需要保持对 WEB Vue.js 的兼容性。此时我们不建议在代码中直接调用小程序API,更好的选择是通过桥接适配层屏蔽两端差异。

常见问题

1. 如何获取小程序在 page onLoad 时候传递的 options

在所有 页面 的组件内可以通过 this.$root.$mp.query 进行获取。

2. 如何获取小程序在 app onLaunch/onShow 时候传递的 options

在所有的组件内可以通过 this.$root.$mp.appOptions 进行获取。

3. 如何捕获 app 的 onError

由于 onError 并不是完整意义的生命周期,所以只提供一个捕获错误的方法,在 app 的根组件上添加名为 onError 的回调函数即可。如下:

export default {
   // 只有 app 才会有 onLaunch 的生命周期
   onLaunch () {
       // ...
   },

   // 捕获 app error
   onError (err) {
       console.log(err)
   }
}

mpvue 框架使用场景汇总

mpvue 作为一个前端开发框架,提供了一整套解决方案。但开发者面临的实际情况可能更加复杂,我们整理了 mpvue 可能的使用场景,在这些场景下,我们为你提供了一些建议。

首先,mpvue 小程序框架包含如下内容:

开发者可能会面对的四种典型场景

针对上述不同场景,mpvue 框架需要提供的方案和建议如下