wepy学习记录

原文地址：微信小程序组件化开发框架WePY官方文档

一、wepy中的文件

wepy的文件主要以.wpy存在，其分类有三种：

1.1 入口文件

即app.wpy，其继承自wepy.app类，包含一个config属性和其它全局属性、方法、事件。其中config属性对应原生的app.json文件，build编译时会根据config属性自动生成app.json文件。

一个app.wpy文件的典型结构如下：

<script>
import wepy from 'wepy';
export default class extends wepy.app {
	// 对应 app.json 文件
    config = {
        "pages":[
            "pages/index/index"
        ],
        "window":{
            "backgroundTextStyle": "light",
            "navigationBarBackgroundColor": "#fff",
            "navigationBarTitleText": "WeChat",
            "navigationBarTextStyle": "black"
        }
    };
	//自定义数据
    customData = {};
	//自定义方法
    customFunction ()　{ }
	//生命周期回调
    onLaunch () {}
	//生命周期回调
    onShow () {}
	//全局数据
    globalData = {}
}
</script>

<style lang="less">
/** less **/
</style>

1.2 页面文件

即page.wpy，其继承自wepy.page类，该类的主要属性介绍如下（在Page页面实例中，可以通过this.$parent来访问App实例）：

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

一个page.wpy文件的典型结构如下：

<script>
import wepy from 'wepy';
import Counter from '../components/counter';

export default class Page extends wepy.page {
    components = {counter1: Counter}; // 声明页面中所引用的组件，或声明组件中所引用的子组件

    customData = {}  // 自定义数据

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

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

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

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

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

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

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

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

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

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

<template lang="wxml">
    <view>
    </view>
    <counter1></counter1>
</template>

<style lang="less">
/** less **/
</style>

注意：WePY中的组件都是静态组件，是以组件ID作为唯一标识的，每一个ID都对应一个组件实例，当页面引入两个相同ID的组件时，这两个组件共用同一个实例与数据，当其中一个组件数据变化时，另外一个也会一起变化。
如果需要避免这个问题，则需要分配多个组件ID和实例（推荐）。

1.3 组件文件

组件文件中所声明的组件实例继承自wepy.component类，除了不需要config配置以及页面特有的一些生命周期函数之外，其属性与页面属性大致相同（实际上wepy.Page类继承自wepy.Component，所以page能用的接口component都能用，除了生命周期方法）。

一个组件文件的典型结构如下：

<template lang="wxml">
    <view>  </view>
</template>

<script>
import wepy from 'wepy';
export default class Com extends wepy.component {
    components = {};

    data = {};
    methods = {};

    events = {};
    // Other properties
}
</script>

<style lang="less">
/** less **/
</style>

二、组件渲染与通信

2.1 WEPY组件的循环渲染

wepy的template部分的语法是符合wxml标准的（一般情况下），可以通过wxml的循环渲染去渲染小程序原生组件。但是如果要循环渲染wepy的自定义组件，则需要特殊处理：

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

示例如下：

/**
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.component {
        components = {
            // 声明页面中要使用到的Child组件的ID为child
            child: Child
        }

        data = {
            list: [{id: 1, title: 'title1'}, {id: 2, title: 'title2'}]
        }
    }
</script>

2.2 computed和watcher

wepy框架也可以用类似vue的computed和watcher属性。具体内容可以在vue或者wepy的文档中查看，这里仅给出简要介绍：

• computed 计算属性。computed计算属性，是一个有返回值的函数，可直接被当作绑定数据来使用。因此类似于data属性，代码中可通过this.计算属性名来引用，模板中也可通过{{ 计算属性名 }}来绑定数据。
  
  需要注意的是，只要是组件中有任何数据发生了改变，那么所有计算属性就都会被重新计算。
• watcher 监听器。通过监听器watcher能够监听到任何属性的更新。监听器在watch对象中声明，类型为函数，函数名与需要被监听的data对象中的属性同名，每当被监听的属性改变一次，监听器函数就会被自动调用执行一次。
  
  监听器适用于当属性改变时需要进行某些额外处理的情形。

2.3 父子组件属性通信

wepy中的父子组件之间，可以使用props进行传值，传值有两种方式：静态传值、动态传值。静态传值指父组件向子组件传递常量数据，且只能传递String字符串类型。

静态传值代码示例如下：

<child title="mytitle"></child>

// child.wpy
props = {
    title: String
};

onLoad () {
    console.log(this.title); // mytitle
}

上面的代码中，在父组件template模板部分的组件标签中，使用子组件props对象中所声明的属性名作为其属性名来接收父组件传递的值。

动态传值是指父组件向子组件传递动态数据内容，父子组件数据完全独立互不干扰。但可以通过使用.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属性值，当在父组件中改变时，会同时改变子组件对应的值。
}

2.4 组件通信与交互

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

• $broadcast用于父组件向子组件（及子组件的子组件等）广播事件，事件广播的顺序为广度优先搜索顺序。如，页面Page_Index发起一个$broadcast事件，那么按先后顺序依次接收到该事件的组件为：ComA、ComB、ComC、ComD、ComE、ComF、ComG、ComH。如下图：
  
• $emit用于子组件向父组件（及父组件的父组件等）发射事件，事件发起组件的所有祖先组件会依次接收到$emit事件。如，组件ComE发起一个$emit事件，那么接收到事件的先后顺序为：组件ComA、页面Page_Index。如下图：
  
• $invoke用于组件对另一个组件中的方法的直接调用，语法类似this.$invoke('ComA', 'someMethod', 'someArgs')。

组件broadcast、emit的语法类似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
}

2.5 组件自定义事件处理函数

wepy的组件可以设置事件处理函数，语法类似@customEvent.user="myFn"，其中@表示事件修饰符，customEvent表示事件名称，.user表示事件后缀。

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

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

代码示例：

// index.wpy

<template>
	//当$emit发射childFn事件时，会传递给parentFn方法
    <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>
	//这里绑定的是小程序的事件，点击时会传递给tap方法
    <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>

2.6 slot 组件内容分发插槽

可以理解为子组件的空间占位标签，父组件可以用其他组件替代这些占位标签。

//Panel组件中模板如下
<view class="panel">
    <slot name="title">默认标题</slot>
    <slot name="content">默认内容</slot>
</view>

//父组件使用Panel时用自定义的组件替代slot
<panel>
    <view slot="title">新的标题</view>
    <view slot="content">
        <text>新的内容</text>
    </view>
</panel>

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

四、数据绑定

wepy中不需要用setData方法来绑定数据，直接为绑定数据赋值即可。

注意，在异步函数中更新数据的时候，必须手动调用$apply方法。

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