lark 飞书小程序的 MobX 绑定辅助库

小程序的 MobX 绑定辅助库。

此 behavior 依赖开发者工具的 npm 构建。具体详情可查阅 官方 npm 文档 。

可配合 MobX 的小程序构建版 npm 模块 mobx-miniprogram 使用。

使用方法

需要小程序基础库版本 >= 1.0.0.598 的环境。

1. 安装 mobx-miniprogram 和 npm i mobx-lark-miniprogram-bindings ：

1npm install --save mobx-miniprogram npm i mobx-lark-miniprogram-bindings

2. 创建 MobX Store。

1// store.js
2import { observable, action } from "mobx-miniprogram";
3
4export const store = observable({
5	// 数据字段
6	numA: 1,
7	numB: 2,
8
9	// 计算属性
10	get sum() {
11		return this.numA + this.numB;
12	},
13
14	// actions
15	update: action(function () {
16		const sum = this.sum;
17		this.numA = this.numB;
18		this.numB = sum;
19	}),
20});

3. 在 Component 构造器中使用：

1import { storeBindingsBehavior } from "npm i mobx-lark-miniprogram-bindings";
2import { store } from "./store";
3
4Component({
5	behaviors: [storeBindingsBehavior],
6	data: {
7		someData: "...",
8	},
9	storeBindings: {
10		store,
11		fields: {
12			numA: () => store.numA,
13			numB: store => store.numB,
14			sum: "sum",
15		},
16		actions: {
17			buttonTap: "update",
18		},
19	},
20	methods: {
21		myMethod() {
22			this.data.sum; // 来自于 MobX store 的字段
23		},
24	},
25});

4. 在 Page 构造器中使用：

如果小程序基础库版本在 2.9.2 以上，可以直接像上面 Component 构造器那样引入 behaviors 。

如果需要比较好的兼容性，可以使用下面这种方式（或者直接改用 Component 构造器来创建页面）。

1import { createStoreBindings } from "npm i mobx-lark-miniprogram-bindings";
2import { store } from "./store";
3
4Page({
5	data: {
6		someData: "...",
7	},
8	onLoad() {
9		this.storeBindings = createStoreBindings(this, {
10			store,
11			fields: ["numA", "numB", "sum"],
12			actions: ["update"],
13		});
14	},
15	onUnload() {
16		this.storeBindings.destroyStoreBindings();
17	},
18	myMethod() {
19		this.data.sum; // 来自于 MobX store 的字段
20	},
21});

Typescript 支持

从 2.1.2 版本开始提供了简单的 TypeScript 支持。

新增两个构造器 API，推荐优先使用下列新版接口，你也可以继续使用旧版接口，详见接口说明。

ComponentWithStore

1import { ComponentWithStore } from "mobx-miniprogram-binding";
2ComponentWithStore({
3	options: {
4		styleIsolation: "shared",
5	},
6	data: {
7		someData: "...",
8	},
9	storeBindings: {
10		store,
11		fields: ["numA", "numB", "sum"],
12		actions: {
13			buttonTap: "update",
14		},
15	},
16});

BehaviorWithStore

1import { BehaviorWithStore } from "mobx-miniprogram-binding";
2export const testBehavior = BehaviorWithStore({
3	storeBindings: {
4		store,
5		fields: ["numA", "numB", "sum"],
6		actions: ["update"],
7	},
8});

接口

将页面、自定义组件和 store 绑定有两种方式： behavior 绑定 和 手工绑定 。

behavior 绑定

behavior 绑定 适用于 Component 构造器。做法：使用 storeBindingsBehavior 这个 behavior 和 storeBindings 定义段。

注意：你可以用 Component 构造器构造页面， 参考文档 。

1import { storeBindingsBehavior } from "npm i mobx-lark-miniprogram-bindings";
2Component({
3	behaviors: [storeBindingsBehavior],
4	storeBindings: {
5		/* 绑定配置（见下文） */
6	},
7});

也可以把 storeBindings 设置为一个数组，这样可以同时绑定多个 store ：

1import { storeBindingsBehavior } from "npm i mobx-lark-miniprogram-bindings";
2Component({
3	behaviors: [storeBindingsBehavior],
4	storeBindings: [
5		{
6			/* 绑定配置 1 */
7		},
8		{
9			/* 绑定配置 2 */
10		},
11	],
12});

手工绑定

手工绑定 适用于全部场景。做法：使用 createStoreBindings 创建绑定，它会返回一个包含清理函数的对象用于取消绑定。

注意：在页面 onUnload （自定义组件 detached ）时一定要调用清理函数，否则将导致内存泄漏！

1import { createStoreBindings } from "npm i mobx-lark-miniprogram-bindings";
2
3Page({
4	onLoad() {
5		this.storeBindings = createStoreBindings(this, {
6			/* 绑定配置（见下文） */
7		});
8	},
9	onUnload() {
10		this.storeBindings.destroyStoreBindings();
11	},
12});

绑定配置

无论使用哪种绑定方式，都必须提供一个绑定配置对象。这个对象包含的字段如下：

字段名	类型	含义
store	一个 MobX observable	默认的 MobX store
fields	数组或者对象	用于指定需要绑定的 data 字段
actions	数组或者对象	用于指定需要映射的 actions

fields

fields 有三种形式：

• 数组形式：指定 data 中哪些字段来源于 store 。例如 ['numA', 'numB', 'sum'] 。
• 映射形式：指定 data 中哪些字段来源于 store 以及它们在 store 中对应的名字。例如 { a: 'numA', b: 'numB' } ，此时 this.data.a === store.numA this.data.b === store.numB 。
• 函数形式：指定 data 中每个字段的计算方法。例如 { a: () => store.numA, b: () => anotherStore.numB } ，此时 this.data.a === store.numA this.data.b === anotherStore.numB 。

上述三种形式中，映射形式和函数形式可以在一个配置中同时使用。

如果仅使用了函数形式，那么 store 字段可以为空，否则 store 字段必填。

actions

actions 可以用于将 store 中的一些 actions 放入页面或自定义组件的 this 下，来方便触发一些 actions 。有两种形式：

• 数组形式：例如 ['update'] ，此时 this.update === store.update 。
• 映射形式：例如 { buttonTap: 'update' } ，此时 this.buttonTap === store.update 。

只要 actions 不为空，则 store 字段必填。

注意事项

延迟更新与立刻更新

为了提升性能，在 store 中的字段被更新后，并不会立刻同步更新到 this.data 上，而是等到下个 wx.nextTick 调用时才更新。（这样可以显著减少 setData 的调用次数。）

如果需要立刻更新，可以调用：

• this.updateStoreBindings() （在 behavior 绑定 中）
• this.storeBindings.updateStoreBindings() （在 手工绑定 中）

与 miniprogram-computed 一起使用

与 miniprogram-computed 时，在 behaviors 列表中 computedBehavior 必须在后面：

1Component({
2	behaviors: [storeBindingsBehavior, computedBehavior],
3	/* ... */
4});

关于部分更新

如果只是更新对象中的一部分（子字段），是不会引发界面变化的！例如：

1Component({
2	behaviors: [storeBindingsBehavior],
3	storeBindings: {
4		store,
5		fields: ["someObject"],
6	},
7});

如果尝试在 store 中：

1this.someObject.someField = "xxx";

这样是不会触发界面更新的。请考虑改成：

1this.someObject = Object.assign({}, this.someObject, { someField: "xxx" });