企业官网建设流程全解析

Vuex 4 State 状态管理：单一状态树、响应式获取与 mapState 辅助函数实战指南

【免费下载链接】vuex🗃️ Centralized State Management for Vue.js.项目地址: https://gitcode.com/gh_mirrors/vu/vuex

导读

本文以 Vuex 官方文档中「State（状态）」章节（docs/ptbr/guide/state.md）为核心，系统讲解 Vuex 4 状态管理的核心机制：**单一状态树（Single State Tree）**如何成为应用的"唯一数据源"、状态如何在 Vue 组件中响应式地被读取（store.state与this.$store.state两种方式）、以及mapState辅助函数与对象展开运算符如何大幅精简组件中的computed代码。同时，我们将结合本仓库（gh_mirrors/vu/vuex）的 源码实现、Store 核心类 与官方示例（examples/classic/counter）深入剖析其底层原理，帮助读者在掌握 API 用法的同时理解 Vuex 状态层的工作原理。

适用版本：本文所述代码基于本仓库 Vuex 4（面向 Vue 3），API 形式为createStore与app.use(store)；Vue 2 + Vuex 3 时代的new Vuex.Store()写法已不再适用。

单一状态树（Single State Tree）

什么是单一状态树

Vuex 使用单一状态树（single state tree）——即用一个单一对象包含应用的全部"应用级状态"（application level state），并作为应用的**"唯一数据源"（single source of truth）**。这意味着：

• 通常每个应用只有一个 store 实例；
• 单一状态树让定位某一块特定状态变得直接简单；
• 它允许我们对应用的当前状态轻松拍摄快照（snapshot），便于调试与时间旅行（time-travel debugging）。

原文档（docs/ptbr/guide/state.md）明确指出："Vuex usa umaúnica árvore de estado"（Vuex 使用单一状态树），这个单一对象承载应用全部状态。

单一状态树与模块化并不冲突

单一状态树不排斥模块化。在后续章节（见 docs/ptbr/guide/modules.md）中，Vuex 允许把状态（state）、变更（mutations）拆分为子模块（sub-modules），最终仍统一挂载到这一棵树上。从源码来看，Store 构造函数 内部通过ModuleCollection递归注册根模块与所有子模块（installModule(this, state, [], this._modules.root)），模块化只是对单一状态树的分层组织方式。

状态必须是"普通对象"

存入 Vuex 的数据遵循与 Vue 实例中data相同的规则：状态对象必须是"普通（plain）"对象，即不应包含如class实例、Date实例、Map/Set等非普通对象，或带特殊行为的响应式代理。这是因为 Vuex 的响应式机制（Vue 3 的reactive）会基于普通对象构建响应式系统，非普通对象可能导致响应式追踪失效或行为异常。

仓库中的真实示例

官方经典示例 examples/classic/counter/store.js 中，根状态就是一个普通对象：

// root state object. // each Vuex instance is just a single state tree. const state = { count: 0 }

而 examples/composition/counter/store.js 也提供了同样语义的写法。可以看到，一个 Vuex store 的根状态即"单一状态树"。

如何在 Vue 组件中获取 Vuex 状态

前提：Store 是响应式的

Vuex store 的响应性来自其底层实现。查看 Store 类：

get state () { return this._state.data }

而_state在 store-util.js 的 resetStoreState 中被定义为：

store._state = reactive({ data: state })

即用 Vue 3 的reactive()包裹整个状态树，使其成为响应式对象。因此，当状态变化时，任何读取它的 Vuecomputed属性都会自动重新求值并触发 DOM 更新。

方式一：在computed中直接返回store.state

既然 store 是响应式的，最简单的方式就是在**计算属性（computed property）**中直接返回store.state的某一部分：

// 创建一个 Counter 组件 const Counter = { template: `<div>{{ count }}</div>`, computed: { count () { return store.state.count } } }

只要store.state.count发生变化，count计算属性就会被重新求值，并触发关联的 DOM 更新。

方式二：通过this.$store访问（推荐）

直接在computed中引用store单例有一个问题：组件会依赖全局 store 单例。在使用模块系统（如 ES Modules）时，这意味着每个使用状态的组件都要手动import store；在单元测试时，还需要对 store 进行 mock，非常繁琐。

Vuex 通过 Vue 的插件系统，把 store注入到根组件之下的所有子组件，并挂载为this.$store。因此，组件的计算属性可以改写为：

const Counter = { template: `<div>{{ count }}</div>`, computed: { count () { return this.$store.state.count } } }

底层实现：install 注入

在 src/store.js 的 install 方法 中可以看到注入机制：

install (app, injectKey) { app.provide(injectKey || storeKey, this) app.config.globalProperties.$store = this // ... }

• 通过app.provide(injectKey || storeKey, this)将 store 通过 Vue 3 的Provide/Inject机制提供给整棵组件树；
• 通过app.config.globalProperties.$store = this将 store 挂载到全局属性上，从而组件内可用this.$store访问；
• 注入键storeKey定义在 src/injectKey.js（export const storeKey = 'store'）；
• 若要在 Composition API 中使用，可从 src/index.js 导出useStore()（基于inject实现，见 src/injectKey.js）。

官方示例 examples/classic/counter/app.js 演示了挂载方式：

import { createApp } from 'vue' import Counter from './Counter.vue' import store from './store' const app = createApp(Counter) app.use(store) app.mount('#app')

调用app.use(store)时，Vue 会调用store.install(app)，从而完成注入。示例组件 examples/classic/counter/Counter.vue 中正是直接使用{{ $store.state.count }}读取模板中的状态。

mapState 辅助函数

为什么需要 mapState

当组件需要多个store 状态属性（或 getters）时，逐一手写计算属性会变得重复且冗长。mapState辅助函数可以自动生成计算属性 getter 函数，为你节省大量样板代码。

在完整构建（full build）中，辅助函数通过Vuex.mapState暴露；通过打包工具按需引入时使用import { mapState } from 'vuex'。

基本用法：对象形式

mapState最典型的用法是传入一个对象，其键为组件内计算属性的名字，值为映射规则：

// 在完整构建中，辅助函数以 Vuex.mapState 暴露 import { mapState } from 'vuex' export default { // ... computed: mapState({ // 箭头函数可以让代码非常简洁！ count: state => state.count, // 传入字符串 'count' 等价于 `state => state.count` countAlias: 'count', // 为了在函数内部通过 `this` 访问组件局部状态，必须使用普通函数 countPlusLocalState (state) { return state.count + this.localCount } }) }

三种映射形式的语义：

基本用法：数组形式

当映射出的计算属性名与状态子树的键名完全一致时，可以传入一个字符串数组，代码更加精简：

computed: mapState([ // 将 this.count 映射为 store.state.count 'count' ])

这等价于computed: mapState({ count: 'count' })。

mapState 的源码级实现

在 src/helpers.js 的 mapState 定义 中可以看到其真实行为：

export const mapState = normalizeNamespace((namespace, states) => { const res = {} if (__DEV__ && !isValidMap(states)) { console.error('[vuex] mapState: mapper parameter must be either an Array or an Object') } normalizeMap(states).forEach(({ key, val }) => { res[key] = function mappedState () { let state = this.$store.state let getters = this.$store.getters if (namespace) { const module = getModuleByNamespace(this.$store, 'mapState', namespace) if (!module) { return } state = module.context.state getters = module.context.getters } return typeof val === 'function' ? val.call(this, state, getters) : state[val] } // mark vuex getter for devtools res[key].vuex = true }) return res })

几个关键细节：

1. normalizeMap统一处理入参：normalizeMap([1,2,3])会转为[{key:1,val:1},{key:2,val:2},{key:3,val:3}]，normalizeMap({a:1,b:2})会转为[{key:'a',val:1},{key:'b',val:2}]（见 helpers.js 的 normalizeMap）。这正是对象形式与数组形式都能工作的原因。
2. 生成的是普通函数：res[key]是一个mappedState函数，函数内部动态读取this.$store.state，因此它天然可以作为 Vue 组件computed的 getter 使用。
3. 函数形式会调用val.call(this, state, getters)：把组件实例this传入，因此普通函数内部可以访问this.localCount；同时把getters作为第二个参数传入，函数体内也可访问 getters。
4. 字符串形式直接取值：state[val]等价于state => state[val]。
5. res[key].vuex = true：为生成的 getter 打上标记，供 Vue Devtools 识别。
6. 参数合法性校验：在开发模式（__DEV__）下，若传入的既不是数组也不是对象，会输出错误[vuex] mapState: mapper parameter must be either an Array or an Object（对应测试见 test/unit/helpers.spec.js 中 "mapState (with undefined states)" 用例）。
7. 命名空间支持：mapState通过normalizeNamespace包装后，第一个参数可传入模块命名空间字符串（如'foo/'），内部通过getModuleByNamespace从store._modulesNamespaceMap查找模块，并将state/getters切换为模块上下文（module.context.state、module.context.getters）。这也是mapState('foo', {...})与createNamespacedHelpers('foo').mapState的实现基础（见 helpers.js 的 createNamespacedHelpers）。

官方测试用例印证

test/unit/helpers.spec.js 中有完整的验证用例：

• 数组形式：computed: mapState(['a'])，断言this.a与store.state.a相等；
• 对象形式：computed: mapState({ ... })，覆盖箭头函数、字符串别名、普通函数三种写法；
• 命名空间形式：mapState('foo', {...})以及嵌套模块mapState('foo', {...})；
• 非法参数：传入undefined时开发模式输出错误日志。

这些用例同时验证了store.state.count的响应式更新与 mutation 提交后状态变化的一致性（如expect(store.state.count).toBe(1)等断言）。

对象展开运算符（Object Spread Operator）组合局部计算属性

问题：mapState 返回的是对象

注意：mapState返回一个对象。如果组件本身还有自己的局部计算属性（local computed），直接写computed: mapState({...})会覆盖掉其他计算属性。传统的做法是借助工具函数手动合并多个对象，才能把最终对象传给computed。

解决方案：展开运算符

利用对象展开运算符（object spread operator），可以把mapState返回对象的成员"混入"外层对象，语法大大简化：

computed: { localComputed () { /* ... */ }, // 使用对象展开运算符把它混入外层对象 ...mapState({ // ... }) }

这样computed对象中既保留了localComputed等局部计算属性，又通过展开合并了mapState生成的映射 getter，二者互不冲突。这是官方文档（docs/ptbr/guide/state.md 的 "Objeto Spread Operator" 小节）推荐的组合方式，也是实际项目中最高频的写法。

该语法依赖 JavaScript 的对象剩余/展开特性（object rest/spread，TC39 提案），现代浏览器与主流打包工具均原生支持。

组件仍然可以拥有局部状态

不必把所有状态都放进 Vuex

使用 Vuex 并不意味着要把"所有"状态都放进 Vuex。文档（docs/ptbr/guide/state.md 的 "Componentes Ainda Podem Ter Um Estado Local" 小节）给出了清晰的权衡建议：

• 优点：把更多状态放进 Vuex，会让状态变更更显式（explicit）、更可调试（debuggable）；
• 缺点：有时也会让代码更冗长（verbose）、更间接（indirect）——比如只为单个组件内的一个临时值写 mutation。

决策准则：如果某块状态严格只属于单个组件（如组件内部的临时 UI 状态、表单草稿、下拉开关等），完全可以直接作为组件的局部状态（data/ref）保留，而不必进入 Vuex。开发者应当权衡利弊，依据应用的开发需求做决策。

这与官方对 store 职责的定位一致：Vuex store 负责"应用级状态"（application level state），组件私有的临时状态留在组件内部反而更简洁。结合源码结构看，this.$store.state是对整棵状态树的只读访问（直接赋值会被set state拦截并提示使用replaceState()，见 src/store.js#L95-L99），状态修改一律走 mutation/action，这正是 Vuex 状态管理"显式可追踪"的价值所在。

实践清单：从零接入 Vuex State

综合原文档与仓库示例，一个最小的完整接入流程如下：

1. 创建 store：定义一个普通对象形式的根状态，用createStore创建 store（参考 examples/classic/counter/store.js）：

   import { createStore } from 'vuex' const store = createStore({ state: { count: 0 } }) export default store

2. 注入应用：在应用入口通过app.use(store)注入（参考 examples/classic/counter/app.js），之后所有组件即可用this.$store/$store访问。

3. 读取状态：在组件computed中读取this.$store.state.xxx；若需多个状态，用mapState配合对象展开运算符合并：

   import { mapState } from 'vuex' export default { computed: { localComputed () { return 1 }, ...mapState(['count']) } }

4. 修改状态：修改必须通过 mutation（store.commit）与 action（store.dispatch），详见 docs/ptbr/guide/mutations.md 与 docs/ptbr/guide/actions.md，组件内可通过mapMutations/mapActions映射（示例见 examples/classic/counter/Counter.vue）。

5. 善用单一状态树：保持根状态为普通对象，善用模块化拆分（见 docs/ptbr/guide/modules.md），并把"严格属于单个组件"的临时状态留在组件内部。

小结

本文围绕 Vuex 4 的 State 主题，完整覆盖了官方文档（docs/ptbr/guide/state.md）的五大核心知识点，并结合仓库源码与示例进行了纵深验证：

掌握以上内容后，读者应能熟练地在 Vue 3 应用中搭建 Vuex 状态层、在组件中高效且规范地读取状态，并为后续学习 mutations、getters、modules 打下坚实基础（可继续阅读 docs/ptbr/guide/index.md 及 docs/ptbr/guide/mutations.md、docs/ptbr/guide/getters.md 等章节）。

【免费下载链接】vuex🗃️ Centralized State Management for Vue.js.项目地址: https://gitcode.com/gh_mirrors/vu/vuex