小程序的 MobX 绑定辅助库

小程序的 MobX 绑定辅助库。

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

使用方法

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

具体的示例完整代码，可以参考 examples 。

1. 安装 mobx-miniprogram 和 mobx-miniprogram-bindings ：

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

2. 创建 MobX Store。

1// store.js
2import { observable, action } from 'mobx-miniprogram'
3
4// 创建 store 时可以采用任何 mobx 的接口风格
5// 这里以传统的 observable 风格为例
6
7export const store = observable({
8  // 数据字段
9  numA: 1,
10  numB: 2,
11
12  // 计算属性
13  get sum() {
14    return this.numA + this.numB
15  },
16
17  // actions
18  update: action(function () {
19    const sum = this.sum
20    this.numA = this.numB
21    this.numB = sum
22  }),
23})

3. 在 Page 或 Component 构造器中使用：

1import { storeBindingsBehavior } from 'mobx-miniprogram-bindings'
2import { store } from './store'
3
4Component({
5  behaviors: [storeBindingsBehavior], // 添加这个 behavior
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})

TypeScript 接口

在 TypeScript 下，可以使用 ComponentWithStore 接口。它会自动处理一些类型问题。注意：

• 使用这个接口时，不要在 behaviors 中额外引入 storeBindingsBehavior ；
• fields 和 actions 末尾需要加上 as const 以便更好的类型推导；
• storeBindings 如果是一个数组，也要在数组后加上 as const 。

1import { ComponentWithStore } from 'mobx-miniprogram-bindings'
2
3ComponentWithStore({
4  data: {
5    someData: '...',
6  },
7  storeBindings: {
8    store,
9    fields: ['numA', 'numB', 'sum'] as const,
10    actions: {
11      buttonTap: 'update',
12    } as const,
13  },
14})

BehaviorWithStore 接口类似。

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

目前 TypeScript 接口定义依赖于 miniprogram-api-typings ^4.0.0 。 （如使用老版本的 api-typings ，请使用本项目的 v4 或 v3 版本。）

glass-easel Chaining API 接口

使用 glass-easel Chaining API 时，使用 initStoreBindings 更友好。

1import { initStoreBindings } from 'mobx-miniprogram-bindings'
2
3Component()
4  .init((ctx) => {
5    const { listener } = ctx
6    initStoreBindings(ctx, {
7      store,
8      fields: ['numA', 'numB', 'sum'],
9    })
10    const buttonTap = listener(() => {
11      store.update()
12    })
13    return { buttonTap }
14  })
15  .register()

具体接口说明

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

behavior 绑定

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

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

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

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

手工绑定

手工绑定 更加灵活，适用于 store 需要在 onLoad （自定义组件 attached ）时才能确定的情况。

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

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

1import { createStoreBindings } from 'mobx-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' })