小程序框架wepy文档

项目创建与使用

安装wepy

wepy安装都通过npm安装

安装wepy命令行工具:

npm install wepy-cli -g

在开发目录生成开发DEMO:

wepy new myproject

安装依赖

npm  install

开发实时编译:

wepy build --watch

项目目录结构:

├── dist                   小程序运行代码目录（该目录由WePY的build指令自动编译生成，请不要直接修改该目录下的文件）
├── node_modules           
├── src                    代码编写的目录（该目录为使用WePY后的开发目录）
|   ├── components         WePY组件目录（组件不属于完整页面，仅供完整页面或其他组件引用）
|   |   ├── com_a.wpy      可复用的WePY组件a
|   |   └── com_b.wpy      可复用的WePY组件b
|   ├── pages              WePY页面目录（属于完整页面）
|   |   ├── index.wpy      index页面（经build后，会在dist目录下的pages目录生成index.js、index.json、index.wxml和index.wxss文件）
|   |   └── other.wpy      other页面（经build后，会在dist目录下的pages目录生成other.js、other.json、other.wxml和other.wxss文件）
|   └── app.wpy            小程序配置项（全局数据、样式、声明钩子等；经build后，会在dist目录下生成app.js、app.json和app.wxss文件）
└── package.json           项目的package配置

开发使用说明

1.使用微信开发者工具新建项目，本地开发选择dist目录

2.微信开发者工具 --> 项目 --> 关闭ES6转ES5

3.微信开发者工具 --> 项目 --> 关闭postcss--对应关闭上传代码时样式自动补全选项

4.微信开发者工具 --> 项目 --> 关闭minified--对应关闭代码压缩上传选项

5.本地项目根目录运行wepy build --watch，开启实时编译

代码高亮

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

Sublime

1. 打开Sublime->Preferences->Browse Packages..进入用户包文件夹
2. 在此文件夹下打开cmd，运行git clone git@github.com: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" }

VIM

1. 安装 Vue 的 VIM 高亮插件，例如 posva/vim-vue。
2. 配置 .wpy 后缀名的文件使用 Vue 语法高亮。

au BufRead,BufNewFile *.wpy setlocal filetype=vue.html.javascript.css

代码规范

1.变量与方法尽量使用驼峰式命名，避免使用$开头;以$开头的方法或者属性为框架内建方法或者属性，可以被使用

2.入口，页面，组件的命名后缀为.wpy。外链的文件可以是其它后缀

3.使用ES6语法开发

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

4.使用Promise

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

主要解决问题

开发模式转换

在原有的小程序的开发模式下进行再次封装，更贴近于现有MVVM框架开发模式。框架在开发过程中参考了现在框架的一些特性，并融入其中，以下是使用wepy前后的代码对比图。

官方DEMO代码：

//index.js
//获取应用实例
var app = getApp()
Page({
  data: {
    motto: 'Hello World',
    userInfo: {}
  },
  //事件处理函数
  bindViewTap: function() {
    console.log('button clicked')
  },
  //页面的生命周期函数
  onLoad: function () {
    console.log('onLoad')
  }
})

基于wepy的实现：

import wepy from 'wepy';
//通过继承自wepy.page的类创建页面逻辑
export default class Index extends wepy.page {
    data = {
        motto: 'Hello World',
        userInfo: {}
    };
    methods = {
        bindViewTap () {
            console.log('button clicked');
        }
    };
    onLoad() {
        console.log('onLoad');
    };
}

支持组件化开发。

示例代码：

// index.wpy
<template>
    <view>
        <component id="pannel" path="pannel"></component>
        <component id="counter1" path="counter"></component>
        <component id="counter2" path="counter"></component>
        <component id="list" path="list"></component>
    </view>
</template>
<script>
//引入List、Panel和Counter组件
import wepy from 'wepy';
import List from '../components/list';
import Panel from '../components/panel';
import Counter from '../components/counter';
export default class Index extends wepy.page {
  //页面配置
    config = {
        "navigationBarTitleText": "test"
    };
    //声明页面中将要使用到的组件
    components = {
        panel: Panel,
        counter1: Counter,
        counter2: Counter,
        list: List
    };
}
</script>

支持加载外部NPM包

在编译过程当中，会递归遍历代码中的require然后将对应依赖文件从node_modules当中拷贝出来，并且修改require为相对路径，从而实现对外部NPM包的支持

单文件模式，使得目录结构更加清晰

官方目录结构要求app必须有三个文件app.json/app.js/app.wxss,页面有4个文件index.json/index.js/index.wxml/index.wxss,而且文件必须同名。所以使用wepy开发前后开发目录对比如下：

官方DEMO：

project
├── pages
|   ├── index
|   |   ├── index.js    index 页面逻辑
|   |   ├── index.json  index 页面配置
|   |   ├── index.wxml  index 页面结构
|   |   └── index.wxss  index 页面样式
|   └── log
|       ├── log.js      log 页面逻辑
|       ├── log.json    log 页面配置
|       ├── log.wxml    log 页面结构
|       └── log.wxss    log 页面样式
├── app.js              小程序逻辑
├── app.json            小程序公共配置
└── app.wxss            小程序公共样式

使用wepy框架后目录结构：

project
└── src
    ├── pages
    |   ├── index.wpy    index 页面逻辑、配置、结构、样式
    |   └── log.wpy      log 页面逻辑、配置、结构、样式
    └──app.wpy           小程序逻辑、公共配置、公共样式

默认使用babel编译，支持ES6/7的一些新特性

用户可以通过修改.wepyrc配置文件，配置自己熟悉的babel环境进行开发。默认开启使用了一些新的特性如promise，async/await等

示例代码：

import wepy from 'wepy';
export default class Index extends wepy.page {
    getData() {
        return new Promise((resolve, reject) => {
            setTimeout(() => {
                resolve({data: 123});
            }, 3000);
        });
    };
    async onLoad() {
        let data = await this.getData();
        console.log(data.data);
    };
}

针对原生API进行优化

对现在API进行promise处理，同时修复一些现有API的缺陷，比如：wx.request并发问题等

原有代码：

onLoad = function () {
    var self = this;
    wx.login({
        success: function (data) {
            wx.getUserInfo({
                success: function (userinfo) {
                    self.setData({userInfo: userinfo});
                }
            });
        }
    });
}

基于wepy实现代码：

import wepy from 'wepy';
async onLoad() {
    await wx.login();
    this.userInfo = await wx.getUserInfo();
}

进阶说明

.wepyrc 配置文件说明

执行wepy new demo后，会生成类似配置文件

let prod = process.env.NODE_ENV === 'production';
module.exports = {
    'target': 'dist',
    'source': 'src',
    'wpyExt': '.wpy',
    'compilers': {
        less: {
            'compress': true
        },
        /*sass: {
            'outputStyle': 'compressed'
        },
        postcss: {
            plugins: [
                cssnext({
                    browsers:['iOS 9', 'Android 4.4']
                })
            ]
        },*/
        babel: {
            'presets': [
                'es2015',
                'stage-1'
            ],
            'plugins': [
                'transform-export-extensions',
                'syntax-export-extensions',
                'transform-runtime'
            ]
        }
    },
    'plugins': {
    }
};
if (prod) {
    // 压缩sass
    module.exports.compilers['sass'] = {'outputStyle': 'compressed'};

    // 压缩less
    module.exports.compilers['less'] = {'compress': true};

    // 压缩js
    module.exports.plugins = {
        'uglifyjs': {
            filter: /\.js$/,
            config: {
            }
        },
        'imagemin': {
            filter: /\.(jpg|png|jpeg)$/,
            config: {
                'jpg': {
                    quality: 80
                },
                'png': {
                    quality: 80
                }
            }
        }
    };
}

wpyExt：缺省值为'.wpy'

wpy文件说明

wpy文件的编译过程过下：

一个.wpy文件分为三个部分：

1.样式对应原有wxss

2.模板对应原有wxml

3.代码对应原有js

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

<style type="less" src="page1.less"></style>
<template type="wxml" src="page1.wxml"></template>
<script>
    // some code
</script>

标签对应 type 值如下表所示：

script说明

程序入口app.wpy

<style type="less">
/** less **/
</style>
<script>
import wepy from 'wepy';
export default class extends wepy.app {
    config = {
        "pages":[
            "pages/index/index"
        ],
        "window":{
            "backgroundTextStyle": "light",
            "navigationBarBackgroundColor": "#fff",
            "navigationBarTitleText": "WeChat",
            "navigationBarTextStyle": "black"
        }
    };
    onLaunch() {
        console.log(this);
    }
}
</script>

入口app.wpy继承自wepy.app，包含一个config属性和其全局属性、方法、事件。其中config属性对应原有的app.json，编译时会根据config生成app.json文件，如果需要修改config中的内容，请使用系统提供API

页面index.wpy

<style type="less">
/** less **/
</style>
<template type="wxml">
    <view></view>
    <component id="counter1" path="counter"></component>
</template>
<script>
import wepy form 'wepy';
import Counter from '../components/counter';
export default class Index extends wepy.page {
    config = {};
    components = {counter1: Counter};
    data = {};
    methods = {};
    events = {};
    onLoad() {};
    // Other properties
}
</script>

页面入口继承自wepy.page，主要属性说明如下：

组件com.wpy

<style type="less">
/** less **/
</style>
<template type="wxml">
    <view></view>
</template>
<script>
import wepy form 'wepy';
export default class Com extends wepy.component {
    components = {};
    data = {};
    methods = {};
    events = {};
    // Other properties
}
</script>

页面入口继承自wepy.component，属性与页面属性一样，除了不需要config以及页面特有的一些小程序事件等

组件

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

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

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

组件引用

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

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

// index.wpy
<template>
    <!-- 以`<script>`脚本部分中所声明的组件ID为名命名自定义标签，从而在`<template>`模板部分中插入组件 -->
    <child></child>
</template>
<script>
    import wepy from 'wepy';
    //引入组件文件
    import Child from '../components/child';
    export default class Index extends wepy.page {
        //声明组件，分配组件id为child
        components = {
            child: Child
        };
    }
</script>

页面和组件都可以引入子组件，且可以引入若干组件

eg:Index页面引入A，B，C三个组件，同时组件A和B又有自己的子组件D，E，F，G，H

组件的循环渲染

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

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

// index.wpy
<template>
    <!-- 注意，使用for属性，而不是使用wx:for属性 -->
    <repeat for="{{list}}" key="index" index="index" item="item">
        <!-- 插入<script>脚本部分所声明的child组件，同时传入item -->
        <child :item="item"></child>
    </repeat>
</template>
<script>
    import wepy from 'wepy';
    // 引入child组件文件
    import Child from '../components/child';
    export default class Index extends wepy.page {
        components = {
            // 声明页面中要使用到的Child组件的ID为child
            child: Child
        }
        data = {
            list: [{id: 1, title: 'title1'}, {id: 2, title: 'title2'}]
        }
    }
</script>

computed 计算属性

computed计算属性，是一个有返回值的函数，可直接被当作绑定数据来使用。因此类似于data属性，代码中可通过this.计算属性名来引用，模板中也可通过{{ 计算属性名 }}来绑定数据;需要注意的是，只要是组件中有任何数据发生了改变，那么所有计算属性就都会被重新计算

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

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)
}

props 传值

props传值在WePY中属于父子组件之间传值的一种机制，包括静态传值与动态传值。在props对象中声明需要传递的值，静态传值与动态传值的声明略有不同

静态传值

静态传值为父组件向子组件传递常量数据，因此只能传递String字符串类型。在父组件template模板部分的组件标签中，使用子组件props对象中所声明的属性名作为其属性名来接收父组件传递的值

<child title="mytitle"></child>
// child.wpy
props = {
    title: String
};
onLoad () {
    console.log(this.title); // mytitle
}

动态传值

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

注意：下文示例中的twoWay为true时，表示子组件向父组件单向动态传值，而twoWay为false(默认值，可不写)时，则表示子组件不向父组件传值。这是与Vue不一致的地方，而这里之所以仍然使用twoWay，只是为了尽可能保持与Vue在标识符命名上的一致性。在父组件template模板部分所插入的子组件标签中，使用:prop属性（等价于Vue中的v-bind:prop属性）来进行动态传值

// parent.wpy
<child :title="parentTitle" :syncTitle.sync="parentTitle" :twoWayTitle="parentTitle"></child>
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属性值，当在父组件中改变时，会同时改变子组件对应的值。
}

组件通信与交互

wepy.component基类提供三个方法$broadcast/$emit/$invoke，因此任一页面或任一组件都可以调用上述三种方法实现通信与交互，如：

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

组件的事件监听需要写在events属性下，如：

import wepy form 'wepy';
export default class Com extends wepy.component {
    components = {};
    data = {};
    methods = {};
    events = {
        'some-event': ($event, ...args) {
               console.log(`${this.name} receive ${$event.name} from ${$event.source.name}`);
        }
    };
    // Other properties
}

$broadcast

$broadcast事件是由父组件发起，所有子组件都会收到此广播事件，除非事件被手动取消。事件广播的顺序为广度优先搜索顺序，如上例子，如果Index发起一个$broadcast事件，那么接收到事件的先后顺序为：A, B, C, D, E, F, G, H

$emit

$emit与$broadcast正好相反，事件发起组件的父组件会依次接收到$emit事件，如上例子，如果E发起一个$emit事件，那么接收到事件的先后顺序为：A, Index

$invoke

$invoke是一个组件对另一个组件的直接调用，通过传入的组件路径找到相应组件，然后再调用其方法;如果想在Index中调用组件A的某个方法：

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

如果想在组件A中调用组件G的某个方法：

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

Page页面实例和Component组件实例

由于Page页面实际上继承自Component组件，即Page也是组件。除扩展了页面所特有的config配置以及特有的页面生命周期函数之外，其它属性和方法与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 = {};  // 声明组件之间的事件处理函数
}

注意，对于WePY中的methods属性，因为与Vue中的使用习惯不一致，非常容易造成误解，这里需要特别强调一下：WePY中的methods属性只能声明页面wxml标签的bind、catch事件，不能声明自定义方法，这与Vue中的用法是不一致的

组件自定义事件处理函数

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

目前总共有三种事件后缀：

.default: 绑定小程序冒泡型事件，如bindtap，.default后缀可省略不写；

.stop: 绑定小程序捕获型事件，如catchtap；

.user: 绑定用户自定义组件事件，通过$emit触发。注意，如果用了自定义事件，则events中对应的监听函数不会再执行。

// index.wpy
<template>
    <child @childFn.user="parentFn"></child>
</template>
<script>
    import wepy from 'wepy'
    import Child from '../components/child'
    export default class Index extends wepy.page {
        components = {
            child: Child
        }
        methods = {
            parentFn (num, evt) {
                console.log('parent received emit event, number is: ' + num)
            }
        }
    }
</script>

// child.wpy
<template>
    <view @tap="tap">Click me</view>
</template>
<script>
    import wepy from 'wepy'
    export default class Child extends wepy.component {
        methods = {
            tap () {
                console.log('child is clicked')
                this.$emit('childFn', 100)
            }
        }
    }
</script>

slot 组件内容分发插槽

WePY中的slot插槽作为内容分发标签的空间占位标签，便于在父组件中通过对相当于扩展板卡的内容分发标签的“插拔”，更为灵活、方便地对子组件进行内容分发。

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

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

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

示例：

在Panel组件中有以下模板：

<view class="panel">
    <slot name="title">默认标题</slot>
    <slot name="content">默认内容</slot>
</view>

在父组件中使用Panel子组件时，可以这样使用：

<panel>
    <view slot="title">新的标题</view>
    <view slot="content">
        <text>新的内容</text>
    </view>
</panel>

第三方组件

WePY允许使用基于WePY开发的第三方组件

Mixin混合

混合可以将组件之间的可复用部分抽离，从而在组件中使用混合时，可以将混合的数据，事件以及方法注入到组件之中。混合分为两种：默认式混合/兼容式混合

默认式混合

对于组件data数据，components组件，events事件以及其它自定义方法采用默认式混合，即如果组件未声明该数据，组件，事件，自定义方法等，那么将混合对象中的选项将注入组件之中。对于组件已声明的选项将不受影响

// mixins/test.js
import wepy from 'wepy';
export default class TestMixin extends wepy.mixin {
    data = {
        foo: 'foo defined by page',
        bar: 'bar defined by testMix'
    };
    methods = {
    tap () {
      console.log('mix tap');
    }
  }
}

// pages/index.wpy
import wepy from 'wepy';
import TestMixin from './mixins/test';
export default class Index extends wepy.page {
    data = {
        foo: 'foo defined by index'
    };
    mixins = [TestMixin];
    onShow() {
        console.log(this.foo); // foo defined by index
        console.log(this.bar); // bar defined by testMix
    }
}

兼容式混合

对于组件methods响应事件，以及小程序页面事件将采用兼容式混合，即先响应组件本身响应事件，然后再响应混合对象中响应事件。注意，这里事件的执行顺序跟Vue中相反，Vue中是先执行mixin中的函数， 再执行组件本身的函数

// mixins/test.js
import wepy from 'wepy';
export default class TestMixin extends wepy.mixin {
    methods = {
        tap () {
            console.log('mixin tap');
        }
    };
    onShow() {
        console.log('mixin onshow');
    }
}

// pages/index.wpy
import wepy from 'wepy';
import TestMixin from './mixins/test';
export default class Index extends wepy.page {
    mixins = [TestMixin];
    methods = {
        tap () {
            console.log('index tap');
        }
    };
    onShow() {
        console.log('index onshow');
    }
}

WXS (WeiXin Script)

WePY 从1.7.x 版本开始支持 wxs 语法，但语法与原生 wxs 稍有出入

project
└── src
    ├── wxs
    |   └── mywxs.wxs      wxs 文件 
    ├── pages
    |   └── index.wpy      页面
    └──app.wpy           

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

// index.wpy
<template>
  <text>{{m1.text}}</text>
  <text>{{m1.filter(num)}}</text>
</template>

<script>
  import wepy from 'wepy';
  import mywxs from '../wxs/mywxs.wxs';
  export default class Index extends wepy.page {
    data = {
      num: 10
    };
    wxs = {
      m1: mywxs
    }
  };
</script>

注意:

wxs是基于原生的wxs去实现的，只是通过编译把现在的语法编译为原生语法

wxs必须是外链文件。并且后缀为.wxs

wxs引入后只能在template中使用，不能在script中使用

interceptor 拦截器

可以使用WePY提供的全局拦截器对原生API的请求进行拦截。具体方法是配置API的config、fail、success、complete回调函数

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);
            }
        });
    }
}

数据绑定

小程序数据绑定方式

小程序通过Page提供的setData方法去绑定数据，如：

this.setData({title: 'this is title'});

因为小程序架构本身原因，页面渲染层和JS逻辑层分开的，setData操作实际就是JS逻辑层与页面渲染层之间的通信，那么如果在同一次运行周期内多次执行setData操作时，那么通信的次数是一次还是多次呢？这个取决于API本身的设计

wepy数据绑定方式

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

this.title = 'this is title';

但需注意，在函数运行周期之外的函数里去修改数据需要手动调用$apply方法。如：

setTimeout(() => {
    this.title = 'this is title';
    this.$apply();
}, 3000);

wepy脏数据检查流程

在执行脏数据检查时，会通过this.$$phase标识当前检查状态，并且会保证在并发的流程当中，只会有一个脏数据检查流程在运行

其它优化细节

wx.request 接收参数修改

// 官方

wx.request({
    url: 'xxx',
    success: function (data) {
        console.log(data);
    }
});

// wepy 使用方式,request 接口从只接收Object变为可接收String

wx.request('xxxx').then((d) => console.log(d));

优化事件参数传递

// 官方

<view id="tapTest" data-hi="WeChat" bindtap="tapName"> Click me! </view>
Page({
  tapName: function(event) {
    console.log(event.currentTarget.hi)// output: WeChat
  }
});

// wepy 建议传参方式

<view id="tapTest" data-wepy-params="1-wepy-something" bindtap="tapName"> Click me! </view>
events: {
    tapName (event, id, title, other) {
        console.log(id, title, other)// output: 1, wepy, something
    }
}

改变数据绑定方式

保留setData方法，但不建议使用setData执行绑定，修复传入undefined的bug，并且修改入参支持：

this.setData(target, value)
this.setData(object)

// 官方

<view> {{ message }} </view>
onLoad: function () {
    this.setData({message: 'hello world'});
}

// wepy

<view> {{ message }} </view>
onLoad () {
    this.message = 'hello world';
}

组件代替模板和模块

// 官方

<!-- item.wxml -->
<template name="item">
  <text>{{text}}</text>
</template>
<!-- index.wxml -->
<import src="item.wxml"/>
<template is="item" data="{{text: 'forbar'}}"/>
<!-- index.js -->
var item = require('item.js')

// wepy

<!-- /components/item.wpy -->
 <text>{{text}}</text>
<!-- index.wpy -->
<template>
    <component id="item"></component>
</template>
<script>
    import wepy from 'wepy';
    import Item from '../components/item';
    export default class Index extends wepy.page {
        components = { Item }
    }
</script>

API

wepy.event

wepy.component

wepy.page

wepy.app