mobx-miniprogram-bindings

By default, updates to store fields are deferred until the next wx.nextTick to optimize performance and reduce setData calls. If you need the update to be applied to this.data immediately, call:

• In behavior binding: this.updateStoreBindings()
• In manual binding: this.storeBindings.updateStoreBindings()

To use this library, you must install both mobx-miniprogram and mobx-miniprogram-bindings. This requires a WeChat Mini Program base library version >= 2.11.0 and requires npm build in the WeChat DevTools.

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

The most common way to bind a store to a Component is using storeBindingsBehavior. This automatically handles the lifecycle of the binding. You can provide a single configuration object or an array of objects to bind multiple stores.

import { storeBindingsBehavior } from 'mobx-miniprogram-bindings'
import { store } from './store'

export default Component({
  behaviors: [storeBindingsBehavior],
  storeBindings: {
    store,
    fields: {
      numA: () => store.numA,
      numB: (store) => store.numB,
      sum: 'sum',
    },
    actions: {
      buttonTap: 'update',
    },
  },
  methods: {
    myMethod() {
      this.data.sum // Accesses field from MobX store
    },
  },
})

For better type inference in TypeScript, use ComponentWithStore or BehaviorWithStore.

Requirements for correct typing:

1. When using ComponentWithStore, do not include storeBindingsBehavior in the behaviors array.
2. Append as const to the end of fields and actions definitions.
3. If storeBindings is an array, append as const to the array itself.

Note: These interfaces depend on miniprogram-api-typings ^4.0.0.

import { ComponentWithStore } from 'mobx-miniprogram-bindings'

export default ComponentWithStore({
  data: {
    someData: '...',
  },
  storeBindings: {
    store,
    fields: ['numA', 'numB', 'sum'] as const,
    actions: {
      buttonTap: 'update',
    } as const,
  },
})

The examples in this repository can be run in both WeChat Mini Programs and web browsers. When running in a browser, the examples rely on glass-easel.

To run an example in your browser, navigate to the specific example directory and follow these steps:

1. Install dependencies using npm install.
2. Build the project using npm run build to generate the web version.
3. Open dist/index.html directly in your browser to view the result.

npm install
npm run build
# Then open dist/index.html in your browser

Since Page constructors do not support behaviors, you must use createStoreBindings manually.

CRITICAL: You must call the returned destroyStoreBindings() method in the onUnload (for Pages) or detached (for Components) lifecycle hook to prevent memory leaks.

import { createStoreBindings } from 'mobx-miniprogram-bindings'

Page({
  onLoad() {
    // Initialize binding
    this.storeBindings = createStoreBindings(this, {
      store,
      fields: ['numA', 'numB'],
    })
  },
  onUnload() {
    // Clean up to prevent memory leaks
    this.storeBindings.destroyStoreBindings()
  },
})

Updating a sub-field of an object in the store (e.g., this.someObject.someField = 'xxx') will not trigger a UI update in the component.

To ensure the UI updates, you must replace the object entirely using Object.assign or similar methods:

// Correct way to trigger update
this.someObject = Object.assign({}, this.someObject, { someField: 'xxx' })

When using the glass-easel Chaining API, use initStoreBindings for a more ergonomic experience within the .init() block.

import { initStoreBindings } from 'mobx-miniprogram-bindings'

export default Component()
  .init((ctx) => {
    const { listener } = ctx
    initStoreBindings(ctx, {
      store,
      fields: ['numA', 'numB', 'sum'],
    })
    const buttonTap = listener(() => {
      store.update()
    })
    return { buttonTap }
  })
  .register()

The binding configuration object requires the following fields:

fields formats:

• Array: ['numA', 'numB'] (Directly maps store property names to this.data).
• Mapping: { a: 'numA' } (Maps store.numA to this.data.a).
• Function: { a: () => store.numA } (Custom calculation for the field).

actions formats:

• Array: ['update'] (Maps store.update to this.update).
• Mapping: { buttonTap: 'update' } (Maps store.update to this.buttonTap).

Use BehaviorWithStore to create a WeChat Mini Program behavior that can be shared across multiple components to provide MobX store bindings. Similar to ComponentWithStore, it handles the injection of store data and actions and supports multiple store bindings via an array.

import { BehaviorWithStore } from 'mobx-miniprogram-bindings';

const myBehavior = BehaviorWithStore({
  storeBindings: [
    { store: storeA, fields: ['field1'] },
    { store: storeB, actions: ['action1'] }
  ],
  properties: {
    // behavior properties
  }
});

For environments using the Glass Easel engine, use initStoreBindings to set up bindings within the component lifecycle. It returns an object containing updateStoreBindings to manually trigger updates.

It automatically handles the attached and detached lifecycles: creating the bindings on attached and destroying them on detached.

import { initStoreBindings } from 'mobx-miniprogram-bindings';

// Inside a Glass Easel context
const bindings = initStoreBindings(ctx, {
  store: myStore,
  fields: ['field1']
});

// Manually trigger an update if needed
bindings.updateStoreBindings();