▶_MiniApp Toolkit

mobx-miniprogram-bindings

工具活跃维护

微信官方小程序 MobX 状态管理绑定库。提供 storeBindingsBehavior 和 createStoreBindings 两种绑定方式，自动将 MobX Store 数据同步到组件/页面，支持计算属性、actions、多 store 绑定。原生支持 TypeScript 和 glass-easel Chaining API。

★ 249🕒 最近更新 2026-07
官网文档
状态管理MobX微信小程序官方库TypeScript

特性

  • MobX Store 与小程序组件/页面自动绑定
  • storeBindingsBehavior（Component behavior 模式）
  • createStoreBindings（手工绑定，适用于 Page）
  • 多 store 同时绑定
  • TypeScript 类型支持（ComponentWithStore / BehaviorWithStore）
  • glass-easel Chaining API 支持（initStoreBindings）
  • 计算属性自动更新
  • npm 包mobx-miniprogram 依赖

详细文档

mobx-miniprogram-bindings#

资源概述#

mobx-miniprogram-bindings 是微信官方（wechat-miniprogram 组织）出品的 MobX 状态管理绑定辅助库，专门为微信小程序设计。它解决了小程序原生开发中状态管理松散、跨组件数据同步困难的问题。

核心价值：将 MobX 的响应式状态管理能力引入小程序，自动将 Store 数据同步到 Component/Page 的 data 中，开发者无需手动 setData。

关键数据：

  • GitHub：249 stars / 24 forks / MIT License
  • npm 包：mobx-miniprogram-bindings v6.0.0（最新）
  • 维护状态：官方团队维护，2026-06-17 最近提交
  • 依赖：mobx-miniprogram（peer dependency）
  • 基础库要求：>= 2.11.0

设计规范#

架构模式#

采用 MobX 经典的 Store-Binding 模式：

  • Store：使用 observable 和 action 定义可观察数据和修改函数
  • Binding：通过 storeBindingsBehavior（Component）或 createStoreBindings（Page）自动绑定
  • 自动更新：Store 数据变化时自动触发 setData，无需手动管理

两种绑定方式#

方式适用场景特点
storeBindingsBehaviorComponentbehavior 注入，声明式绑定
createStoreBindingsPage / 动态 store手工创建，需在 onUnload 清理

审核规范#

本库为 npm 开发依赖，无需平台审核。使用时需确保小程序项目已开启 npm 构建（开发者工具 → 详情 → 本地设置 → 使用 npm 模块）。

开发指南#

快速上手#

code
npm install --save mobx-miniprogram mobx-miniprogram-bindings
code
// store.js — 创建 MobX Store
import { observable, action } from 'mobx-miniprogram'

export const store = observable({
  numA: 1,
  numB: 2,
  get sum() { return this.numA + this.numB },
  update: action(function () {
    const sum = this.sum
    this.numA = this.numB
    this.numB = sum
  })
})
code
// component.js — Component 中使用（behavior 模式）
import { storeBindingsBehavior } from 'mobx-miniprogram-bindings'
import { store } from './store'

Component({
  behaviors: [storeBindingsBehavior],
  storeBindings: {
    store,
    fields: {
      numA: () => store.numA,
      numB: (store) => store.numB,
      sum: 'sum',
    },
    actions: {
      buttonTap: 'update',
    },
  },
  methods: {
    myMethod() {
      this.data.sum // 来自 MobX store
    },
  },
})
code
// page.js — Page 中使用（手工绑定模式）
import { createStoreBindings } from 'mobx-miniprogram-bindings'
import { store } from './store'

Page({
  onLoad() {
    this.storeBindings = createStoreBindings(this, {
      store,
      fields: ['numA', 'numB', 'sum'],
      actions: { buttonTap: 'update' },
    })
  },
  onUnload() {
    this.storeBindings.destroyStoreBindings() // 必须清理！
  },
})

TypeScript 用法#

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

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

glass-easel Chaining API#

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

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

常见陷阱#

  1. Page 必须手工绑定：storeBindingsBehavior 只能用于 Component，Page 需用 createStoreBindings
  2. 内存泄漏：手工绑定时必须在 onUnload / detached 中调用 destroyStoreBindings()
  3. 基础库要求：>= 2.11.0，低版本不支持
  4. npm 构建必须开启：未开启 npm 构建会导致 require 失败
  5. TypeScript 版本匹配：TS 接口依赖 miniprogram-api-typings ^4.0.0，老版本请用 v3/v4

生态资源#

配套库#

库说明
mobx-miniprogramMobX 核心库的小程序版本（peer dependency）
miniprogram-api-typings小程序 TypeScript 类型定义

适用场景#

  • 中大型小程序项目，组件间共享状态多
  • 需要计算属性和响应式更新的复杂业务逻辑
  • 从 React/MobX 技术栈迁移到小程序的团队
  • 替代简单的 globalData / 页面间传参方案

与其他状态管理方案对比#

方案优点缺点
mobx-miniprogram-bindings官方维护，MobX 生态，TypeScript 支持需学习 MobX 概念
westore腾讯出品，deepClone + dataDiff仅支持 Model 层，无计算属性
原生 globalData零依赖无响应式，手动 setData
eventBus / pub-sub灵活无状态管理，易混乱

版本更新#

当前版本（核实日期：2026-07-20）#

  • npm 最新：mobx-miniprogram-bindings v6.0.0
  • 主要变更：glass-easel Chaining API 支持（initStoreBindings）、TypeScript 类型增强（ComponentWithStore / BehaviorWithStore）
  • 基础库要求：>= 2.11.0
  • 最近提交：2026-06-17（持续维护中）

版本里程碑#

  • v6.x：glass-easel 支持、TS 接口增强
  • v5.x：TypeScript 完整类型支持
  • v4.x / v3.x：兼容老版本 miniprogram-api-typings