微信小程序轻量型开发助手/增强类库

MP Helper 不是一个框架，而是基于小程序原生 MINA 框架的开发助手与语法增强类库

特性

使用 .mp 单文件页面组件化开发，内聚且低耦合
支持 require import 直接引入 npm 包依赖
API 语法增强，新增数据状态管理 store context、事件管理 emitter、计算属性 computed 等能力
拓展工具集，包含小程序原生方法 Promise 化 promiser 、类名属性连接 classNames、行内样式连接 inlineStyles 等方法

特点

轻量易用，低侵入性，低学习成本
不改变小程序原生 MINA 框架的语法与用法习惯
编译时不会对 js 语法进行转译（因此请开启微信开发者工具的 ES6 转 ES5 增强编译 功能）
小程序基础库最低要求 v2.6.1

TODO

命令行 CLI：图片支持压缩
修复 setData 赋值 undefined 报错

快速上手

安装

$ npm i -S mp-helper

配置 CLI

在项目中 package.json 文件字段 scripts 配置

/* package.json */
"scripts": {
  "dev": "mp-helper -w src dist",
  "build": "mp-helper src dist"
}

src 为输入路径
dist 为输出路径
使用 npm run dev 命令开发
使用 npm run build 命令构建

至此即可使用 .mp 单文件规范进行开发

在微信开发者工具中需要勾选下述两项

ES6 转 ES5
(可选) 启用自定义启动命令 npm run build

引入类库 Core

<!-- .mp -->
<script>
import mp from 'mp-helper';
// ...
</script>

mp-helper CLI 在解析 .mp 文件时会自动处理引入的 npm 包依赖

`.mp` 单文件

显示高亮

在当前项目根目录下，创建 .vscode/settings.json 文件，内容为：

{
  "files.associations": {
    "*.mp": "html"
  },
  "css.validate": false
}

模板

开发时可参考文件模板：

注册小程序 app.mp
注册页面 page.mp
注册页面 (组件化页面) component-page.mp
注册组件 component.mp

例子

这是一个文件名为 index.mp 的简单实例：

<config>
{
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "演示页面",
    "backgroundColor": "#eeeeee",
    "backgroundTextStyle": "light"
}
</config>

<template>
<view class="container">
    <button wx:if="{{ !userInfo }}" bind:tap="tapButton">按钮</button>
    <block wx:else>
        <image src="{{ userInfo.avatarUrl }}"></image>
        <text class="nickname">{{ userInfo.nickName }}</text>
    </block>
</view>
</template>

<script>
// 若想使用对原生 App/Page/Component 对象进行增强的语法
// 可引入 mp-helper API 代替进行注册小程序/页面/组件
//   App -> mp.App
//   Page -> mp.Page
//   Component -> mp.Component
import mp from 'mp-helper';

mp.Page({ 
    data: {
        userInfo: null
    },
    tapButton() {
        this.setData({
            userInfo: {
                avatarUrl: '',
                nickName: '昵称',
            }
        });
    }
});
</script>

<style lang="less">
.container {
    background: #fff;
}
</style>

语法

页面 index.mp 文件聚合了

标签	编译分离	属性
页面配置 `config`	生成 index.json	`lang` 可选值为 `json` `js`，默认值为 `json`
页面模板 `template`	生成 index.wxml	`lang` 可选值为 `wxml`，默认值为 `wxml`
页面逻辑 `script`	生成 index.js	`lang` 可选值为 `js`/`javascript`，默认值为 `js`
页面样式 `style`	生成 index.wxss	`lang` 可选值为 `less`、`wxss`，默认值为 `wxss`

解析编译

利用 mp-helper 命令行可完成对 .mp 文件的解析与编译：

Usage: mp-helper [options] <input...> <output>

Options:
  -w, --watch            监听文件变化
  -c, --config <config>  高级配置模式 (默认读取 ./package.json)
  -v, --version          output the version number
  -h, --help             output usage information

Arguments:
  <input>   输入路径 (Globs 规则)
  <output>  输出路径

Examples:
# 纯命令行模式
$ mp-helper ./src ./dist
$ mp-helper -w ./src ./dist
$ mp-helper "src/**.mp" ./dist
# 高级配置模式 (读取 ./package.json `mp-helper` 字段)
$ mp-helper -c
$ mp-helper -c -w

配置模式： 在文件 package.json 进行配置的例子

{
    // ...
    "mp-helper": {
        // io 输入输出 支持配置多个
        "io": [
            {
                "input": "./input",
                "output": "./output"
            },
            {
                "input": ["./src/**.mp", "./static"],
                "output": "./dist"
            }
        ],
        // 是否开启监听 默认 false
        "watch": false,
        // 是否清理 output 文件夹 默认 false
        "clean": false,
        // 是否提取依赖 默认 true
        "extractDeps": true
    }
}

增强 API

约定： 为了与小程序原生API进行区别，在注册 App/Page/Component 方法内新增的属性与方法名前会加上 $

mp.App(`options`)

options 支持所有的原生 App 参数，此外新增了：

mp.App({
    $store,
})

构造属性 `$store`

用于存储全局数据，将注入到所有页面与组件的 data.$store 内, 因此需慎重存储重要的数据

在 App/Page/Component 内都可通过 this.$setStore 实例方法设置全局数据使页面响应, 用法与一致 this.setData

需注意的是，在 Component 内只能在 attached 生命周期后获取 this.data.$store、调用 this.$setStore

在低于 v2.7.4 的版本中 $store 不可用用于组件的 $computed 或 observers，兼容低版本需使用 _store

原因为：组件 observers 属性无法监听以 $ 开头的属性名

mp.Page(`options`)

options 支持所有的原生 Page 参数，此外新增了：

mp.Page({
    $context,
})

若想将页面以自定义组件形式构造，可参见官方提供的方法使用 Component 构造器构造页面

此情况需使用 mp.Component 进行注册页面，且页面配置需添加 "usingComponents": {}，模板可见 component-page.mp

Page 中可使用 this.$app 方法获取 app 实例

构造属性 `$context`

用于存储当前页面上下文数据，将注入到当前页面及其所有组件的 data.$context 内, 跨页面不共享

在 Page/Component 内都可通过 this.$setContext 实例方法设置当前页面上下文数据使页面响应, 用法与一致 this.setData

需注意的是，在 Component 内只能在 ready 生命周期后获取 this.data.$context、调用 this.$setContext

在低于 v2.7.4 的版本中 $context 不可用用于组件的 $computed 或 observers，兼容低版本需使用 _context

原因为：组件 observers 属性无法监听以 $ 开头的属性名

mp.Component(`options`)

options 支持所有的原生 Component 参数，此外新增了：

mp.Component({
    $computed,
})

Component 中可使用 this.$app 方法获取 app 实例。在 attached 生命周期后，可使用 this.$page 方法获取所在 page 实例

构造属性 `$computed`

$computed: {
    total: {
        depend: ['list'], // 即 this.data.list
        get(list) {
            return list.length;
        }
    },
    showList: {
        depend: ['total', 'loading'], // 即 computed total (this.data.total) 和 this.data.loading
        get(total, loading) {
            return total && !loading;
        }
    },
}

此处需通过 depend 声明当前计算属性所用到的依赖数据（在 this.data 中的 path），取值会作为参数传入 get 方法中，实际上可以理解为是小程序组件 observers 的语法糖

计算属性最终将会注入至 this.data 内

路由

在 Page/Component 内都可通过 this.$route 实例属性获取当前的路由信息

事件监听

全局事件监听（四种方式）：
- mp.on()
- App 实例方法: this.$on()
- Page 实例方法: this.$app.$on()
- Component 实例方法: this.$app.$on()
单个当前页面内的事件监听：
- Page 实例方法: this.$on()
- Component 实例方法: this.$page.$on()

on(`type`, `handler`)

type: String 要侦听的事件名称
handler: Function 事件响应函数

注册事件监听

off(`type`, `handler`)

type: String 要取消的事件名称
handler: Function 其事件响应函数

取消事件侦听

emit(`type`, `...args`)

type: String 要取消的事件名称
...args: 传入事件响应函数的参数

触发事件

工具库 mp.utils

const {
    promiser,
    classNames,
    inlineStyles,
    urlString,
} = mp.utils;

promiser(`nativeMethod`)

nativeMethod: 原生小程序 API 方法
返回: 转换为 Promise 后的方法

将原生方法转换为 Promise 方法，其中 success 属性转换为 resolve、fail 属性转换为 reject

// 例子
const login = promiser(wx.login);
const res = await login();

classNames(`...`)

参数: 见 JedWatson/classnames
返回: class 字符串

类名属性连接工具，将数组、对象等形式 class 转换为字符串，详见 classnames

inlineStyles(`styleObject`)

styleObject: 对象形式 style
返回: style 字符串

样式属性连接工具，将对象形式 style 转换为行内字符串

urlString.stringify(`url`, `query`)

url: 基础 URL 字符串
query: 查询值参数对象，支持复杂 JSON 对象
返回: 完整字符串形式 URL

拼接页面地址工具，将 URL 与查询值参数信息拼接

urlString.parse(`urlstring`)

urlstring: 字符串形式 URL
返回: 解析后包含 url query 的对象

解析页面地址工具，将字符串形式 URL 转换为对象形式

工具库中内置的第三方工具：

mitt

事件管理器，即 mitt

urlString.qs

URL querystring 查询值解析工具，即 qs

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.vscode		.vscode
bin		bin
dist		dist
lib		lib
templates		templates
test		test
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
README.md		README.md
package.json		package.json
rollup.config.js		rollup.config.js

cong-min/mp-helper

Folders and files

Latest commit

History

Repository files navigation

微信小程序轻量型开发助手/增强类库

特性

特点

TODO

快速上手

配置 CLI

引入类库 Core

.mp 单文件

显示高亮

模板

例子

语法

解析编译

增强 API

mp.App(options)

构造属性 $store

mp.Page(options)

构造属性 $context

mp.Component(options)

构造属性 $computed

路由

事件监听

on(type, handler)

off(type, handler)

emit(type, ...args)

工具库 mp.utils

promiser(nativeMethod)

classNames(...)

inlineStyles(styleObject)

urlString.stringify(url, query)

urlString.parse(urlstring)

mitt

urlString.qs

About

Topics

Resources

Stars

Watchers

Forks

Releases 17

Packages 0

Languages