Information Density: Vuex – Signal Evidence & AI Readability

[H1] What is Vuex? #
Pinia is now the new defaultThe official state management library for Vue has changed to Pinia. Pinia has almost the exact same or enhanced API as Vuex 5, described in Vuex 5 RFC. You could simply consider Pinia as Vuex 5 with a different name. Pinia also works with Vue 2.x as well.Vuex 3 and 4 will still be maintained. However, it's unlikely to add new functionalities to it. Vuex and Pinia can be installed in the same project. If you're migrating existing Vuex app to Pinia, it might be a suitable option. However, if you're planning to start a new project, we highly recommend using Pinia instead.Vuex is a state management pattern + library for Vue.js applications. It serves as a centralized store for all the components in an application, with rules ensuring that the state can only be mutated in a predictable fashion.
[H2] What is a "State Management Pattern"? #
Let's start with a simple Vue counter app:const Counter = {
// state
data () {
return {
count: 0
}
},
// view
template: `
<div>{{ count }}</div>
`,
// actions
methods: {
increment () {
this.count++
}
}
}
createApp(Counter).mount('#app')
It is a self-contained app with the following parts:The state, the source of truth that drives our app;The view, a declarative mapping of the state;The actions, the possible ways the state could change in reaction to user inputs from the view.This is a simple representation of the concept of "one-way data flow":However, the simplicity quickly breaks down when we have multiple components that share a common state:Multiple views may depend on the same piece of state.Actions from different views may need to mutate the same piece of state.For problem one, passing props can be tedious for deeply nested components, and simply doesn't work for sibling components. For problem two, we often find ourselves resorting to solutions such as reaching for direct parent/child instance references or trying to mutate and synchronize multiple copies of the state via events. Both of these patterns are brittle and quickly lead to unmaintainable code.So why don't we extract the shared state out of the components, and manage it in a global singleton? With this, our component tree becomes a big "view", and any component can access the state or trigger actions, no matter where they are in the tree!By defining and separating the concepts involved in state management and enforcing rules that maintain independence between views and states, we give our code more structure and maintainability.This is the basic idea behind Vuex, inspired by Flux, Redux and The Elm Architecture. Unlike the other patterns, Vuex is also a library implementation tailored specifically for Vue.js to take advantage of its granular reactivity system for efficient updates.If you want to learn Vuex in an interactive way you can check out this Vuex course on Scrimba, which gives you a mix of screencast and code playground that you can pause and play around with anytime.
[IMG: vuex]
[H2] When Should I Use It? #
Vuex helps us deal with shared state management with the cost of more concepts and boilerplate. It's a trade-off between short term and long term productivity.If you've never built a large-scale SPA and jump right into Vuex, it may feel verbose and daunting. That's perfectly normal - if your app is simple, you will most likely be fine without Vuex. A simple store pattern may be all you need. But if you are building a medium-to-large-scale SPA, chances are you have run into situations that make you think about how to better handle state outside of your Vue components, and Vuex will be the natural next step for you. There's a good quote from Dan Abramov, the author of Redux:Flux libraries are like glasses: you’ll know when you need them.Installation

[H1] Getting Started #
Try this lesson on ScrimbaAt the center of every Vuex application is the store. A "store" is basically a container that holds your application state. There are two things that make a Vuex store different from a plain global object:Vuex stores are reactive. When Vue components retrieve state from it, they will reactively and efficiently update if the store's state changes.You cannot directly mutate the store's state. The only way to change a store's state is by explicitly committing mutations. This ensures every state change leaves a track-able record, and enables tooling that helps us better understand our applications.
[H2] The Simplest Store #
NOTEWe will be using ES2015 syntax for code examples for the rest of the docs. If you haven't picked it up, you should!After installing Vuex, let's create a store. It is pretty straightforward - just provide an initial state object, and some mutations:import { createApp } from 'vue'
import { createStore } from 'vuex'
// Create a new store instance.
const store = createStore({
state () {
return {
count: 0
}
},
mutations: {
increment (state) {
state.count++
}
}
})
const app = createApp({ /* your root component */ })
// Install the store instance as a plugin
app.use(store)
Now, you can access the state object as store.state, and trigger a state change with the store.commit method:store.commit('increment')

[H1] API Reference #
[H2] Store #
[H3] createStore #
createStore<S>(options: StoreOptions<S>): Store<S>Creates a new store.import { createStore } from 'vuex'
const store = createStore({ ...options })
[H2] Store Constructor Options #
[H3] state #
type: Object | FunctionThe root state object for the Vuex store. DetailsIf you pass a function that returns an object, the returned object is used as the root state. This is useful when you want to reuse the state object especially for module reuse. Details
[H3] mutations #
type: { [type: string]: Function }Register mutations on the store. The handler function always receives state as the first argument (will be module local state if defined in a module), and receives a second payload argument if there is one.Details
[H3] actions #
type: { [type: string]: Function }Register actions on the store. The handler function receives a context object that exposes the following properties:{
state, // same as `store.state`, or local state if in modules
rootState, // same as `store.state`, only in modules
commit, // same as `store.commit`
dispatch, // same as `store.dispatch`
getters, // same as `store.getters`, or local getters if in modules
rootGetters // same as `store.getters`, only in modules
}
And also receives a second payload argument if there is one.Details
[H3] getters #
type: { [key: string]: Function }Register getters on the store. The getter function receives the following arguments:state, // will be module local state if defined in a module.
getters // same as store.getters
Specific when defined in a modulestate, // will be module local state if defined in a module.
getters, // module local getters of the current module
rootState, // global state
rootGetters // all getters
Registered getters are exposed on store.getters.Details
[H3] modules #
type: ObjectAn object containing sub modules to be merged into the store, in the shape of:{
key: {
state,
namespaced?,
mutations?,
actions?,
getters?,
modules?
},
...
}
Each module can contain state and mutations similar to the root options. A module's state will be attached to the store's root state using the module's key. A module's mutations and getters will only receives the module's local state as the first argument instead of the root state, and module actions' context.state will also point to the local state.Details
[H3] plugins #
type: Array<Function>An array of plugin functions to be applied to the store. The plugin simply receives the store as the only argument and can either listen to mutations (for outbound data persistence, logging, or debugging) or dispatch mutations (for inbound data e.g. websockets or observables).Details
[H3] strict #
type: booleandefault: falseForce the Vuex store into strict mode. In strict mode any mutations to Vuex state outside of mutation handlers will throw an Error.Details
[H3] devtools #
type: booleanTurn the devtools on or off for a particular Vuex instance. For instance, passing false tells the Vuex store to not subscribe to devtools plugin. Useful when you have multiple stores on a single page.{
devtools: false
}
[H2] Store Instance Properties #
[H3] state #
type: ObjectThe root state. Read only.
[H3] getters #
type: ObjectExposes registered getters. Read only.
[H2] Store Instance Methods #
[H3] commit #
commit(type: string, payload?: any, options?: Object)commit(mutation: Object, options?: Object)Commit a mutation. options can have root: true that allows to commit root mutations in namespaced modules. Details
[H3] dispatch #
dispatch(type: string, payload?: any, options?: Object): Promise<any>dispatch(action: Object, options?: Object): Promise<any>Dispatch an action. options can have root: true that allows to dispatch root actions in namespaced modules. Returns a Promise that resolves all triggered action handlers. Details
[H3] replaceState #
replaceState(state: Object)Replace the store's root state. Use this only for state hydration / time-travel purposes.
[H3] watch #
watch(fn: Function, callback: Function, options?: Object): FunctionReactively watch fn's return value, and call the callback when the value changes. fn receives the store's state as the first argument, and getters as the second argument. Accepts an optional options object that takes the same options as Vue's vm.$watch method.To stop watching, call the returned unwatch function.
[H3] subscribe #
subscribe(handler: Function, options?: Object): FunctionSubscribe to store mutations. The handler is called after every mutation and receives the mutation descriptor and post-mutation state as arguments.const unsubscribe = store.subscribe((mutation, state) => {
console.log(mutation.type)
console.log(mutation.payload)
})
// you may call unsubscribe to stop the subscription
unsubscribe()
By default, new handler is added to the end of the chain, so it will be executed after other handlers that were added before. This can be overridden by adding prepend: true to options, which will add the handler to the beginning of the chain.store.subscribe(handler, { prepend: true })
The subscribe method will return an unsubscribe function, which should be called when the subscription is no longer needed. For example, you might subscribe to a Vuex Module and unsubscribe when you unregister the module. Or you might call subscribe from inside a Vue Component and then destroy the component later. In these cases, you should remember to unsubscribe the subscription manually.Most commonly used in plugins. Details
[H3] subscribeAction #
subscribeAction(handler: Function, options?: Object): FunctionSubscribe to store actions. The handler is called for every dispatched action and receives the action descriptor and current store state as arguments. The subscribe method will return an unsubscribe function, which should be called when the subscription is no longer needed. For example, when unregistering a Vuex module or before destroying a Vue component.const unsubscribe = store.subscribeAction((action, state) => {
console.log(action.type)
console.log(action.payload)
})
// you may call unsubscribe to stop the subscription
unsubscribe()
By default, new handler is added to the end of the chain, so it will be executed after other handlers that were added before. This can be overridden by adding prepend: true to options, which will add the handler to the beginning of the chain.store.subscribeAction(handler, { prepend: true })
The subscribeAction method will return an unsubscribe function, which should be called when the subscription is no longer needed. For example, you might subscribe to a Vuex Module and unsubscribe when you unregister the module. Or you might call subscribeAction from inside a Vue Component and then destroy the component later. In these cases, you should remember to unsubscribe the subscription manually.subscribeAction can also specify whether the subscribe handler should be called before or after an action dispatch (the default behavior is before):store.subscribeAction({
before: (action, state) => {
console.log(`before action ${action.type}`)
},
after: (action, state) => {
console.log(`after action ${action.type}`)
}
})
subscribeAction can also specify an error handler to catch an error thrown when an action is dispatched. The function will receive an error object as the third argument.store.subscribeAction({
error: (action, state, error) => {
console.log(`error action ${action.type}`)
console.error(error)
}
})
The subscribeAction method is most commonly used in plugins. Details
[H3] registerModule #
registerModule(path: string | Array<string>, module: Module, options?: Object)Register a dynamic module. Detailsoptions can have preserveState: true that allows to preserve the previous state. Useful with Server Side Rendering.
[H3] unregisterModule #
unregisterModule(path: string | Array<string>)Unregister a dynamic module. Details
[H3] hasModule #
hasModule(path: string | Array<string>): booleanCheck if the module with the given name is already registered. Details
[H3] hotUpdate #
hotUpdate(newOptions: Object)Hot swap new actions and mutations. Details
[H2] Component Binding Helpers #
[H3] mapState #
mapState(namespace?: string, map: Array<string> | Object<string | function>): ObjectCreate component computed options that return the sub tree of the Vuex store. DetailsThe first argument can optionally be a namespace string. DetailsThe second object argument's members can be a function.

[H1] Vuex 是什么？ #
提示这是与 Vue 3 匹配的 Vuex 4 的文档。如果您在找与 Vue 2 匹配的 Vuex 3 的文档，请在这里查看。Vuex 是一个专为 Vue.js 应用程序开发的状态管理模式 + 库。它采用集中式存储管理应用的所有组件的状态，并以相应的规则保证状态以一种可预测的方式发生变化。
[H2] 什么是“状态管理模式”？ #
让我们从一个简单的 Vue 计数应用开始：const Counter = {
// 状态
data () {
return {
count: 0
}
},
// 视图
template: `
<div>{{ count }}</div>
`,
// 操作
methods: {
increment () {
this.count++
}
}
}
createApp(Counter).mount('#app')
这个状态自管理应用包含以下几个部分：状态，驱动应用的数据源；视图，以声明方式将状态映射到视图；操作，响应在视图上的用户输入导致的状态变化。以下是一个表示“单向数据流”理念的简单示意：但是，当我们的应用遇到多个组件共享状态时，单向数据流的简洁性很容易被破坏：多个视图依赖于同一状态。来自不同视图的行为需要变更同一状态。对于问题一，传参的方法对于多层嵌套的组件将会非常繁琐，并且对于兄弟组件间的状态传递无能为力。对于问题二，我们经常会采用父子组件直接引用或者通过事件来变更和同步状态的多份拷贝。以上的这些模式非常脆弱，通常会导致无法维护的代码。因此，我们为什么不把组件的共享状态抽取出来，以一个全局单例模式管理呢？在这种模式下，我们的组件树构成了一个巨大的“视图”，不管在树的哪个位置，任何组件都能获取状态或者触发行为！通过定义和隔离状态管理中的各种概念并通过强制规则维持视图和状态间的独立性，我们的代码将会变得更结构化且易维护。这就是 Vuex 背后的基本思想，借鉴了 Flux、Redux 和 The Elm Architecture。与其他模式不同的是，Vuex 是专门为 Vue.js 设计的状态管理库，以利用 Vue.js 的细粒度数据响应机制来进行高效的状态更新。如果你想交互式地学习 Vuex，可以看这个 Scrimba 上的 Vuex 课程，它将录屏和代码试验场混合在了一起，你可以随时暂停并尝试。
[IMG: vuex]
[H2] 什么情况下我应该使用 Vuex？ #
Vuex 可以帮助我们管理共享状态，并附带了更多的概念和框架。这需要对短期和长期效益进行权衡。如果您不打算开发大型单页应用，使用 Vuex 可能是繁琐冗余的。确实是如此——如果您的应用够简单，您最好不要使用 Vuex。一个简单的 store 模式就足够您所需了。但是，如果您需要构建一个中大型单页应用，您很可能会考虑如何更好地在组件外部管理状态，Vuex 将会成为自然而然的选择。引用 Redux 的作者 Dan Abramov 的话说就是：Flux 架构就像眼镜：您自会知道什么时候需要它。安装