Introduction to the Labrador framework for component-based development of WeChat mini programs

labrador command

labrador init initialization project command

Note that this command will initialize the current directory as the project directory.

labrador build Build the current project

  Usage: labrador build [options]

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -c, --catch    在载入时自动catch所有JS脚本的错误
    -t, --test     运行测试脚本
    -d, --debug    DEBUG模式
    -m, --minify   压缩代码
    -f, --force    强制构建，不使用缓存

labrador watch Monitor file changes

  Usage: labrador watch [options]

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -c, --catch    在载入时自动catch所有JS脚本的错误
    -t, --test     运行测试脚本
    -d, --debug    DEBUG模式

labrador library

labrador library encapsulates the global wx variable and Most methods in the wx object support Promise, except for methods starting with on* or ending with *Sync. Use the labrador library in the following code.

import wx from 'labrador';console.log(wx.version);wx.app;         
// 和全局的 getApp() 函数效果一样，代码风格不建议粗暴地访问全局对象和方法wx.Component;   
// Labrador 自定义组件基类wx.List;        
// Labrador 自定义组件列表类wx.PropTypes;   
// Labrador 数据类型校验器集合wx.login;       
// 封装后的微信登录接口wx.getStorage;  
// 封装后的读取缓存接口

We recommend not to use synchronous blocking methods such as wx.getStorageSync(), but to use await wx.getStorage() asynchronous non-blocking methods in async functions to improve performance, unless special circumstances are encountered.

app.js

src/app.js The sample code is as follows:

import wx from 'labrador';import {sleep} from './utils/util';export default class {
  globalData = {
    userInfo: null
  };  async onLaunch() {    //调用API从本地缓存中获取数据
    let res = await wx.getStorage({ key: 'logs' });    let logs = res.data || [];    logs.unshift(Date.now());    await wx.setStorage({ key: 'logs', data: logs });    this.timer();
  }  async timer() {    while (true) {      console.log('hello');      await sleep(10000);
    }
  }  async getUserInfo() {    if (this.globalData.userInfo) {      return this.globalData.userInfo;
    }    await wx.login();    let res = await wx.getUserInfo();    this.globalData.userInfo = res.userInfo;    return res.userInfo;
  }
}

All codes use ES6/7 standard syntax. Code does not need to declare use strict because at compile time, all code will be forced to use strict mode.

The global App() method is not called in the code, but a class is exported by default using the export syntax. After compilation, Labrador will automatically add the App() method call, so please do not manually call App( ) method. This is done because the coding style discourages rough access to global objects and methods.

Custom components

Labrador's custom components are based on the components of the WeChat applet framework, and are further customized and combined, with logical processing and styles.

Common custom components in the project are stored in the src/components directory. A component is generally composed of three files. *.js , *.xml and *.less respectively correspond to js , wxml and wxml of the WeChat applet framework. wxss file. In the Labordor project source code, we deliberately used the xml and less suffixes to show the difference. If the component contains unit tests, there will be a *.test.js test script file in the component directory.

Custom component example

The following is a simple custom component code example:

逻辑 src/compontents/title/title.js

import wx from 'labrador';import randomColor  from '../../utils/random-color';const { string } = wx.PropTypes;export default class Title extends wx.Component {

  propTypes = {
    text: string
  };

  props = {
    text: ''
  };

  data = {
    text: '',
    color: randomColor()
  };  onUpdate(props) {    this.setData('text', props.text);
  }  handleTap() {    this.setData({
      color: randomColor()
    });
  }
}

自定义组件的逻辑代码和微信框架中的page很相似，最大的区别是在js逻辑代码中，没有调用全局的 Page() 函数声明页面，而是用 export 语法导出了一个默认的类，这个类必须继承于 labrador.Component 组件基类。

相对于微信框架中的page，Labrador自定义组件扩展了 propTypes 、 props 、 children 选项及 onUpdate 生命周期函数。children 选项代表当前组件中的子组件集合，此选项将在下文中叙述。

Labrador的目标是构建一个可以重用、嵌套的自定义组件方案，在现实情况中，当多个组件互相嵌套组合，就一定会遇到父子组件件的数据和消息传递。因为所有的组件都实现了 setData 方法，所以我们可以使用this.children.foobar.setData(data) 或 this.parent.setData(data) 这样的代码调用来解决父子组件间的数据传递问题，但是，如果项目中出现大量这样的代码，那么数据流将变得非常混乱。

我们借鉴了 React.js 的思想，为组件增加了 props 机制。子组件通过 this.props 得到父组件给自己传达的参数数据。父组件怎样将数据传递给子组件，我们下文中叙述。

onUpdate 生命周期函数是当组件的 props 发生变化后被调用，类似React.js中的 componentWillReceiveProps 所以我们可以在此函数体内监测 props 的变化。

组件定义时的 propTypes 选项是对当前组件的props参数数据类型的定义。 props 选项代表的是当前组件默认的各项参数值。propTypes 、 props 选项都可以省略，但是强烈建议定义 propTypes，因为这样可以使得代码更清晰易懂，另外还可以通过Labrador自动检测props值类型，以减少BUG。为优化性能，只有在DEBUG模式下才会自动检测props值类型。

编译时加上 -d 参数时即可进入DEBUG模式，在代码中任何地方都可以使用魔术变量 __DEBUG__ 来判断是否是DEBUG模式。

另外，Labrador自定义组件的 setData 方法，支持两种传参方式，第一种像微信框架一样接受一个 object 类型的对象参数，第二种方式接受作为KV对的两个参数，setData 方法将自动将其转为 object。

布局 src/compontents/title/title.xml

<view class="text-view">
  <text class="title-text" catchtap="handleTap" style="color:{{color}};">{{text}}</text>
</view>

XML布局文件和微信WXML文件语法完全一致，只是扩充了两个自定义标签 和 ，下文中详细叙述。

样式 src/compontents/title/title.less

.title-text {  font-weight: bold;  font-size: 2em;
}

虽然我们采用了LESS文件，但是由于微信小程序框架的限制，不能使用LESS的层级选择及嵌套语法。但是我们可以使用LESS的变量、mixin、函数等功能方便开发。

页面

我们要求所有的页面必须存放在 pages 目录中，每个页面的子目录中的文件格式和自定义组件一致，只是可以多出一个*.json 配置文件。

页面示例

下面是默认首页的示例代码：

逻辑 src/pages/index/index.js

import wx from 'labrador';import List from '../../components/list/list';import Title from '../../components/title/title';import Counter from '../../components/counter/counter';export default class Index extends wx.Component {
  data = {
    userInfo: {},
    mottoTitle: 'Hello World',
    count: 0
  };

  children = {
    list: new List(),
    motto: new Title({ text: '@mottoTitle', hello: '@mottoTitle' }),
    counter: new Counter({ count: '@count', onChange: '#handleCountChange' })
  };  handleCountChange(count) {    this.setData({ count });
  }  //事件处理函数
  handleViewTap() {    wx.navigateTo({
      url: '../logs/logs'
    });
  }  async onLoad() {    try {      //调用应用实例的方法获取全局数据
      let userInfo = await wx.app.getUserInfo();      //更新数据
      this.setData({ userInfo });      this.update();
    } catch (error) {      console.error(error.stack);
    }
  }  onReady() {    this.setData('mottoTitle', 'Labrador');
  }
}

页面代码的格式和自定义组件的格式一模一样，我们的思想是 页面也是组件。

js逻辑代码中同样使用 export default 语句导出了一个默认类，也不能手动调用 Page() 方法，因为在编译后，pages 目录下的所有js文件全部会自动调用 Page() 方法声明页面。

我们看到组件类中，有一个对象属性 children ，这个属性定义了该组件依赖、包含的其他自定义组件，在上面的代码中页面包含了三个自定义组件 list 、 title 和 counter ，这个三个自定义组件的 key 分别为 list 、 motto 和 counter。

自定义组件类在实例化时接受一个类型为 object 的参数，这个参数就是父组件要传给子组件的props数据。一般情况下，父组件传递给子组件的props属性在其生命周期中是不变的，这是因为JS的语法和小程序框架的限制，没有React.js的JSX灵活。但是我们可以传递一个以 @ 开头的属性值，这样我们就可以把子组建的 props 属性值绑定到父组件的 data 上来，当父组件的data 发生变化后，Labrador将自动更新子组件的 props。例如上边代码中，将子组件 motto 的 text 属性绑定到了@mottoTitle。那么在 onReady 方法中，将父组件的 mottoTitle 设置为 Labrador，那么子组件 motto 的 text 属性就会自动变为 Labrador。如果属性值以 # 开头，则将父组件的属性（非data的属性）直接绑定到子组件 props，如上边代码中的 #handleCountChange，会将父组件的 handleCountChange 方法绑定到子组件的 props.onChange 属性，这样子组件中可以通过调用 this.props.onChange(newValue) 来通知父组件数据变化。

页面也是组件，所有的组件都拥有一样的生命周期函数onLoad, onReady, onShow, onHide, onUnload，onUpdate 以及setData函数。

componets 和 pages 两个目录的区别在于，componets 中存放的组件能够被智能加载，pages 目录中的组件在编译时自动加上 Page() 调用，所以，pages 目录中的组件不能被其他组件调用,否则将出现多次调用Page()的错误。如果某个组件需要重用，请存放在 componets 目录或打包成NPM包。

布局 src/pages/index/index.xml

<view class="container">
  <view class="userinfo" catchtap="handleViewTap">
    <image class="userinfo-avatar" src="{{ userInfo.avatarUrl }}" background-size="cover"/>
    <text class="userinfo-nickname">{{ userInfo.nickName }}</text>
  </view>
  <view class="usermotto">
    <component key="motto" name="title"/>
  </view>
  <component key="list"/>
  <component key="counter"/>
</view>

XML布局代码中，使用了Labrador提供的 标签，此标签的作用是导入一个自定义子组件的布局文件，标签有两个属性，分别为 key (必选)和 name (可选，默认为key的值)。key 与js逻辑代码中的组件 key 对应，name 是组件的目录名。key 用来绑定组件JS逻辑对象的 children 中对应的数据， name 用于在src/componets 和 node_modules 目录中寻找子组件模板。

样式 src/pages/index/index.less

@import 'list';@import 'title';@import 'counter';.motto-title-text {  font-size: 3em;  padding-bottom: 1rem;
}/* ... */

LESS样式文件中，我们使用了 @import 语句加载所有子组件样式，这里的 @import 'list' 语句按照LESS的语法，会首先寻找当前目录 src/pages/index/ 中的 list.less 文件，如果找不到就会按照Labrador的规则智能地尝试寻找 src/componets和 node_modules 目录中的组件样式。

接下来，我们定义了 .motto-title-text 样式，这样做是因为 motto key 代表的title组件的模板中（src/compontents/title/title.xml）有一个view 属于 title-text 类，编译时，Labrador将自动为其增加一个前缀motto- ，所以编译后这个view所属的类为 title-text motto-title-text （可以查看 dist/pages/index/index.xml）。那么我们就可以在父组件的样式代码中使用 .motto-title-text 来重新定义子组件的样式。

Labrador支持多层组件嵌套，在上述的实例中，index 包含子组件 list 和 title，list 包含子组件 title，所以在最终显示时，index 页面上回显示两个 title 组件。

详细代码请参阅 labrador init 命令生成的示例项目。

自定义组件列表

Labrador 0.5版本后支持循环调用自定义组件生成一个列表。

逻辑 src/components/list/list.js

import wx from 'labrador';import Title from '../title/title';import Item from '../item/item';import { sleep } from '../../utils/util';export default class List extends wx.Component {

  data = {
    items: [
      { title: 'Labrador' },
      { title: 'Alaska' }
    ]
  };

  children = {
    title: new Title({ text: 'The List Title' }),
    listItems: new wx.List(Item, 'items', {
      item: '>>',
      title: '>title',
      isNew: '>isNew',
      onChange: '#handleChange'
    })
  };  async onLoad() {    await sleep(1000);    this.setData({
      items: [{ title: 'Collie', isNew: true }].concat(this.data.items)
    });
  }  handleChange(component, title) {    let item = this.data.items[component.key];    item.title = title;    this.setData('items', this.data.items);
  }
}

在上边代码中的 children.listItems 子组件定义时，并没有直接实例化子组件类，而是实例化了一个 labrador.List 类，这个类是Labrador中专门用来管理组件列表。labrador.List 实例化时，接受三个参数：

第一个参数是列表中的自定义组件类，请将原始类传入即可，不用实例化。

第二个参数是父组件上 data 属性指向，指向的属性必须是一个数组，例如上述代码中，第二个参数为 items ，则当前父组件的 data.items 属性是一个数组，这个数组又多少个元素，那么子组件列表中就自动产生多少个子组件。子组件的数量跟随data.items 数组动态变化，Labrador会自动实例化或销毁相应的子组件。销毁子组件时，子组件的 onUnload() 方法将会被调用。

第三个参数是子组件 props 数据绑定设置，如果属性值以 > 开头，则将 data.items 中对应元素的属性绑定到子组件的props。如果属性值以 # 开头，则将父组件的方法绑定到子组件的 props 中。注意，因为子组件是一个列表，所以为了区别，父组件对应的方法被调用时，第一个参数为子组件的实例，第二个及其之后的参数才是子组件中传回的参数。如果属性值是 >> 则将整个列表项数据绑定到对应的 props 上。

模板 src/components/list/list.xml

<view class="list">
  <component key="title" name="title"/>
  <list key="listItems" name="item"/>
</view>

在XML模板中，调用 标签即可自动渲染子组件列表。和 标签类似， 同样也有两个属性，key 和 name。Labrador编译后，会自动将 标签编译成 wx:for 循环。

自动化测试

我们规定项目中所有后缀为 *.test.js 的文件为测试脚本文件。每一个测试脚本文件对应一个待测试的JS模块文件。例如src/utils/util.js 和 src/utils/utils.test.js 。这样，项目中所有模块和其测试文件就全部存放在一起，方便查找和模块划分。这样规划主要是受到了GO语言的启发，也符合微信小程序一贯的目录结构风格。

在编译时，加上 -t 参数即可自动调用测试脚本完成项目测试，如果不加 -t 参数，则所有测试脚本不会被编译到 dist 目录，所以不必担心项目会肥胖。

普通JS模块测试

测试脚本中使用 export 语句导出多个名称以 test* 开头的函数，这些函数在运行后会被逐个调用完成测试。如果test测试函数在运行时抛出异常，则视为测试失败，例如代码：

// src/util.js// 普通项目模块文件中的代码片段，导出了一个通用的add函数export function add(a, b) {  return a + b;
}

// src/util.test.js// 测试脚本文件代码片段import assert from 'assert';//测试 util.add() 函数export function testAdd(exports) {  assert(exports.add(1, 1) === 2);
}

代码中 testAdd 即为一个test测试函数，专门用来测试 add() 函数，在test函数执行时，会将目标模块作为参数传进来，即会将 util.js 中的 exports 传进来。

自定义组件测试

自定义组件的测试脚本中可以导出两类测试函数。第三类和普通测试脚本一样，也为 test* 函数，但是参数不是 exports 而是运行中的、实例化后的组件对象。那么我们就可以在test函数中调用组件的方法或则访问组件的props 和 data 属性，来测试行为。另外，普通模块测试脚本是启动后就开始逐个运行 test* 函数，而组件测试脚本是当组件 onReady 以后才会开始测试。

自定义组件的第二类测试函数是以 on* 开头，和组件的生命周期函数名称一模一样，这一类测试函数不是等到组件 onReady以后开始运行，而是当组件生命周期函数运行时被触发。函数接收两个参数，第一个为组件的对象引用，第二个为run 函数。比如某个组件有一个 onLoad 测试函数，那么当组件将要运行 onLoad 生命周期函数时，先触发 onLoad 测试函数，在测试函数内部调用 run() 函数，继续执行组件的生命周期函数，run() 函数返回的数据就是生命周期函数返回的数据，如果返回的是Promise，则代表生命周期函数是一个异步函数，测试函数也可以写为async 异步函数，等待生命周期函数结束。这样我们就可以获取run()前后两个状态数据，最后对比，来测试生命周期函数的运行是否正确。

第三类测试函数与生命周期测试函数类似，是以 handle* 开头，用以测试事件处理函数是否正确，是在对应事件发生时运行测试。例如：

// src/components/counter/counter.test.jsexport function handleTap(c, run) {  let num = c.data.num;  run();  let step = c.data.num - num;  if (step !== 1) {    throw new Error('计数器点击一次应该自增1，但是自增了' + step);
  }
}

生命周期测试函数和事件测试函数只会执行一次，自动化测试的结果将会输出到Console控制台。

项目配置文件

labrador init 命令在初始化项目时，会在项目根目录中创建一个 .labrador 项目配置文件，如果你的项目是使用 labrador-cli 0.3 版本创建的，可以手动增加此文件。

配置文件为JSON格式，默认配置为：

{  "npmMap":{
  },  "uglify":{    "mangle": [],    "compress": {      "warnings": false
    }
  },  "classNames": {    "for-test":true
  }
}

npmMap 属性为NPM包映射设置，例如 {"underscore":"lodash"} 配置，如果你的源码中有require('underscore') 那么编译后将成为 require('lodash')。这样做是为了解决小程序的环境限制导致一些NPM包无法使用的问题。比如我们的代码必须依赖于包A，A又依赖于B，如果B和小程序不兼容，将导致A也无法使用。在这总情况下，我们可以Fork一份B，起名为C，将C中与小程序不兼容的代码调整下，最后在项目配置文件中将B映射为C，那么在编译后就会绕过B而加载C，从而解决这个问题。

uglify 属性为 UglifyJs2 的压缩配置，在编译时附加 -m 参数即可对项目中的所有文件进行压缩处理。

classNames 属性指定了不压缩的WXSS类名，在压缩模式下，默认会将所有WXSS类名压缩为非常短的字符串，并抛弃所有WXML页面中未曾使用的样式类，如果指定了该配置项，则指定的类不会被压缩和抛弃。这个配置在动态类名的情况下非常实用，比如XML中class="text-{{color}}"，在编译LESS时，无法确定LESS中的.text-red类是否被用到，所以需要配置此项强制保留text-red类。

ChangeLog

2016-10-09

labrador 0.3.0

重构自定义组件支持绑定子组件数据和事件

2016-10-12

labrador 0.4.0

增加自定义组件props机制

自动化测试

UglifyJS压缩集成

NPM包映射

增加.labrador项目配置文件

2016-10-13

labrador 0.4.2

修复组件setData方法优化性能产生的数据不同步问题

在DEBUG模式下输出调试信息

2016-10-16

labrador 0.5.0

新增组件列表

重构XML模板编译器

编译时绑定事件改为事件发生时自动分派

The above is the detailed content of Introduction to the Labrador framework for component-based development of WeChat mini programs. For more information, please follow other related articles on the PHP Chinese website!