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 命令初始化项目后,只是得到了一个模板项目,如果想开启实时编译,得到小程序项目,步骤如下:
- 运行 cd myproject 切换至 WePY 项目根目录
- 运行 npm install 安装 WePY 项目依赖项
- 运行 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 文件可分为三大部分,各自对应于一个标签:
- 脚本部分,即 标签中的内容,又可分为两个部分:
- 逻辑部分,除了 config 对象之外的部分,对应于原生的 .js 文件
- 配置部分,即 config 对象,对应于原生的 .json 文件
- 结构部分,即 模板部分,对应于原生的 .wxml 文件。
- 样式部分,即样式部分,对应于原生的 .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 中实现代码高亮的相关设置步骤:
- 在 Code 里先安装 Vue 的语法高亮插件 Vetur。
- 打开任意 .wpy 文件。
- 点击右下角的选择语言模式,默认为纯文本。
- 在弹出的窗口中选择 .wpy 的配置文件关联…。
- 在选择要与 .wpy 关联的语言模式 中选择 Vue。
- 在 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组件事件处理函数对象,存放响应组件之间通过 b r o a d c a s t 、 broadcast、 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 页面的时候,要注意以下事项:
- 每个页面的 script 标签中,必须导入 wepy 模块,并创建继承自 wepy.page 的页面类;否则会报错。
- 每个页面的路径,必须记录到 app.wpy 的 config -> pages 数组中。
- 页面路径记录完毕之后,必须再回到页面文件中,摁下 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 做双向数据绑定
实现步骤如下:
- 为 input 输入框绑定数据和事件处理函数,代码为:<input value="{{msg}}" @input=“inputHandler” />
- 在 methods 中定义事件处理函数,函数名称为 inputHandler
- 在事件处理函数中,通过事件参数 e.detail.value 获取到最新的文本框内容
- 通过 this.msg = e.detail.value 为 data 中的 msg 重新赋值
3. 使用 wxs 脚本
在 WePY 中使用 wxs 脚本的方式如下:
- 将 wxs 脚本定义为外联文件,并且后缀名为 .wxs
- 在 标签内,通过 import 导入相对路径的 wxs 模块
- 在当前页面的 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()
}
}