微信小程序WePY开发框架

简介

微信小程序入门门槛低、开发周期短、代码编写灵活、传播速度快等优点让微信小程序迅速火爆，开发者纷纷涌入，任何语言开发者一旦多了，就会有新的框架出来，WePY就是一个优秀的微信小程序开发框架。它让微信小程序的开发更加简单，功能更加强大，并且也优化了文件结构，熟悉了WePY之后确实可以让微信小程序开发更上一层楼。

在安装使用WePY框架之前需要安装npm，这部分就略过了，大多数开发者应该都是装了npm的，下面就从WePY的安装开始讲起，列举各项使用方法。

1、安装WePY（WePY的安装或更新都通过npm进行）

npm install -g wepy-cli

2、初始化项目

// 1.7.0之前
wepy new myproject
// 1.7.0之后
wepy init standard myproject

3、查看WePY版本号

// 成功查看版本即表示工程初始化正确
wepy --version

4、安装依赖

npm install

5、开启实时编译

npm run dev

或者（前者其实就是调用的后者）

wepy build --watch

6、project.config.json

{
  "description": "A WePY project",
  "setting": {
    "urlCheck": true,
    "es6": false,
    "postcss": false,
    "minified": false,
    "newFeature": true
  },
  "compileType": "miniprogram",
  "appid": "touristappid",
  "projectname": "hellowepy",
  "miniprogramRoot": "./dist",
  "condition": {}
}

• es6: 对应关闭ES6转ES5选项，关闭。 重要：未关闭会运行报错。
• postcss: 对应关闭上传代码时样式自动补全选项，关闭。 重要：某些情况下漏掉此项也会运行报错。
• minified: 对应关闭代码压缩上传选项，关闭。重要：开启后，会导致真机computed, props.sync 等等属性失效。（注：压缩功能可使用WePY提供的build指令代替，详见后文相关介绍以及Demo项目根目录中的wepy.config.js和package.json文件。）
• urlCheck: 对应不检查安全域名选项，开启。 如果已配置好安全域名则建议关闭。

7、VS Code设置代码高亮

文件后缀为.wpy，可共用Vue的高亮规则，但需要手动设置。下面提供一些常见IDE或编辑器中实现代码高亮的相关设置步骤以供参考(也可通过更改文件后缀名的方式来实现高亮，详见后文相关介绍)。

• Sublime
    1. 打开Sublime->Preferences->Browse Packages..进入用户包文件夹。
    2. 在此文件夹下打开cmd，运行git clone [email protected]:vuejs/vue-syntax-highlight.git，无GIT用户可以直接下载zip包解压至当前文件夹。
    3. 关闭.wpy文件重新打开即可高亮。

• WebStorm/PhpStorm
    1. 打开Settings，搜索Plugins，搜索Vue.js插件并安装。
    2. 打开Settings，搜索File Types，找到Vue.js Template，在Registered Patterns添加*.wpy，即可高亮。

• Atom
    1. 在Atom里先安装Vue的语法高亮 - language-vue，如果装过了就忽略这一步。
    2. 打开Atom -> Config菜单。在core键下添加：

customFileTypes:
   "text.html.vue": [
      "wpy"
   ]

• VS Code
    1. 在 Code 里先安装 Vue 的语法高亮插件 Vetur。
    2. 打开任意 .wpy 文件。
    3. 点击右下角的选择语言模式，默认为纯文本。
    4. 在弹出的窗口中选择 .wpy 的配置文件关联...。
    5. 在选择要与 .wpy 关联的语言模式 中选择 Vue。
    6. 在VS Code编辑器设置中设置。 //文件-首选项-设置-settings.json settings.json "files.associations": { "*.wpy": "vue" }

8、代码规范

• 变量与方法尽量使用驼峰式命名，并且注意避免使用$开头。 以$开头的标识符为WePY框架的内建属性和方法，可在JavaScript脚本中以this.的方式直接使用。

• 小程序入口、页面、组件文件名的后缀为.wpy；外链的文件可以是其它后缀。

• 使用ES6语法开发。框架在ES6(ECMAScript 6)下开发，因此也需要使用ES6开发小程序，ES6中有大量的语法糖可以让我们的代码更加简洁高效。

• 使用Promise。框架默认对小程序提供的API全都进行了Promise处理，甚至可以直接使用async/await等新特性进行开发。启用Promise方法。

• 事件绑定语法使用优化语法代替。
  a.原bindtap="click"替换为@tap="click"，原catchtap="click"替换为@tap.stop="click"。原capture-bind:tap="click"替换为@tap.capture="click"，
  b.原capture-catch:tap="click"替换为@tap.capture.stop="click"。

• 事件传参使用优化后语法代替。原bindtap="click" data-index={{index}}替换为@tap="click({{index}})"。

• 自定义组件命名应避开微信原生组件名称以及功能标签。不可以使用input、button、view、repeat等微信小程序原生组件名称命名自定义组件；另外也不要使用WePY框架定义的辅助标签repeat命名。

9、wepy.config.js配置文件说明

• wpyExt：缺省值为'.wpy'，IDE默认情况下不会对此文件类型进行高亮显示，这种情况下，除了前问代码高亮部分的介绍进行设置外，还可以直接将相关文件的后缀名由.wpy改为.vue。

• compilers：compilers为1.3.1版本之后的功能，如果需要使用其它语法，请先配置compilers，然后再安装相应的compilers。目前支持wepy-compiler-less， wepy-compiler-postcss，wepy-compiler-sass、wepy-compiler-babel、wepy-compiler-pug，其他compiler持续开发中......

• 对应各compiler请参考各自文档：
  sass：sass编译配置，参见这里。https://github.com/sass/node-sass
  less：less编译配置，参见这里。http://lesscss.org/#using-less-usage-in-code
  postcss：postcss编译配置，参见这里。http://www.css88.com/archives/7317
  stylus：stylus编译配置，参见这里。http://www.zhangxinxu.com/jq/stylus/js.php
  babel：babel编译配置，参见这里。http://babeljs.io/docs/usage/options/
  typescript：typescript编译配置，参见这里。https://www.tslang.cn/docs/home.html

• plugins：plugins为1.1.6版本之后的功能，目前支持js压缩wepy-plugin-ugliyjs、图片压缩wepy-plugin-imagemin，其他plugin持续开发中...

10、.wpy文件

• 一个.wpy文件可分为三大部分，各自对应于一个标签：

• 脚本部分，即标签中的内容，又可分为两个部分：
  逻辑部分，除了config对象之外的部分，对应于原生的.js文件；
  配置部分，即config对象，对应于原生的.json文件。

• 结构部分，即模板部分，对应于原生的.wxml文件。

• 样式部分，即样式部分，对应于原生的.wxss文件。

其中，小程序入口文件app.wpy不需要template，所以编译时会被忽略。.wpy文件中的script、template、style这三个标签都支持lang和src属性，lang决定了其代码编译过程，src决定是否外联代码，存在src属性且有效时，会忽略内联代码。

11、小程序入口app.wpy

入口文件app.wpy中所声明的小程序实例继承自wepy.app类，包含一个config属性和其它全局属性、方法、事件。其中config属性对应原生的app.json文件，build编译时会根据config属性自动生成app.json文件，如果需要修改config中的内容，请使用微信提供的相关API。

12、页面page.wpy

页面文件page.wpy中所声明的页面实例继承自wepy.page类，该类的主要属性介绍如下：

• config：页面配置对象，对应于原生的page.json文件，类似于app.wpy中的config
• components：页面组件列表对象，声明页面所引入的组件列表
• data：页面渲染数据对象，存放可用于页面模板绑定的渲染数据
• methods：wxml事件处理函数对象，存放响应wxml中所捕获到的事件的函数，如bindtap、bindchange
• events：WePY组件事件处理函数对象，存放响应组件之间通过emit、$invoke所传递的事件的函数
• 其它：小程序页面生命周期函数，如onLoad、onReady等，以及其它自定义的方法与属性

13、app小程序实例

import wepy from 'wepy';

export default class MyAPP extends wepy.app {
  customData = {};

  customFunction ()　{}

  onLaunch () {}

  onShow () {}

  config = {}  // 对应 app.json 文件

  globalData = {}
}

14、page页面实例和Component组件实例

import wepy from 'wepy';

export default class MyPage extends wepy.page {
//export default class MyComponent extends wepy.component {
  customData = {} //自定义数据

  customFunction () {} //自定义方法

  onLoad () {} //在Page和Component共用的生命周期函数

  onShow () {} //只在Page中存在的页面生命周期函数

  config = {}; //只在Page实例中存在的配置数据，对应于原生的page.json文件

  data = {}; //页面所需数据均需在这里声明，可用于模板数据绑定

  components = {}; //声明页面中所引用的组件，或声明组件中所引用的子组件

  mixins = []; //声明页面所引用的Mixin实例

  computed = {}; //声明计算属性

  watch = {}; //声明数据watcher

  methods = {}; //声明页面wxml中标签的事件处理函数。注意，此处只用于声明页面wxml中标签的bind、catch事件，自定义方法需以自定义方法的方式声明

  events = {}; //声明组件之间的事件处理函数
}

15、组件

原生小程序支持js模块化，但彼此独立，业务代码与交互事件仍需在页面处理。无法实现组件化的松耦合与复用的效果。

例如模板A中绑定一个bindtap="myclick"，模板B中同样绑定一样bindtap="myclick"，那么就会影响同一个页面事件。对于数据同样如此。因此，只有通过改变变量或者事件方法，或者给其加不同前缀才能实现绑定不同事件或者不同数据。当页面复杂之后就十分不利于开发维护。

因此，在WePY中实现了小程序的组件化开发，组件的所有业务与功能在组件本身实现，组件与组件之间彼此隔离，上述例子在WePY的组件化开发过程中，A组件只会影响到A所绑定的myclick，B也如此。

16、普通组件引用

当页面需要引入组件或组件需要引入子组件时，必须在.wpy文件的

17、组件的循环渲染

当需要循环渲染WePY组件时(类似于通过wx:for循环渲染原生的wxml标签)，必须使用WePY定义的辅助标签

/**
project
└── src
    ├── components
    |   └── child.wpy
    ├── pages
    |   ├── index.wpy    index 页面配置、结构、样式、逻辑
    |   └── log.wpy      log 页面配置、结构、样式、逻辑
    └──app.wpy           小程序配置项（全局样式配置、声明钩子等）
**/

// index.wpy

18、computed 计算属性

computed计算属性，是一个有返回值的函数，可直接被当作绑定数据来使用。因此类似于data属性，代码中可通过this.计算属性名来引用，模板中也可通过{{ 计算属性名 }}来绑定数据。

需要注意的是，只要是组件中有任何数据发生了改变，那么所有计算属性就都会被重新计算。

data = {
  a: 1
}

//计算属性aPlus，在脚本中可通过this.aPlus来引用，在模板中可通过{{ aPlus }}来插值
computed = {
  aPlus () {
    return this.a + 1
  }
}

19、watcher 监听器

通过监听器watcher能够监听到任何属性的更新。监听器在watch对象中声明，类型为函数，函数名与需要被监听的data对象中的属性同名，每当被监听的属性改变一次，监听器函数就会被自动调用执行一次。

监听器适用于当属性改变时需要进行某些额外处理的情形。

data = {
    num: 1
}

//监听器函数名必须跟需要被监听的data对象中的属性num同名，
//其参数中的newValue为属性改变后的新值，oldValue为改变前的旧值
watch = {
    num (newValue, oldValue) {
        console.log(`num value: ${oldValue} -> ${newValue}`)
    }
}

//每当被监听的属性num改变一次，对应的同名监听器函数num()就被自动调用执行一次
onLoad () {
    setInterval(() => {
        this.num++;
        this.$apply();
    }, 1000)
}

20、props 传值

动态传值是指父组件向子组件传递动态数据内容，父子组件数据完全独立互不干扰。但可以通过使用.sync修饰符来达到父组件数据绑定至子组件的效果，也可以通过设置子组件props的twoWay: true来达到子组件数据绑定至父组件的效果。那如果既使用.sync修饰符，同时子组件props中添加的twoWay: true时，就可以实现数据的双向绑定了。

注意：下文示例中的twoWay为true时，表示子组件向父组件单向动态传值，而twoWay为false(默认值，可不写)时，则表示子组件不向父组件传值。这是与Vue不一致的地方，而这里之所以仍然使用twoWay，只是为了尽可能保持与Vue在标识符命名上的一致性。

在父组件template模板部分所插入的子组件标签中，使用:prop属性（等价于Vue中的v-bind:prop属性）来进行动态传值。

// parent.wpy



data = {
    parentTitle: 'p-title'
};


// child.wpy

props = {
    // 静态传值
    title: String,

    // 父向子单向动态传值
    syncTitle: {
        type: String,
        default: 'null'
    },

    twoWayTitle: {
        type: String,
        default: 'nothing',
        twoWay: true
    }
};

onLoad () {
    console.log(this.title); // p-title
    console.log(this.syncTitle); // p-title
    console.log(this.twoWayTitle); // p-title

    this.title = 'c-title';
    console.log(this.$parent.parentTitle); // p-title.
    this.twoWayTitle = 'two-way-title';
    this.$apply();
    console.log(this.$parent.parentTitle); // two-way-title.  --- twoWay为true时，子组件props中的属性值改变时，会同时改变父组件对应的值
    this.$parent.parentTitle = 'p-title-changed';
    this.$parent.$apply();
    console.log(this.title); // 'c-title';
    console.log(this.syncTitle); // 'p-title-changed' --- 有.sync修饰符的props属性值，当在父组件中改变时，会同时改变子组件对应的值。
}

21、组件通信与交互

wepy.component基类提供emit、$invoke三个方法用于组件之间的通信和交互，如：

this.$emit('some-event', 1, 2, 3, 4);

用于监听组件之间的通信与交互事件的事件处理函数需要写在组件和页面的events对象中，如：

import wepy from 'wepy'

export default class Com extends wepy.component {
    components = {};

    data = {};

    methods = {};

    // events对象中所声明的函数为用于监听组件之间的通信与交互事件的事件处理函数
    events = {
        'some-event': (p1, p2, p3, $event) => {
               console.log(`${this.$name} receive ${$event.name} from ${$event.source.$name}`);
        }
    };
    // Other properties
}

• $broadcast
  由父组件发起，所有子组件都会收到此广播事件，除非事件被手动取消。事件广播的顺序为广度优先搜索顺序

• **broadcast正好相反，事件发起组件的所有祖先组件会依次接收到$emit事件。

• $invoke
  一个页面或组件对另一个组件中的方法的直接调用，通过传入组件路径找到相应的组件，然后再调用其方法。

Page_Index中调用组件ComA的某个方法

this.$invoke('ComA', 'someMethod', 'someArgs');

组件ComA中调用组件ComG的某个方法

this.$invoke('./../ComB/ComG', 'someMethod', 'someArgs');

22、组件自定义事件处理函数

可以通过使用.user修饰符为自定义组件绑定事件，如：@customEvent.user="myFn"，其中，@表示事件修饰符，customEvent 表示事件名称，.user表示事件后缀。目前总共有三种事件后缀：

• default: 绑定小程序冒泡型事件，如bindtap，.default后缀可省略不写；
• stop: 绑定小程序捕获型事件，如catchtap；
• user: 绑定用户自定义组件事件，通过$emit触发。注意，如果用了自定义事件，则events中对应的监听函数不会再执行。

// index.wpy





// child.wpy

23、slot 组件插槽

子组件template模板部分中声明slot标签作为内容插槽，同时必须在其name属性中指定插槽名称，还可设置默认的标签内容；然后在引入了该带有插槽的子组件的父组件template模板部分中声明用于“插拔”的内容分发标签。

注意，这些父组件中的内容分发标签必须具有slot属性，并且其值为子组件中对应的插槽名称，这样父组件内容分发标签中的内容会覆盖掉子组件对应插槽中的默认内容。

另外，要特别注意的是，父组件中一旦声明了对应于子组件插槽的内容分发标签，即便没有内容，子组件插槽中的默认内容也不会显示出来，只有删除了父组件中对应的内容分发标签，才能显示出来。

    默认标题
    默认内容



    新的标题
    
        新的内容
    

24、第三方组件

略

25、WXS (WeiXin Script)

wxs是基于原生的wxs去实现的，只是通过编译把现在的语法编译为原生语法。
wxs必须是外链文件。并且后缀为.wxs。
wxs引入后只能在template中使用，不能在script中使用。

// mywxs.wxs
module.exports = {
  text: 'This is from wxs',
  filter: function (num) {
    return num.toFixed(2);
  }
};

// index.wpy

26、interceptor 拦截器

可以使用WePY提供的全局拦截器对原生API的请求进行拦截。

import wepy from 'wepy';

export default class extends wepy.app {
    constructor () {
        // this is not allowed before super()
        super();
        // 拦截request请求
        this.intercept('request', {
            // 发出请求时的回调函数
            config (p) {
                // 对所有request请求中的OBJECT参数对象统一附加时间戳属性
                p.timestamp = +new Date();
                console.log('config request: ', p);
                // 必须返回OBJECT参数对象，否则无法发送请求到服务端
                return p;
            },

            // 请求成功后的回调函数
            success (p) {
                // 可以在这里对收到的响应数据对象进行加工处理
                console.log('request success: ', p);
                // 必须返回响应数据对象，否则后续无法对响应数据进行处理
                return p;
            },

            //请求失败后的回调函数
            fail (p) {
                console.log('request fail: ', p);
                // 必须返回响应数据对象，否则后续无法对响应数据进行处理
                return p;
            },

            // 请求完成时的回调函数(请求成功或失败都会被执行)
            complete (p) {
                console.log('request complete: ', p);
            }
        });
    }
}

27、数据绑定更新

WePY使用脏数据检查对setData进行封装，在函数运行周期结束时执行脏数据检查，一来可以不用关心页面多次setData是否会有性能上的问题，二来可以更加简洁去修改数据实现绑定，不用重复去写setData方法。

// 同步函数：
this.title = 'this is new title';
    
// 异步函数中：
setTimeout(() => {
  this.title = 'this is new title';
  this.$apply();
}, 3000);

28、其它优化细节

1. wx.request接收参数修改

// 原生代码:
wx.request({
    url: 'xxx',
    success: function (data) {
        console.log(data);
    }
});

// WePY使用方式, 需要开启Promise支持
wepy.request('xxxx').then((d) => console.log(d));

// async/await的使用方式, 需要开启Promise和async/await支持
async function request () {
   let d = await wepy.request('xxxxx');
   console.log(d);
}

2. 优化事件参数传递

// 原生的事件传参方式:
 Click me! 

Page({
    tapName: function (event) {
        console.log(event.currentTarget.dataset.id)// output: 1
        console.log(event.currentTarget.dataset.title)// output: wepy
        console.log(event.currentTarget.dataset.other)// output: otherparams
    }
});

// WePY 1.1.8以后的版本，只允许传string。
 Click me! 

methods: {
    tapName (id, title, other, event) {
        console.log(id, title, other)// output: 1, wepy, otherparams
    }
}

29、存在的问题

WePY 1.x 版本中，组件使用的是静态编译组件，即组件是在编译阶段编译进页面的，每个组件都是唯一的一个实例，目前只提供简单的 repeat 支持。不支持在 repeat 的组件中去使用 props, computed, watch 等等特性。

错误使用 :

// list.wpy
{{test.name}}

// index.wpy

   



// list.wpy

    {{item.name}}


// index.wpy