使用說明-Vuex
安裝
直接下載 / CDN 引用
Unpkg.com 提供了基于 NPM 的 CDN 鏈接。以上的鏈接會一直指向 NPM 上發布的最新版本。您也可以通過 https://unpkg.com/vuex@2.0.0
這樣的方式指定特定的版本。
在 Vue 之后引入 vuex 會進行自動安裝:
<script src="/path/to/vue.js"></script>
<script src="/path/to/vuex.js"></script>
NPM
npm install vuex --save
Yarn
yarn add vuex
在一個模塊化的打包系統中,您必須顯式地通過 Vue.use()
來安裝 Vuex:
import Vue from 'vue'
import Vuex from 'vuex'
Vue.use(Vuex)
當使用全局 script 標簽引用 Vuex 時,不需要以上安裝過程。
Promise
Vuex 依賴 Promise。如果你支持的瀏覽器并沒有實現 Promise (比如 IE),那么你可以使用一個 polyfill 的庫,例如 es6-promise。
你可以通過 CDN 將其引入:
<script src="https://cdn.jsdelivr.net/npm/es6-promise@4/dist/es6-promise.auto.js"></script>
然后 window.Promise
會自動可用。
如果你喜歡使用諸如 npm
或 Yarn
等包管理器,可以按照下列方式執行安裝:
npm install es6-promise --save # npm
yarn add es6-promise # Yarn
或者更進一步,將下列代碼添加到你使用 Vuex 之前的一個地方:
import 'es6-promise/auto'
自己構建
如果需要使用 dev 分支下的最新版本,您可以直接從 GitHub 上克隆代碼并自己構建。
git clone https://github.com/vuejs/vuex.git node_modules/vuex
cd node_modules/vuex
npm install
npm run build
Vuex是什么?
Vuex 是一個專為 Vue.js 應用程序開發的狀態管理模式。它采用集中式存儲管理應用的所有組件的狀態,并以相應的規則保證狀態以一種可預測的方式發生變化。Vuex 也集成到 Vue 的官方調試工具 devtools extension,提供了諸如零配置的 time-travel 調試、狀態快照導入導出等高級調試功能。
什么是“狀態管理模式”?
new Vue({
// state
data () {
return {
count: 0
}
},
// view
template: `
<div>{{ count }}</div>
`,
// actions
methods: {
increment () {
this.count++
}
}
})
這個狀態自管理應用包含以下幾個部分:
- state,驅動應用的數據源;
- view,以聲明方式將 state 映射到視圖;
- actions,響應在 view 上的用戶輸入導致的狀態變化。
但是,當我們的應用遇到多個組件共享狀態時,單向數據流的簡潔性很容易被破壞:
- 多個視圖依賴于同一狀態。
- 來自不同視圖的行為需要變更同一狀態。
對于問題一,傳參的方法對于多層嵌套的組件將會非常繁瑣,并且對于兄弟組件間的狀態傳遞無能為力。對于問題二,我們經常會采用父子組件直接引用或者通過事件來變更和同步狀態的多份拷貝。以上的這些模式非常脆弱,通常會導致無法維護的代碼。
因此,我們為什么不把組件的共享狀態抽取出來,以一個全局單例模式管理呢?在這種模式下,我們的組件樹構成了一個巨大的“視圖”,不管在樹的哪個位置,任何組件都能獲取狀態或者觸發行為!
另外,通過定義和隔離狀態管理中的各種概念并強制遵守一定的規則,我們的代碼將會變得更結構化且易維護。
這就是 Vuex 背后的基本思想,借鑒了 Flux、Redux、和 The Elm Architecture。與其他模式不同的是,Vuex 是專門為 Vue.js 設計的狀態管理庫,以利用 Vue.js 的細粒度數據響應機制來進行高效的狀態更新。
什么情況下我應該使用 Vuex?
雖然 Vuex 可以幫助我們管理共享狀態,但也附帶了更多的概念和框架。這需要對短期和長期效益進行權衡。
如果您不打算開發大型單頁應用,使用 Vuex 可能是繁瑣冗余的。確實是如此——如果您的應用夠簡單,您最好不要使用 Vuex。一個簡單的 store 模式 就足夠您所需了。但是,如果您需要構建一個中大型單頁應用,您很可能會考慮如何更好地在組件外部管理狀態,Vuex 將會成為自然而然的選擇。引用 Redux 的作者 Dan Abramov 的話說就是:
Flux 架構就像眼鏡:您自會知道什么時候需要它。
開始
每一個 Vuex 應用的核心就是 store(倉庫)。“store”基本上就是一個容器,它包含著你的應用中大部分的狀態 (state)。Vuex 和單純的全局對象有以下兩點不同:
- Vuex 的狀態存儲是響應式的。當 Vue 組件從 store 中讀取狀態的時候,若 store 中的狀態發生變化,那么相應的組件也會相應地得到高效更新。
- 你不能直接改變 store 中的狀態。改變 store 中的狀態的唯一途徑就是顯式地提交 (commit) mutation。這樣使得我們可以方便地跟蹤每一個狀態的變化,從而讓我們能夠實現一些工具幫助我們更好地了解我們的應用。
最簡單的 Store
提示: 我們將在后續的文檔示例代碼中使用 ES2015 語法。如果你還沒能掌握 ES2015,你得抓緊了
安裝 Vuex 之后,讓我們來創建一個 store。創建過程直截了當——僅需要提供一個初始 state 對象和一些 mutation:
// 如果在模塊化構建系統中,請確保在開頭調用了 Vue.use(Vuex)
const store = new Vuex.Store({
state: {
count: 0
},
mutations: {
increment (state) {
state.count++
}
}
})
現在,你可以通過 store.state 來獲取狀態對象,以及通過 store.commit 方法觸發狀態變更:
store.commit('increment')
console.log(store.state.count) // -> 1
再次強調,我們通過提交 mutation 的方式,而非直接改變 store.state.count,是因為我們想要更明確地追蹤到狀態的變化。這個簡單的約定能夠讓你的意圖更加明顯,這樣你在閱讀代碼的時候能更容易地解讀應用內部的狀態改變。此外,這樣也讓我們有機會去實現一些能記錄每次狀態改變,保存狀態快照的調試工具。有了它,我們甚至可以實現如時間穿梭般的調試體驗。
由于 store 中的狀態是響應式的,在組件中調用 store 中的狀態簡單到僅需要在計算屬性中返回即可。觸發變化也僅僅是在組件的 methods 中提交 mutation。
這是一個最基本的 Vuex 記數應用示例。
接下來,我們將會更深入地探討一些核心概念。讓我們先從 State 概念開始。
核心概念
State
單一狀態樹
Vuex 使用單一狀態樹——是的,用一個對象就包含了全部的應用層級狀態。至此它便作為一個“唯一數據源 (SSOT)”而存在。這也意味著,每個應用將僅僅包含一個 store 實例。單一狀態樹讓我們能夠直接地定位任一特定的狀態片段,在調試的過程中也能輕易地取得整個當前應用狀態的快照。
單狀態樹和模塊化并不沖突——在后面的章節里我們會討論如何將狀態和狀態變更事件分布到各個子模塊中。
在 Vue 組件中獲得 Vuex 狀態
那么我們如何在 Vue 組件中展示狀態呢?由于 Vuex 的狀態存儲是響應式的,從 store 實例中讀取狀態最簡單的方法就是在計算屬性中返回某個狀態:
// 創建一個 Counter 組件
const Counter = {
template: `<div>{{ count }}</div>`,
computed: {
count () {
return store.state.count
}
}
}
每當 store.state.count 變化的時候, 都會重新求取計算屬性,并且觸發更新相關聯的 DOM。
然而,這種模式導致組件依賴全局狀態單例。在模塊化的構建系統中,在每個需要使用 state 的組件中需要頻繁地導入,并且在測試組件時需要模擬狀態。
Vuex 通過 store 選項,提供了一種機制將狀態從根組件“注入”到每一個子組件中(需調用 Vue.use(Vuex)):
const app = new Vue({
el: '#app',
// 把 store 對象提供給 “store” 選項,這可以把 store 的實例注入所有的子組件
store,
components: { Counter },
template: `
<div class="app">
<counter></counter>
</div>
`
})
通過在根實例中注冊 store 選項,該 store 實例會注入到根組件下的所有子組件中,且子組件能通過 this.$store 訪問到。讓我們更新下 Counter 的實現:
const Counter = {
template: `<div>{{ count }}</div>`,
computed: {
count () {
return this.$store.state.count
}
}
}
mapState 輔助函數
當一個組件需要獲取多個狀態時候,將這些狀態都聲明為計算屬性會有些重復和冗余。為了解決這個問題,我們可以使用 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
}
})
}
當映射的計算屬性的名稱與 state 的子節點名稱相同時,我們也可以給 mapState 傳一個字符串數組。
computed: mapState([
// 映射 this.count 為 store.state.count
'count'
])
對象展開運算符
mapState 函數返回的是一個對象。我們如何將它與局部計算屬性混合使用呢?通常,我們需要使用一個工具函數將多個對象合并為一個,以使我們可以將最終對象傳給 computed 屬性。但是自從有了對象展開運算符(現處于 ECMASCript 提案 stage-4 階段),我們可以極大地簡化寫法:
computed: {
localComputed () { /* ... */ },
// 使用對象展開運算符將此對象混入到外部對象中
...mapState({
// ...
})
}
組件仍然保有局部狀態
使用 Vuex 并不意味著你需要將所有的狀態放入 Vuex。雖然將所有的狀態放到 Vuex 會使狀態變化更顯式和易調試,但也會使代碼變得冗長和不直觀。如果有些狀態嚴格屬于單個組件,最好還是作為組件的局部狀態。你應該根據你的應用開發需要進行權衡和確定。
Getter
有時候我們需要從 store 中的 state 中派生出一些狀態,例如對列表進行過濾并計數:
computed: {
doneTodosCount () {
return this.$store.state.todos.filter(todo => todo.done).length
}
}
如果有多個組件需要用到此屬性,我們要么復制這個函數,或者抽取到一個共享函數然后在多處導入它——無論哪種方式都不是很理想。
Vuex 允許我們在 store 中定義“getter”(可以認為是 store 的計算屬性)。就像計算屬性一樣,getter 的返回值會根據它的依賴被緩存起來,且只有當它的依賴值發生了改變才會被重新計算。
Getter 接受 state 作為其第一個參數:
const store = new Vuex.Store({
state: {
todos: [
{ id: 1, text: '...', done: true },
{ id: 2, text: '...', done: false }
]
},
getters: {
doneTodos: state => {
return state.todos.filter(todo => todo.done)
}
}
})
通過屬性訪問
Getter 會暴露為 store.getters 對象,你可以以屬性的形式訪問這些值:
store.getters.doneTodos // -> [{ id: 1, text: '...', done: true }]
Getter 也可以接受其他 getter 作為第二個參數:
getters: {
// ...
doneTodosCount: (state, getters) => {
return getters.doneTodos.length
}
}
store.getters.doneTodosCount // -> 1
我們可以很容易地在任何組件中使用它:
computed: {
doneTodosCount () {
return this.$store.getters.doneTodosCount
}
}
注意,getter 在通過屬性訪問時是作為 Vue 的響應式系統的一部分緩存其中的。
通過方法訪問
你也可以通過讓 getter 返回一個函數,來實現給 getter 傳參。在你對 store 里的數組進行查詢時非常有用。
getters: {
// ...
getTodoById: (state) => (id) => {
return state.todos.find(todo => todo.id === id)
}
}
store.getters.getTodoById(2) // -> { id: 2, text: '...', done: false }
注意,getter 在通過方法訪問時,每次都會去進行調用,而不會緩存結果。
mapGetters 輔助函數
mapGetters 輔助函數僅僅是將 store 中的 getter 映射到局部計算屬性:
import { mapGetters } from 'vuex'
export default {
// ...
computed: {
// 使用對象展開運算符將 getter 混入 computed 對象中
...mapGetters([
'doneTodosCount',
'anotherGetter',
// ...
])
}
}
如果你想將一個 getter 屬性另取一個名字,使用對象形式:
mapGetters({
// 把 `this.doneCount` 映射為 `this.$store.getters.doneTodosCount`
doneCount: 'doneTodosCount'
})
Mutation
更改 Vuex 的 store 中的狀態的唯一方法是提交 mutation。Vuex 中的 mutation 非常類似于事件:每個 mutation 都有一個字符串的 事件類型 (type) 和 一個 回調函數 (handler)。這個回調函數就是我們實際進行狀態更改的地方,并且它會接受 state 作為第一個參數:
const store = new Vuex.Store({
state: {
count: 1
},
mutations: {
increment (state) {
// 變更狀態
state.count++
}
}
})
你不能直接調用一個 mutation handler。這個選項更像是事件注冊:“當觸發一個類型為 increment 的 mutation 時,調用此函數。”要喚醒一個 mutation handler,你需要以相應的 type 調用 store.commit 方法:
store.commit('increment')
提交載荷(Payload)
你可以向 store.commit 傳入額外的參數,即 mutation 的 載荷(payload):
// ...
mutations: {
increment (state, n) {
state.count += n
}
}
store.commit('increment', 10)
在大多數情況下,載荷應該是一個對象,這樣可以包含多個字段并且記錄的 mutation 會更易讀:
// ...
mutations: {
increment (state, payload) {
state.count += payload.amount
}
}
store.commit('increment', {
amount: 10
})
對象風格的提交方式
提交 mutation 的另一種方式是直接使用包含 type 屬性的對象:
store.commit({
type: 'increment',
amount: 10
})
當使用對象風格的提交方式,整個對象都作為載荷傳給 mutation 函數,因此 handler 保持不變:
mutations: {
increment (state, payload) {
state.count += payload.amount
}
}
Mutation 需遵守 Vue 的響應規則
既然 Vuex 的 store 中的狀態是響應式的,那么當我們變更狀態時,監視狀態的 Vue 組件也會自動更新。這也意味著 Vuex 中的 mutation 也需要與使用 Vue 一樣遵守一些注意事項:
最好提前在你的 store 中初始化好所有所需屬性。
當需要在對象上添加新屬性時,你應該
使用 Vue.set(obj, 'newProp', 123), 或者
以新對象替換老對象。例如,利用 stage-3 的對象展開運算符我們可以這樣寫:
state.obj = { ...state.obj, newProp: 123 }
使用常量替代 Mutation 事件類型
使用常量替代 mutation 事件類型在各種 Flux 實現中是很常見的模式。這樣可以使 linter 之類的工具發揮作用,同時把這些常量放在單獨的文件中可以讓你的代碼合作者對整個 app 包含的 mutation 一目了然:
// mutation-types.js
export const SOME_MUTATION = 'SOME_MUTATION'
// store.js
import Vuex from 'vuex'
import { SOME_MUTATION } from './mutation-types'
const store = new Vuex.Store({
state: { ... },
mutations: {
// 我們可以使用 ES2015 風格的計算屬性命名功能來使用一個常量作為函數名
[SOME_MUTATION] (state) {
// mutate state
}
}
})
用不用常量取決于你——在需要多人協作的大型項目中,這會很有幫助。但如果你不喜歡,你完全可以不這樣做。
Mutation 必須是同步函數
一條重要的原則就是要記住 mutation 必須是同步函數。為什么?請參考下面的例子:
mutations: {
someMutation (state) {
api.callAsyncMethod(() => {
state.count++
})
}
}
現在想象,我們正在 debug 一個 app 并且觀察 devtool 中的 mutation 日志。每一條 mutation 被記錄,devtools 都需要捕捉到前一狀態和后一狀態的快照。然而,在上面的例子中 mutation 中的異步函數中的回調讓這不可能完成:因為當 mutation 觸發的時候,回調函數還沒有被調用,devtools 不知道什么時候回調函數實際上被調用——實質上任何在回調函數中進行的狀態的改變都是不可追蹤的。
在組件中提交 Mutation
你可以在組件中使用 this.$store.commit('xxx') 提交 mutation,或者使用 mapMutations 輔助函數將組件中的 methods 映射為 store.commit 調用(需要在根節點注入 store)。
import { mapMutations } from 'vuex'
export default {
// ...
methods: {
...mapMutations([
'increment', // 將 `this.increment()` 映射為 `this.$store.commit('increment')`
// `mapMutations` 也支持載荷:
'incrementBy' // 將 `this.incrementBy(amount)` 映射為 `this.$store.commit('incrementBy', amount)`
]),
...mapMutations({
add: 'increment' // 將 `this.add()` 映射為 `this.$store.commit('increment')`
})
}
}
下一步:Action
在 mutation 中混合異步調用會導致你的程序很難調試。例如,當你調用了兩個包含異步回調的 mutation 來改變狀態,你怎么知道什么時候回調和哪個先回調呢?這就是為什么我們要區分這兩個概念。在 Vuex 中,mutation 都是同步事務:
store.commit('increment')
// 任何由 "increment" 導致的狀態變更都應該在此刻完成。
為了處理異步操作,讓我們來看一看 Action。
Action
Action 類似于 mutation,不同在于:
Action 提交的是 mutation,而不是直接變更狀態。
Action 可以包含任意異步操作。
讓我們來注冊一個簡單的 action:
const store = new Vuex.Store({
state: {
count: 0
},
mutations: {
increment (state) {
state.count++
}
},
actions: {
increment (context) {
context.commit('increment')
}
}
})
Action 函數接受一個與 store 實例具有相同方法和屬性的 context 對象,因此你可以調用 context.commit 提交一個 mutation,或者通過 context.state 和 context.getters 來獲取 state 和 getters。當我們在之后介紹到 Modules 時,你就知道 context 對象為什么不是 store 實例本身了。
實踐中,我們會經常用到 ES2015 的 參數解構 來簡化代碼(特別是我們需要調用 commit 很多次的時候):
actions: {
increment ({ commit }) {
commit('increment')
}
}
分發 Action
Action 通過 store.dispatch 方法觸發:
store.dispatch('increment')
乍一眼看上去感覺多此一舉,我們直接分發 mutation 豈不更方便?實際上并非如此,還記得 mutation 必須同步執行這個限制么?Action 就不受約束!我們可以在 action 內部執行異步操作:
actions: {
incrementAsync ({ commit }) {
setTimeout(() => {
commit('increment')
}, 1000)
}
}
Actions 支持同樣的載荷方式和對象方式進行分發:
// 以載荷形式分發
store.dispatch('incrementAsync', {
amount: 10
})
// 以對象形式分發
store.dispatch({
type: 'incrementAsync',
amount:
10
})
來看一個更加實際的購物車示例,涉及到調用異步 API 和分發多重 mutation:
actions: {
checkout ({ commit, state }, products) {
// 把當前購物車的物品備份起來
const savedCartItems = [...state.cart.added]
// 發出結賬請求,然后樂觀地清空購物車
commit(types.CHECKOUT_REQUEST)
// 購物 API 接受一個成功回調和一個失敗回調
shop.buyProducts(
products,
// 成功操作
() => commit(types.CHECKOUT_SUCCESS),
// 失敗操作
() => commit(types.CHECKOUT_FAILURE, savedCartItems)
)
}
}
注意我們正在進行一系列的異步操作,并且通過提交 mutation 來記錄 action 產生的副作用(即狀態變更)。
在組件中分發 Action
你在組件中使用 this.$store.dispatch('xxx') 分發 action,或者使用 mapActions 輔助函數將組件的 methods 映射為 store.dispatch 調用(需要先在根節點注入 store):
import { mapActions } from 'vuex'
export default {
// ...
methods: {
...mapActions([
'increment', // 將 `this.increment()` 映射為 `this.$store.dispatch('increment')`
// `mapActions` 也支持載荷:
'incrementBy' // 將 `this.incrementBy(amount)` 映射為 `this.$store.dispatch('incrementBy', amount)`
]),
...mapActions({
add: 'increment' // 將 `this.add()` 映射為 `this.$store.dispatch('increment')`
})
}
}
組合 Action
Action 通常是異步的,那么如何知道 action 什么時候結束呢?更重要的是,我們如何才能組合多個 action,以處理更加復雜的異步流程?
首先,你需要明白 store.dispatch 可以處理被觸發的 action 的處理函數返回的 Promise,并且 store.dispatch 仍舊返回 Promise:
actions: {
actionA ({ commit }) {
return new Promise((resolve, reject) => {
setTimeout(() => {
commit('someMutation')
resolve()
}, 1000)
})
}
}
現在你可以:
store.dispatch('actionA').then(() => {
// ...
})
在另外一個 action 中也可以:
actions: {
// ...
actionB ({ dispatch, commit }) {
return dispatch('actionA').then(() => {
commit('someOtherMutation')
})
}
}
最后,如果我們利用 async / await,我們可以如下組合 action:
// 假設 getData() 和 getOtherData() 返回的是 Promise
actions: {
async actionA ({ commit }) {
commit('gotData', await getData())
},
async actionB ({ dispatch, commit }) {
await dispatch('actionA') // 等待 actionA 完成
commit('gotOtherData', await getOtherData())
}
}
一個 store.dispatch 在不同模塊中可以觸發多個 action 函數。在這種情況下,只有當所有觸發函數完成后,返回的 Promise 才會執行。
Module
由于使用單一狀態樹,應用的所有狀態會集中到一個比較大的對象。當應用變得非常復雜時,store 對象就有可能變得相當臃腫。
為了解決以上問題,Vuex 允許我們將 store 分割成模塊(module)。每個模塊擁有自己的 state、mutation、action、getter、甚至是嵌套子模塊——從上至下進行同樣方式的分割:
const moduleA = {
state: { ... },
mutations: { ... },
actions: { ... },
getters: { ... }
}
const moduleB = {
state: { ... },
mutations: { ... },
actions: { ... }
}
const store = new Vuex.Store({
modules: {
a: moduleA,
b: moduleB
}
})
store.state.a // -> moduleA 的狀態
store.state.b // -> moduleB 的狀態
模塊的局部狀態
對于模塊內部的 mutation 和 getter,接收的第一個參數是模塊的局部狀態對象。
const moduleA = {
state: { count: 0 },
mutations: {
increment (state) {
// 這里的 `state` 對象是模塊的局部狀態
state.count++
}
},
getters: {
doubleCount (state) {
return state.count * 2
}
}
}
同樣,對于模塊內部的 action,局部狀態通過 context.state 暴露出來,根節點狀態則為 context.rootState:
const moduleA = {
// ...
actions: {
incrementIfOddOnRootSum ({ state, commit, rootState }) {
if ((state.count + rootState.count) % 2 === 1) {
commit('increment')
}
}
}
}
對于模塊內部的 getter,根節點狀態會作為第三個參數暴露出來:
const moduleA = {
// ...
getters: {
sumWithRootCount (state, getters, rootState) {
return state.count + rootState.count
}
}
}
命名空間
默認情況下,模塊內部的 action、mutation 和 getter 是注冊在全局命名空間的——這樣使得多個模塊能夠對同一 mutation 或 action 作出響應。
如果希望你的模塊具有更高的封裝度和復用性,你可以通過添加 namespaced: true 的方式使其成為帶命名空間的模塊。當模塊被注冊后,它的所有 getter、action 及 mutation 都會自動根據模塊注冊的路徑調整命名。例如:
const store = new Vuex.Store({
modules: {
account: {
namespaced: true,
// 模塊內容(module assets)
state: { ... }, // 模塊內的狀態已經是嵌套的了,使用 `namespaced` 屬性不會對其產生影響
getters: {
isAdmin () { ... } // -> getters['account/isAdmin']
},
actions: {
login () { ... } // -> dispatch('account/login')
},
mutations: {
login () { ... } // -> commit('account/login')
},
// 嵌套模塊
modules: {
// 繼承父模塊的命名空間
myPage: {
state: { ... },
getters: {
profile () { ... } // -> getters['account/profile']
}
},
// 進一步嵌套命名空間
posts: {
namespaced: true,
state: { ... },
getters: {
popular () { ... } // -> getters['account/posts/popular']
}
}
}
}
}
})
啟用了命名空間的 getter 和 action 會收到局部化的 getter,dispatch 和 commit。換言之,你在使用模塊內容(module assets)時不需要在同一模塊內額外添加空間名前綴。更改 namespaced 屬性后不需要修改模塊內的代碼。
在帶命名空間的模塊內訪問全局內容(Global Assets)
如果你希望使用全局 state 和 getter,rootState 和 rootGetter 會作為第三和第四參數傳入 getter,也會通過 context 對象的屬性傳入 action。
若需要在全局命名空間內分發 action 或提交 mutation,將 { root: true } 作為第三參數傳給 dispatch 或 commit 即可。
modules: {
foo: {
namespaced: true,
getters: {
// 在這個模塊的 getter 中,`getters` 被局部化了
// 你可以使用 getter 的第四個參數來調用 `rootGetters`
someGetter (state, getters, rootState, rootGetters) {
getters.someOtherGetter // -> 'foo/someOtherGetter'
rootGetters.someOtherGetter // -> 'someOtherGetter'
},
someOtherGetter: state => { ... }
},
actions: {
// 在這個模塊中, dispatch 和 commit 也被局部化了
// 他們可以接受 `root` 屬性以訪問根 dispatch 或 commit
someAction ({ dispatch, commit, getters, rootGetters }) {
getters.someGetter // -> 'foo/someGetter'
rootGetters.someGetter // -> 'someGetter'
dispatch('someOtherAction') // -> 'foo/someOtherAction'
dispatch('someOtherAction', null, { root: true }) // -> 'someOtherAction'
commit('someMutation') // -> 'foo/someMutation'
commit('someMutation', null, { root: true }) // -> 'someMutation'
},
someOtherAction (ctx, payload) { ... }
}
}
}
在帶命名空間的模塊注冊全局 action
若需要在帶命名空間的模塊注冊全局 action,你可添加 root: true,并將這個 action 的定義放在函數 handler 中。例如:
{
actions: {
someOtherAction ({dispatch}) {
dispatch('someAction')
}
},
modules: {
foo: {
namespaced: true,
actions: {
someAction: {
root: true,
handler (namespacedContext, payload) { ... } // -> 'someAction'
}
}
}
}
}
帶命名空間的綁定函數
當使用 mapState, mapGetters, mapActions 和 mapMutations 這些函數來綁定帶命名空間的模塊時,寫起來可能比較繁瑣:
computed: {
...mapState({
a: state => state.some.nested.module.a,
b: state => state.some.nested.module.b
})
},
methods: {
...mapActions([
'some/nested/module/foo', // -> this['some/nested/module/foo']()
'some/nested/module/bar' // -> this['some/nested/module/bar']()
])
}
對于這種情況,你可以將模塊的空間名稱字符串作為第一個參數傳遞給上述函數,這樣所有綁定都會自動將該模塊作為上下文。于是上面的例子可以簡化為:
computed: {
...mapState('some/nested/module', {
a: state => state.a,
b: state => state.b
})
},
methods: {
...mapActions('some/nested/module', [
'foo', // -> this.foo()
'bar' // -> this.bar()
])
}
而且,你可以通過使用 createNamespacedHelpers 創建基于某個命名空間輔助函數。它返回一個對象,對象里有新的綁定在給定命名空間值上的組件綁定輔助函數:
import { createNamespacedHelpers } from 'vuex'
const { mapState, mapActions } = createNamespacedHelpers('some/nested/module')
export default {
computed: {
// 在 `some/nested/module` 中查找
...mapState({
a: state => state.a,
b: state => state.b
})
},
methods: {
// 在 `some/nested/module` 中查找
...mapActions([
'foo',
'bar'
])
}
}
給插件開發者的注意事項
如果你開發的插件(Plugin)提供了模塊并允許用戶將其添加到 Vuex store,可能需要考慮模塊的空間名稱問題。對于這種情況,你可以通過插件的參數對象來允許用戶指定空間名稱:
// 通過插件的參數對象得到空間名稱
// 然后返回 Vuex 插件函數
export function createPlugin (options = {}) {
return function (store) {
// 把空間名字添加到插件模塊的類型(type)中去
const namespace = options.namespace || ''
store.dispatch(namespace + 'pluginAction')
}
}
模塊動態注冊
在 store 創建之后,你可以使用 store.registerModule 方法注冊模塊:
// 注冊模塊 `myModule`
store.registerModule('myModule', {
// ...
})
// 注冊嵌套模塊 `nested/myModule`
store.registerModule(['nested', 'myModule'], {
// ...
})
之后就可以通過 store.state.myModule 和 store.state.nested.myModule 訪問模塊的狀態。
模塊動態注冊功能使得其他 Vue 插件可以通過在 store 中附加新模塊的方式來使用 Vuex 管理狀態。例如,vuex-router-sync 插件就是通過動態注冊模塊將 vue-router 和 vuex 結合在一起,實現應用的路由狀態管理。
你也可以使用 store.unregisterModule(moduleName) 來動態卸載模塊。注意,你不能使用此方法卸載靜態模塊(即創建 store 時聲明的模塊)。
在注冊一個新 module 時,你很有可能想保留過去的 state,例如從一個服務端渲染的應用保留 state。你可以通過 preserveState 選項將其歸檔:store.registerModule('a', module, { preserveState: true })。
模塊重用
有時我們可能需要創建一個模塊的多個實例,例如:
創建多個 store,他們公用同一個模塊 (例如當 runInNewContext 選項是 false 或 'once' 時,為了在服務端渲染中避免有狀態的單例)
在一個 store 中多次注冊同一個模塊
如果我們使用一個純對象來聲明模塊的狀態,那么這個狀態對象會通過引用被共享,導致狀態對象被修改時 store 或模塊間數據互相污染的問題。
實際上這和 Vue 組件內的 data 是同樣的問題。因此解決辦法也是相同的——使用一個函數來聲明模塊狀態(僅 2.3.0+ 支持):
const MyReusableModule = {
state () {
return {
foo: 'bar'
}
},
// mutation, action 和 getter 等等...
}
項目結構
Vuex 并不限制你的代碼結構。但是,它規定了一些需要遵守的規則:
應用層級的狀態應該集中到單個 store 對象中。
提交 mutation 是更改狀態的唯一方法,并且這個過程是同步的。
異步邏輯都應該封裝到 action 里面。
只要你遵守以上規則,如何組織代碼隨你便。如果你的 store 文件太大,只需將 action、mutation 和 getter 分割到單獨的文件。
對于大型應用,我們會希望把 Vuex 相關代碼分割到模塊中。下面是項目結構示例:
├── index.html
├── main.js
├── api
│ └── ... # 抽取出API請求
├── components
│ ├── App.vue
│ └── ...
└── store
├── index.js # 我們組裝模塊并導出 store 的地方
├── actions.js # 根級別的 action
├── mutations.js # 根級別的 mutation
└── modules
├── cart.js # 購物車模塊
└── products.js # 產品模塊
插件
Vuex 的 store 接受 plugins 選項,這個選項暴露出每次 mutation 的鉤子。Vuex 插件就是一個函數,它接收 store 作為唯一參數:
const myPlugin = store => {
// 當 store 初始化后調用
store.subscribe((mutation, state) => {
// 每次 mutation 之后調用
// mutation 的格式為 { type, payload }
})
}
然后像這樣使用:
const store = new Vuex.Store({
// ...
plugins: [myPlugin]
})
在插件內提交 Mutation
在插件中不允許直接修改狀態——類似于組件,只能通過提交 mutation 來觸發變化。
通過提交 mutation,插件可以用來同步數據源到 store。例如,同步 websocket 數據源到 store(下面是個大概例子,實際上 createPlugin 方法可以有更多選項來完成復雜任務):
export default function createWebSocketPlugin (socket) {
return store => {
socket.on('data', data => {
store.commit('receiveData', data)
})
store.subscribe(mutation => {
if (mutation.type === 'UPDATE_DATA') {
socket.emit('update', mutation.payload)
}
})
}
}
const plugin = createWebSocketPlugin(socket)
const store = new Vuex.Store({
state,
mutations,
plugins: [plugin]
})
生成 State 快照
有時候插件需要獲得狀態的“快照”,比較改變的前后狀態。想要實現這項功能,你需要對狀態對象進行深拷貝:
const myPluginWithSnapshot = store => {
let prevState = _.cloneDeep(store.state)
store.subscribe((mutation, state) => {
let nextState = _.cloneDeep(state)
// 比較 prevState 和 nextState...
// 保存狀態,用于下一次 mutation
prevState = nextState
})
}
生成狀態快照的插件應該只在開發階段使用,使用 webpack 或 Browserify,讓構建工具幫我們處理:
const store = new Vuex.Store({
// ...
plugins: process.env.NODE_ENV !== 'production'
? [myPluginWithSnapshot]
: []
})
上面插件會默認啟用。在發布階段,你需要使用 webpack 的 DefinePlugin 或者是 Browserify 的 envify 使 process.env.NODE_ENV !== 'production' 為 false。
內置 Logger 插件
如果正在使用 vue-devtools,你可能不需要此插件。
Vuex 自帶一個日志插件用于一般的調試:
import createLogger from 'vuex/dist/logger'
const store = new Vuex.Store({
plugins: [createLogger()]
})
createLogger 函數有幾個配置項:
const logger = createLogger({
collapsed: false, // 自動展開記錄的 mutation
filter (mutation, stateBefore, stateAfter) {
// 若 mutation 需要被記錄,就讓它返回 true 即可
// 順便,`mutation` 是個 { type, payload } 對象
return mutation.type !== "aBlacklistedMutation"
},
transformer (state) {
// 在開始記錄之前轉換狀態
// 例如,只返回指定的子樹
return state.subTree
},
mutationTransformer (mutation) {
// mutation 按照 { type, payload } 格式記錄
// 我們可以按任意方式格式化
return mutation.type
},
logger: console, // 自定義 console 實現,默認為 `console`
})
日志插件還可以直接通過 <script> 標簽引入,它會提供全局方法 createVuexLogger。
要注意,logger 插件會生成狀態快照,所以僅在開發環境使用。
嚴格模式
開啟嚴格模式,僅需在創建 store 的時候傳入 strict: true:
const store = new Vuex.Store({
// ...
strict: true
})
在嚴格模式下,無論何時發生了狀態變更且不是由 mutation 函數引起的,將會拋出錯誤。這能保證所有的狀態變更都能被調試工具跟蹤到。
開發環境與發布環境
** 不要在發布環境下啟用嚴格模式!**嚴格模式會深度監測狀態樹來檢測不合規的狀態變更——請確保在發布環境下關閉嚴格模式,以避免性能損失。
類似于插件,我們可以讓構建工具來處理這種情況:
const store = new Vuex.Store({
// ...
strict: process.env.NODE_ENV !== 'production'
})
表單處理
當在嚴格模式中使用 Vuex 時,在屬于 Vuex 的 state 上使用 v-model 會比較棘手:
<input v-model="obj.message">
假設這里的 obj 是在計算屬性中返回的一個屬于 Vuex store 的對象,在用戶輸入時,v-model 會試圖直接修改 obj.message。在嚴格模式中,由于這個修改不是在 mutation 函數中執行的, 這里會拋出一個錯誤。
用“Vuex 的思維”去解決這個問題的方法是:給 <input> 中綁定 value,然后偵聽 input 或者 change 事件,在事件回調中調用 action:
<input :value="message" @input="updateMessage">
// ...
computed: {
...mapState({
message: state => state.obj.message
})
},
methods: {
updateMessage (e) {
this.$store.commit('updateMessage', e.target.value)
}
}
下面是 mutation 函數:
// ...
mutations: {
updateMessage (state, message) {
state.obj.message = message
}
}
雙向綁定的計算屬性
必須承認,這樣做比簡單地使用“v-model + 局部狀態”要啰嗦得多,并且也損失了一些 v-model 中很有用的特性。另一個方法是使用帶有 setter 的雙向綁定計算屬性:
<input v-model="message">
// ...
computed: {
message: {
get () {
return this.$store.state.obj.message
},
set (value) {
this.$store.commit('updateMessage', value)
}
}
}
測試
我們主要想針對 Vuex 中的 mutation 和 action 進行單元測試。
測試 Mutation
Mutation 很容易被測試,因為它們僅僅是一些完全依賴參數的函數。這里有一個小技巧,如果你在 store.js 文件中定義了 mutation,并且使用 ES2015 模塊功能默認輸出了 Vuex.Store 的實例,那么你仍然可以給 mutation 取個變量名然后把它輸出去:
const state = { ... }
// `mutations` 作為命名輸出對象
export const mutations = { ... }
export default new Vuex.Store({
state,
mutations
})
下面是用 Mocha + Chai 測試一個 mutation 的例子(實際上你可以用任何你喜歡的測試框架):
// mutations.js
export const mutations = {
increment: state => state.count++
}
// mutations.spec.js
import { expect } from 'chai'
import { mutations } from './store'
// 解構 `mutations`
const { increment } = mutations
describe('mutations', () => {
it('INCREMENT', () => {
// 模擬狀態
const state = { count: 0 }
// 應用 mutation
increment(state)
// 斷言結果
expect(state.count).to.equal(1)
})
})
測試 Action
Action 應對起來略微棘手,因為它們可能需要調用外部的 API。當測試 action 的時候,我們需要增加一個 mocking 服務層——例如,我們可以把 API 調用抽象成服務,然后在測試文件中用 mock 服務回應 API 調用。為了便于解決 mock 依賴,可以用 webpack 和 inject-loader 打包測試文件。
下面是一個測試異步 action 的例子:
// actions.js
import shop from '../api/shop'
export const getAllProducts = ({ commit }) => {
commit('REQUEST_PRODUCTS')
shop.getProducts(products => {
commit('RECEIVE_PRODUCTS', products)
})
}
// actions.spec.js
// 使用 require 語法處理內聯 loaders。
// inject-loader 返回一個允許我們注入 mock 依賴的模塊工廠
import { expect } from 'chai'
const actionsInjector = require('inject-loader!./actions')
// 使用 mocks 創建模塊
const actions = actionsInjector({
'../api/shop': {
getProducts (cb) {
setTimeout(() => {
cb([ /* mocked response */ ])
}, 100)
}
}
})
// 用指定的 mutations 測試 action 的輔助函數
const testAction = (action, args, state, expectedMutations, done) => {
let count = 0
// 模擬提交
const commit = (type, payload) => {
const mutation = expectedMutations[count]
try {
expect(mutation.type).to.equal(type)
if (payload) {
expect(mutation.payload).to.deep.equal(payload)
}
} catch (error) {
done(error)
}
count++
if (count >= expectedMutations.length) {
done()
}
}
// 用模擬的 store 和參數調用 action
action({ commit, state }, ...args)
// 檢查是否沒有 mutation 被 dispatch
if (expectedMutations.length === 0) {
expect(count).to.equal(0)
done()
}
}
describe('actions', () => {
it('getAllProducts', done => {
testAction(actions.getAllProducts, [], {}, [
{ type: 'REQUEST_PRODUCTS' },
{ type: 'RECEIVE_PRODUCTS', payload: { /* mocked response */ } }
], done)
})
})
如果在測試環境下有可用的 spy (比如通過 Sinon.JS),你可以使用它們替換輔助函數 testAction:
describe('actions', () => {
it('getAllProducts', () => {
const commit = sinon.spy()
const state = {}
actions.getAllProducts({ commit, state })
expect(commit.args).to.deep.equal([
['REQUEST_PRODUCTS'],
['RECEIVE_PRODUCTS', { /* mocked response */ }]
])
})
})
測試 Getter
如果你的 getter 包含很復雜的計算過程,很有必要測試它們。Getter 的測試與 mutation 一樣直截了當。
測試一個 getter 的示例:
// getters.js
export const getters = {
filteredProducts (state, { filterCategory }) {
return state.products.filter(product => {
return product.category === filterCategory
})
}
}
// getters.spec.js
import { expect } from 'chai'
import { getters } from './getters'
describe('getters', () => {
it('filteredProducts', () => {
// 模擬狀態
const state = {
products: [
{ id: 1, title: 'Apple', category: 'fruit' },
{ id: 2, title: 'Orange', category: 'fruit' },
{ id: 3, title: 'Carrot', category: 'vegetable' }
]
}
// 模擬 getter
const filterCategory = 'fruit'
// 獲取 getter 的結果
const result = getters.filteredProducts(state, { filterCategory })
// 斷言結果
expect(result).to.deep.equal([
{ id: 1, title: 'Apple', category: 'fruit' },
{ id: 2, title: 'Orange', category: 'fruit' }
])
})
})
執行測試
如果你的 mutation 和 action 編寫正確,經過合理地 mocking 處理之后這些測試應該不依賴任何瀏覽器 API,因此你可以直接用 webpack 打包這些測試文件然后在 Node 中執行。換種方式,你也可以用 mocha-loader 或 Karma + karma-webpack在真實瀏覽器環境中進行測試。
在 Node 中執行測試
創建以下 webpack 配置(配置好 .babelrc):
// webpack.config.js
module.exports = {
entry: './test.js',
output: {
path: __dirname,
filename: 'test-bundle.js'
},
module: {
loaders: [
{
test: /\.js$/,
loader: 'babel-loader',
exclude: /node_modules/
}
]
}
}
然后:
webpack
mocha test-bundle.js
在瀏覽器中測試
- 安裝 mocha-loader。
- 把上述 webpack 配置中的 entry 改成 'mocha-loader!babel-loader!./test.js'。
- 用以上配置啟動 webpack-dev-server。
- 訪問 localhost:8080/webpack-dev-server/test-bundle。
使用 Karma + karma-webpack 在瀏覽器中執行測試
詳見 vue-loader documentation
熱重載
使用 webpack 的 Hot Module Replacement API,Vuex 支持在開發過程中熱重載 mutation、module、action 和 getter。你也可以在 Browserify 中使用 browserify-hmr 插件。
對于 mutation 和模塊,你需要使用 store.hotUpdate() 方法:
// store.js
import Vue from 'vue'
import Vuex from 'vuex'
import mutations from './mutations'
import moduleA from './modules/a'
Vue.use(Vuex)
const state = { ... }
const store = new Vuex.Store({
state,
mutations,
modules: {
a: moduleA
}
})
if (module.hot) {
// 使 action 和 mutation 成為可熱重載模塊
module.hot.accept(['./mutations', './modules/a'], () => {
// 獲取更新后的模塊
// 因為 babel 6 的模塊編譯格式問題,這里需要加上 `.default`
const newMutations = require('./mutations').default
const newModuleA = require('./modules/a').default
// 加載新模塊
store.hotUpdate({
mutations: newMutations,
modules: {
a: newModuleA
}
})
})
}
參考熱重載示例 counter-hot。
使用 webpack 的 Hot Module Replacement API,Vuex 支持在開發過程中熱重載 mutation、module、action 和 getter。你也可以在 Browserify 中使用 browserify-hmr 插件。
對于 mutation 和模塊,你需要使用 store.hotUpdate() 方法:
// store.js
import Vue from 'vue'
import Vuex from 'vuex'
import mutations from './mutations'
import moduleA from './modules/a'
Vue.use(Vuex)
const state = { ... }
const store = new Vuex.Store({
state,
mutations,
modules: {
a: moduleA
}
})
if (module.hot) {
// 使 action 和 mutation 成為可熱重載模塊
module.hot.accept(['./mutations', './modules/a'], () => {
// 獲取更新后的模塊
// 因為 babel 6 的模塊編譯格式問題,這里需要加上 `.default`
const newMutations = require('./mutations').default
const newModuleA = require('./modules/a').default
// 加載新模塊
store.hotUpdate({
mutations: newMutations,
modules: {
a: newModuleA
}
})
})
}
參考熱重載示例 counter-hot。