微信小程序WePY框架手册

WePY 框架概述

WePY 是腾讯官方出品的一个小程序快速开发框架，对原生小程序的开发模式进行了再次封装，更贴近于 MVVM 架构模式，并支持ES6/7的一些新特性，同时语法风格更接近于 Vue.js，使用 WePY 框架能够提高小程序的开发效率。

注意：WePY 只是小程序的快速开发框架之一，市面上还有诸如 mpvue 之类的小程序开发框架也比较流行。

WePY 相比于原生小程序开发，拥有众多的开发特性和优化方案，例如：

• 开发风格接近于 Vue.js，支持很多vue中的语法特性；
• 通过 polyfill 让小程序完美支持 Promise；
• 可以使用ES6等诸多高级语法特性，简化代码，提高开发效率；
• 对小程序本身的性能做出了进一步的优化；
• 支持第三方的 npm 资源；
• 支持多种插件处理和编译器；
• etc…

安装 WePY 框架

WePY 的安装或更新都通过 npm 进行，全局安装或更新 WePY 命令行工具，可以在终端运行以下命令：

npm install wepy-cli -g

创建 WePY 项目

1. 初始化 WePY 项目

WePY 命令行工具安装完毕后，可以运行如下命令，初始化项目结构：

wepy init standard myproject

其中，”wepy init” 是固定写法，代表要初始化 wepy 项目；”standard” 代表模板类型为标准模板，可以运行 ”wepy list” 命令查看所有可用的项目模板； ”myproject” 为自定义的项目名称。
注意：创建项目的时候，要勾选 ESLint 选项！

2. WePY 项目与小程序项目的关系

通过 wepy init 命令初始化的 wepy 项目，准确来说只是一个模板项目，不能直接当作小程序运行。需要运行相关的命令，把模板项目编译为小程序项目，才可以运行。

3. 实时编译 WePY 项目

使用 wepy init 命令初始化项目后，只是得到了一个模板项目，如果想开启实时编译，得到小程序项目，步骤如下：

1. 运行 cd myproject 切换至 WePY 项目根目录
2. 运行 npm install 安装 WePY 项目依赖项
3. 运行 wepy build --watch 开启实时编译

注意：wepy build --watch 命令，会循环监听 WePY 项目中源代码的变化，自动编译生成小程序项目，生成的小程序项目默认被存放于 dist 目录中。

WePY 项目的目录结构

├── 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配置

加载并配置 WePY 项目

1. 加载 WePY 项目到微信开发者工具

1.7.0 版本之后的 wepy-cli 工具生成的项目根目录下，包含 project.config.json 文件，记录了项目的基本配置信息，例如：项目的名称、appId、生成的小程序项目根路径等。
如果项目中存在 project.config.json 文件，使用 微信开发者工具 --> 导入项目，”项目目录”请选择 wepy 项目根目录，即可根据 project.config.json 文件中的配置，把 wepy 编译生成的小程序项目加载到微信开发者工具中。

2. 解决 ESLint 报错的问题

ESLint 是好用的代码格式检查工具，能够帮助程序员养成良好的代码书写习惯。首次把 WePY 项目加载到微信开发者工具后，终端会报两个红色的错误信息。

这是因为 ESLint 规定，不允许在代码中出现连续多个空行，此时根据报错信息，找到对应的文件，删除多余的空行，重新编译 WePY 项目即可。

.wpy 文件的使用说明

1. .wpy 文件的组成部分

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

1. 脚本部分，即 标签中的内容，又可分为两个部分：

• 逻辑部分，除了 config 对象之外的部分，对应于原生的 .js 文件
• 配置部分，即 config 对象，对应于原生的 .json 文件

2. 结构部分，即 模板部分，对应于原生的 .wxml 文件。
3. 样式部分，即样式部分，对应于原生的 .wxss 文件。

其中，小程序入口文件 app.wpy 不需要 template，所以编译时会被忽略。

2. lang 和 src 属性

.wpy 文件中的 script、template、style 这三个标签都支持 lang 和 src 属性，lang 决定了其代码编译过程，src 决定是否外联代码，存在 src 属性且有效时，会忽略内联代码。
各标签对应的 lang 值如下表所示：

标签	lang 默认值	lang 支持值
style	css	css、less、scss、stylus、postcss
template	wxml	wxml、xml、pug(原jade)
script	babel	babel、TypeScript

3. 代码高亮

文件后缀为.wpy，可共用 Vue 的高亮规则，但需要手动设置。如下是 VS Code 中实现代码高亮的相关设置步骤：

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

注意：其它常见 IDE 或编辑器中设置代码高亮，可以参考：https://tencent.github.io/wepy/document.html#/?id=代码高亮

4. 小程序入口 app.wpy

入口文件 app.wpy 中所声明的小程序实例继承自 wepy.app 类，包含一个 config 属性和其它全局属性、方法、事件。
在 build 编译期间：

• config 属性会被编译为小程序的 app.json 全局配置文件；
• config 属性之外的其它节点，会被编译为小程序的 app.js 文件；
• style 标签会被编译为小程序的 app.wxss 全局样式；

5. 使用 app.wpy 全局配置小程序外观

在小程序的入口文件中找到 window 节点：app.wpy -> script标签 -> config -> window 即可全局配置小程序的外观，示例代码如下：

<script>
import wepy from 'wepy';
export default class extends wepy.app {
    config = { // 对应 app.json 文件
        "window": { // 全局配置小程序外观
            "backgroundTextStyle": "light",
            "navigationBarBackgroundColor": "#fff",
            "navigationBarTitleText": "WeChat",
            "navigationBarTextStyle": "black"
        }
    }
}
</script>

6. 页面 .wpy 文件中 script 标签组成结构

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

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

WePY 框架的开发规范

自定义默认首页

1. 创建 home 首页

在 src -> pages 目录下，创建 home.wpy 页面，并创建页面的基本代码结构，示例代码如下：

<template></template>
<script>
import wepy from 'wepy'
export default class Home extends wepy.page {
    config = {}
    methods = {}
}
</script>
<style></style>

2. 设置默认首页

如果要把刚创建的 home.wpy 设置为默认首页，需要打开 src -> app.wpy 入口文件，将 home.wpy 的页面路径，注册到 config -> pages 数组中，并调整为数组的第一项即可，示例代码如下：

<script>
import wepy from 'wepy'
import 'wepy-async-function'
export default class extends wepy.app {
  config = {
    pages: ['pages/home', 'pages/index’]
  }
}
</script>

3. 创建 .wpy 页面的注意事项

在创建 .wpy 页面的时候，要注意以下事项：

1. 每个页面的 script 标签中，必须导入 wepy 模块，并创建继承自 wepy.page 的页面类；否则会报错。
2. 每个页面的路径，必须记录到 app.wpy 的 config -> pages 数组中。
3. 页面路径记录完毕之后，必须再回到页面文件中，摁下 Ctrl + S 快捷键重新编译生成页面，否则会报错。

为 WePY 页面绑定事件并传参

1. 使用 @ 绑定事件处理函数

原生小程序使用 bindtap、bindinput 等绑定事件处理函数，在 wepy 框架中，优化了事件绑定机制，支持类似于 Vue.js 的事件绑定语法，今后绑定事件可以采用如下方式：

• 原 bindtap=“clickHandler” 替换为 @tap=“clickHandler”
• 原 bindinput=“inputHandler” 替换为 @input=“inputHandler”

2. 事件传参的优化写法

如果 @ 符号绑定的事件处理函数需要传参，可以采用优化的写法，示例如下：

• 原 bindtap=“clickHandler” data-index={{index}} 替换为 @tap=“click({{index}})”

3. 定义事件处理函数的注意点

通过 @ 符号绑定的事件处理函数，必须定义到页面的 methods 节点下。

注意：对于 WePY 中的 methods 属性，因为与 Vue 中的使用习惯不一致，非常容易造成误解，这里需要特别强调一下：WePY 中的 methods 属性只能声明页面 wxml 标签的事件处理函数，不能声明自定义方法，自定义方法需要声明到和 methods 平级的节点位置，这与 Vue 中的用法是不一致的。

WePY 页面的数据绑定

1. 使用 data 定义私有数据

.wpy 页面中的私有数据，需要定义到 data 节点中，页面上可以使用双大括号语法 {{ }} 渲染 data 中的数据
示例代码如下：

<template>
    <view>{{msg}}</view>
</template>

data = {
    msg: 'hello wepy'
}

2. 将文本框与 data 做双向数据绑定

实现步骤如下：

1. 为 input 输入框绑定数据和事件处理函数，代码为：<input value="{{msg}}" @input=“inputHandler” />
2. 在 methods 中定义事件处理函数，函数名称为 inputHandler
3. 在事件处理函数中，通过事件参数 e.detail.value 获取到最新的文本框内容
4. 通过 this.msg = e.detail.value 为 data 中的 msg 重新赋值

3. 使用 wxs 脚本

在 WePY 中使用 wxs 脚本的方式如下：

1. 将 wxs 脚本定义为外联文件，并且后缀名为 .wxs
2. 在 标签内，通过 import 导入相对路径的 wxs 模块
3. 在当前页面的 class 类中，通过 wxs = { } 注册刚才导入的 wxs 模块

注意：被注册的 wxs 模块，只能在当前页面的 template 中使用，不能在script中使用

WePY 页面中发起数据请求

1. 配置 promisify 启用 async 和 await

默认使用 wepy-cli 创建的项目，不支持使用 ES7 的 async 和 await 来简化 Promise API 的调用。需要手动开启此功能：打开 src -> app.wpy，找到 constructor() 构造函数，在构造函数中代码的最后一行，添加 this.use(‘promisify’) 即可，示例代码如下：

constructor() {
  super()
  this.use('requestfix')
  this.use('promisify') // 添加此行代码，即可启用 async 和 await
}

2. 使用 wepy.request 发起 Get 请求

WePY 框架对原生小程序做了封装，之前通过 wx 调用的 API，都可以直接使用 wepy 进行调用，例如：wx.request() 是原生小程序的数据请求 API，现在可以直接通过 wepy.request() 发起网络数据请求。示例代码如下：

methods = {
  async getInfo() {
    const res = await wepy.request('https://www.liulongbin.top:8082/api/get’)
    console.log(res)
  }
}

3. 使用 wepy.request 发起 Post 请求

通过 wepy.request() 方法发起 Post 请求的示例代码如下：

methods = {
  async postInfo() {
    const res = await wepy.request({
      url: 'https://www.liulongbin.top:8082/api/post',
      method: 'post',
      data: { name: 'zs', age: 20 }
    })
    console.log(res)
  }
}

4. 异步更新数据

在异步函数中更新数据的时候，页面检测不到数据的变化，必须手动调用 this.$apply 方法。作用是强制页面重新渲染，代码示例如下：

methods = {
  async getInfo() { // 被 async 修饰的函数叫做异步函数
    const res = await wepy.request('https://www.liulongbin.top:8081/api/get’)
    this.getMsg = res.data
    this.$apply()
  }
}