mpvue-loader

我们是在 vue-loader 上做的修改，增加了建构到微信小程序 的若干能力。除此之外与原 vue-loader 文档 保持一致，所以本文档只列下修改的地方。

如果你对 vue-loader 不是很熟悉的话，强烈建议先阅读原文档一遍，下面的内容会默认你已经知道了什么是 vue-loader 和她能做什么。

开始

mpvue-loader 是 vue-loader 的一个扩展延伸版，类似于超集的关系，除了 vue-loader 本身所具备的能力之外，它还会产出微信小程序所需要的文件结构和模块内容。

特性

entry

它会从 webpack 的配置中的 entry 开始，分析依赖模块，并分别打包。在entry 中 app 属性及其内容会被打包为微信小程序所需要的 app.js／app.json／app.wxss，其余的会生成对应的页面page.js/page.json/page.wxml/page.wxss，如示例的 entry 将会生成如下这些文件，文件内容下文慢慢讲来：

  1. // webpack.config.js
  2. {
  3.     // ...
  4.     entry: {
  5.         app: resolve('./src/main.js'),               // app 字段被识别为 app 类型
  6.         index: resolve('./src/pages/index/main.js'),   // 其余字段被识别为 page 类型
  7.         'news/home': resolve('./src/pages/news/home/index.js')
  8.     }
  9. }
  11. // 产出文件的结构
  12. .
  13. ├── app.js
  14. ├── app.json
  15. ├── app.wxss
  16. ├── components
  17. │   ├── card$74bfae61.wxml
  18. │   ├── index$023eef02.wxml
  19. │   └── news$0699930b.wxml
  20. ├── news
  21. │   ├── home.js
  22. │   ├── home.wxml
  23. │   └── home.wxss
  24. ├── pages
  25. │   └── index
  26. │       ├── index.js
  27. │       ├── index.wxml
  28. │       └── index.wxss
  29. └── static
  30.     ├── css
  31.     │   ├── app.wxss
  32.     │   ├── index.wxss
  33.     │   └── news
  34.     │       └── home.wxss
  35.     └── js
  36.         ├── app.js
  37.         ├── index.js
  38.         ├── manifest.js
  39.         ├── news
  40.         │   └── home.js
  41.         └── vendor.js

wxml

每一个 .vue 的组件都会被生成为一个 wxml 规范的 template，然后通过 wxml 规范的 import 语法来达到一个复用，同时组件如果涉及到 props 的 data 数据，我们也会做相应的处理，举个实际的例子：

  1. <template>
  2.     <div class="my-component">
  3.         <h1>{{msg}}</h1>
  4.         <other-component :msg="msg"></other-component>
  5.     </div>
  6. </template>
  7. <script>
  8. import otherComponent from './otherComponent.vue'
  10. export default {
  11.   components: { otherComponent },
  12.   data () {
  13.     return { msg: 'Hello Vue.js!' }
  14.   }
  15. }
  16. </script>

这样一个 vue 的组件的模版部分会生成相应的 wxml

  1. <import src="components/other-component$hash.wxml" />
  2. <template name="component$hash">
  3.     <view class="my-component">
  4.         <view class="_h1">{{msg}}</view>
  5.         <template is="other-component$hash" wx:if="{{ $c[0] }}" data="{{ ...$c[0] }}"></template>
  6.     </view>
  7. </template>

细心的开发者可能已经注意到了 other-component(:msg="msg") 被转化成了 <template is="other-component$hash" data="{{ ...$c[0] }}"></template> 。mpvue 在运行时会从根组件开始把所有的组件实例数据合并成一个树形的数据，然后通过 setData 到 appData,$c 是 $children 的缩写。至于那个 0 则是我们的 compiler 处理过后的一个标记，会为每一个子组件打一个特定的不重复的标记。
树形数据结构如下：

  1. // 这儿数据结构是一个数组，index 是动态的
  2. {
  3.   $child: {
  4.     '0'{
  5.       // ... root data
  6.       $child: {
  7.         '0': {
  8.           // ... data
  9.           msg: 'Hello Vue.js!',
  10.           $child: {
  11.             // ...data
  12.           }
  13.         }
  14.       }
  15.     }
  16.   }
  17. }

wxss

这个部分的处理同 web 的处理差异不大，唯一不同在于通过配置生成 .css 为 .wxss ，其中的对于 css 的若干处理，在 postcss-mpvue-wxss 和 px2rpx-loader 这两部分的文档中又详细的介绍。

app.json／page.json

1.1.1 以上

推荐和小程序一样，将 app.json／page.json 放到页面入口处，使用 copy-webpack-plugin copy 到对应的生成位置。

1.1.1 以下

这部分内容来源于 app 和 page 的 entry 文件，通常习惯是 main.js，你需要在你的入口文件中 export default { config: {} }，这才能被我们的 loader 识别为这是一个配置，需要写成 json 文件。

  1. import Vue from 'vue';
  2. import App from './app';
  4. const vueApp = new Vue(App);
  5. vueApp.$mount();
  7. // 这个是我们约定的额外的配置
  8. export default {
  9.     // 这个字段下的数据会被填充到 app.json ／ page.json
  10.     config: {
  11.         pages: ['static/calendar/calendar', '^pages/list/list'], // Will be filled in webpack
  12.         window: {
  13.             backgroundTextStyle: 'light',
  14.             navigationBarBackgroundColor: '#455A73',
  15.             navigationBarTitleText: '美团汽车票',
  16.             navigationBarTextStyle: '#fff'
  17.         }
  18.     }
  19. };

同时，这个时候，我们会根据 entry 的页面数据，自动填充到 app.json 中的 pages 字段。
pages 字段也是可以自定义的，约定带有 ^ 符号开头的页面，会放到数组的最前面。

style scoped

在 vue-loader 中对 style scoped 的处理方式是给每个样式加一个 attr 来标记 module-id，然后在 css 中也给每条 rule 后添加 [module-id]，最终可以形成一个 css 的“作用域空间”。

在微信小程序中目前是不支持 attr 选择器的，所以我们做了一点改动，把 attr 上的 [module-id] 直接写到了 class 里，如下：

  1. <!-- .vue -->
  2. <template>
  3.     <div class="container">
  4.         // ...
  5.     </div>
  6. </template>
  7. <style scoped>
  8.     .container {
  9.         color: red;
  10.     }
  11. </style>
  13. <!-- vue-loader -->
  14. <template>
  15.     <div class="container" data-v-23e58823>
  16.         // ...
  17.     </div>
  18. </template>
  19. <style scoped>
  20.     .container[data-v-23e58823] {
  21.         color: red;
  22.     }
  23. </style>
  25. <!-- mpvue-loader -->
  26. <template>
  27.     <div class="container data-v-23e58823">
  28.         // ...
  29.     </div>
  30. </template>
  31. <style scoped>
  32.     .container.data-v-23e58823 {
  33.         color: red;
  34.     }
  35. </style>

配置

和 vue-loader 用法一致，讲讲额外注意的地方。

checkMPEntry

在 项目建构 文档的这个部分，有讲到需要给所有 js 后缀文件增加 mpvue-loader ，并且需要加 options，通过这个配置，我们的 loader 才能知道 entry 进来的 js 和 vue 的类型是 app 还是 page，从而做了一些页面类型的区分。

TypeScript支持

mpvue-loader目前支持用TypeScript来写，功能还在完善中(WIP)。目前实现了用<script lang="ts" src="./xx.ts"></script>这种方式的自动识别，并且需要搭配vue-property-decorator来使用。

配置

添加对应的loader

  1. // webpack.conf.js
  2. module.exports = {
  3.   //...
  4.   module: {
  5.     rules: [
  6.       {
  7.         test: /\.vue$/,
  8.         loader: 'mpvue-loader',
  9.         options: {
  10.           //...
  11.           ts: [ //添加对应vue的loader
  12.             'babel-loader',
  13.             {
  14.               // loader: 'ts-loader',
  15.               loader: 'awesome-typescript-loader',
  16.               options: {
  17.                 // errorsAsWarnings: true,
  18.                 useCache: true,
  19.               }
  20.             }
  21.           ]
  22.         }
  23.       },
  24.       // ts文件的loader
  25.       {
  26.         test: /\.tsx?$/, 
  27.         exclude: /node_modules/,
  28.         use: [
  29.           'babel-loader',
  30.           {
  31.             loader: 'mpvue-loader',
  32.             options: {
  33.               checkMPEntry: true
  34.             }
  35.           },
  36.           {
  37.             // loader: 'ts-loader',
  38.             loader: 'awesome-typescript-loader',
  39.             options: {
  40.               // errorsAsWarnings: true,
  41.               useCache: true,
  42.             }
  43.           }
  44.         ]
  45.       },
  46.     ]
  47.   // ...
  48.   }

main.ts

  1. // main.ts
  2. import { Component, Emit, Inject, Model, Prop, Provide, Vue, Watch } from 'vue-property-decorator';
  3. import { VueConstructor } from "vue";
  5. interface IMpVue extends VueConstructor {
  6.   mpType: string
  7. }
  9. // 添加小程序hooks http://mpvue.com/mpvue/#_4
  10. Component.registerHooks([
  11.   // app
  12.   'onLaunch', // 初始化
  13.   'onShow', // 当小程序启动，或从后台进入前台显示
  14.   'onHide', // 当小程序从前台进入后台
  15.   // pages
  16.   'onLoad', // 监听页面加载
  17.   'onShow', // 监听页面显示
  18.   'onReady', // 监听页面初次渲染完成
  19.   'onHide', // 监听页面隐藏
  20.   'onUnload', // 监听页面卸载
  21.   'onPullDownRefresh', // 监听用户下拉动作
  22.   'onReachBottom', // 页面上拉触底事件的处理函数
  23.   'onShareAppMessage', // 用户点击右上角分享
  24.   'onPageScroll', // 页面滚动
  25.   'onTabItemTap', //当前是 tab 页时， 点击 tab 时触发 （mpvue 0.0.16 支持）
  26. ])
  28. Vue.config.productionTip = false
  29. // 在这个地方引入是为了registerHooks先执行
  30. const MyApp = require('./App.vue').default as IMpVue
  31. const app = new Vue(MyApp)
  32. app.$mount()

App.vue

  1. <script lang="ts" src="./app.ts"></script>
  2. <style></style>
  1. //app.ts
  2. import { Vue, Component } from 'vue-property-decorator'
  3. declare module "vue/types/vue" {
  4.   interface Vue {
  5.     $mp: any;
  6.   }
  7. }
  9. // 必须使用装饰器的方式来指定components
  10. @Component({
  11.   mpType: 'app', // mpvue特定
  12. }as any)
  13. class App extends Vue {
  14.   // app hook
  15.   onLaunch() {
  16.     let opt = this.$root.$mp.appOptions
  17.   }
  19.   onShow() {
  20.   }
  22.   onHide() {
  23.   }
  25.   mounted() { // vue hook
  26.   }
  27. }
  29. export default App

页面

  1. <!-- page.vue -->
  2. <template>
  3.   <div class="counter-warp">
  4.     <p>Mpvue</p>
  5.     <p>ts value {{ ver }}</p>
  6.     <card text="card component"></card>
  7.     <comp-b text="card component"></comp-b>
  8.     <a :href="AppUrls.COUNTER" class="home">去往vuex</a>
  9.   </div>
  10. </template>
  11. <!--必须指定为ts-->
  12. <script lang="ts" src="./index.ts"></script>
  13. <style></style>
  1. // index.ts
  2. import { Vue, Component } from 'vue-property-decorator'
  3. import Card from '@/components/card.vue' // mpvue目前只支持的单文件组件
  4. import CompB from '@/components/compb.vue' // mpvue目前只支持的单文件组件
  5. // 必须使用装饰器的方式来指定component
  6. @Component({
  7.   components: {
  8.     Card,
  9.     CompB, //注意，vue的组件在template中的用法，`CompB` 会被转成 `comp-b`
  10.   },
  11. })
  12. class Index extends Vue {
  13.   ver: number = 123
  15.   onShow() { // 小程序 hook
  16.   }
  18.   mounted() { // vue hook
  19.   }
  20. }
  22. export default Index

组件

  1. <!-- card.vue -->
  2. <template>
  3.   <div>
  4.     <p class="card">
  5.       From Card {{text}} {{ver}}
  6.     </p>
  7.   </div>
  8. </template>
  9. <!--必须指定为ts-->
  10. <script lang="ts" src="./card.ts"></script>
  11. <style></style>
  1. // card.ts
  2. import { Vue, Component, Prop } from 'vue-property-decorator'
  3. // 必须使用装饰器的方式来指定component
  4. @Component
  5. class Card extends Vue {
  6.   @Prop({ default: '1' }) //注意用法！
  7.   text: string;
  9.   ver: number = 2;
  11.   onShow() {
  12.   }
  14.   onHide() {
  15.   }
  17.   mounted() { // vue hook
  18.   }
  19. }
  21. export default CompB

示例Demo

示例: mpvue-ts-demo