Referência da API

Store

createStore

  • createStore<S>(options: StoreOptions<S>): Store<S>

    Cria um novo store.

    import { createStore } from 'vuex'
    
    const store = createStore({ ...options })
    

Opções do Construtor Store

state (estado)

  • type: Object | Function

    O objeto raiz de estado para o store Vuex. Detalhes

    Se você passar uma função que retorna um objeto, o objeto retornado é usado como o estado raiz. Isso é útil quando você deseja reutilizar o objeto de estado, especialmente para reutilização de módulos. Detalhes

mutations (mutações)

  • type: { [type: string]: Function }

    Registra mutações no store. A função manipuladora (ou handler) sempre recebe state como o 1º argumento (será o estado local do módulo se definido em um módulo) e receberá um 2º argumento payload se houver um.

    Detalhes

actions (ações)

  • type: { [type: string]: Function }

    Registra ações no store. A função manipuladora (ou handler) recebe um objeto context que expõe as seguintes propriedades:

    {
      state,      // o mesmo que `store.state`, ou estado local se estiver em módulos
      rootState,  // o mesmo que `store.state`, apenas em módulos
      commit,     // o mesmo que `store.commit`
      dispatch,   // o mesmo que `store.dispatch`
      getters,    // o mesmo que `store.getters`, ou getters locais se estiver em módulos
      rootGetters // o mesmo que `store.getters`, apenas em módulos
    }
    

    E também recebe um 2º argumento payload se houver um.

    Detalhes

getters

  • type: { [key: string]: Function }

    Registra os getters no store. A função getter recebe os seguintes argumentos:

    state,     // será estado local do módulo se definido em um módulo.
    getters    // o mesmo que store.getters
    

    Especificamente quando definido em um módulo

    state,       // será estado local do módulo se definido em um módulo.
    getters,     // módulo de getters locais do módulo atual.
    rootState,   // estado global
    rootGetters  // todos os getters
    

    Os getters registrados estão expostos em store.getters.

    Detalhes

modules (módulos)

  • type: Object

    Um objeto contendo sub módulos a serem incorporados no store, de forma que:

    {
      key: {
        state,
        namespaced?,
        mutations?,
        actions?,
        getters?,
        modules?
      },
      ...
    }
    

    Cada módulo pode conter state e mutations semelhantes às opções raiz. O estado de um módulo será anexado ao estado da raiz do store usando a chave do módulo. As mutações e getters de um módulo receberão apenas o estado local do módulo como o 1º argumento em vez do estado da raiz, e as ações do módulo context.state também apontarão para o estado local.

    Detalhes

plugins

  • type: Array<Function>

    Um Array de funções de plug-in a serem aplicadas no store. O plug-in simplesmente recebe o store como o único argumento e pode ouvir mutações (para persistência de dados de saída, registro ou depuração) ou despachar mutações (para dados de entrada, por exemplo, websockets ou observables).

    Detalhes

strict

  • type: boolean

  • default: false

    Força o store Vuex a rodar mo modo estrito. No modo estrito, qualquer mutação ao estado do Vuex fora dos manipuladores de mutação acusará um erro.

    Detalhes

devtools

  • type: boolean

    Ative ou desative o devtools para uma determinada instância Vuex. Passar false à instância diz ao store Vuex para não se integrar ao devtools. Bem útil quando se tem vários stores em uma single page.

    {
      devtools: false
    }
    

Propriedades da Instância Store

state (estado)

  • type: Object

    O estado raiz. Apenas leitura.

getters

  • type: Object

    Expõe os getters registrados. Apenas leitura.

Métodos da Instância Store

commit

  • commit(type: string, payload?: any, options?: Object)
  • commit(mutation: Object, options?: Object)

Confirma (ou faz um Commit de) uma mutação. options pode ter root: true que permite confirmar mutações da raiz em módulos namespaced. Detalhes

dispatch

  • dispatch(type: string, payload?: any, options?: Object): Promise<any>
  • dispatch(action: Object, options?: Object): Promise<any>

Despacha uma ação. options pode ter root: true que permite despachar ações para raiz em módulos namespaced. Retorna um Promise que resolve todos os manipuladores de ação acionados. Detalhes

replaceState

  • replaceState(state: Object)

Substitue o estado da raiz do store. Use isso apenas para fins de hydration / time-travel.

watch

  • watch(fn: Function, callback: Function, options?: Object): Function

Visualiza de forma reativa um valor de retorno de fn, e chama o callback para o retorno de chamada quando o valor for alterado. O fn recebe o estado do store como o 1º argumento, e os getters como o 2º argumento. Aceita um objeto de opções opcional que leva as mesmas opções que o método vm.$watch do Vue.

Para parar um watch, chame a função unwatch retornada.

subscribe

  • subscribe(handler: Function, options?: Object): Function

Assinatura para as mutações do store. O manipulador é chamado após cada mutação e recebe o descritor da mutação e o estado pós-mutação como argumentos:

const unsubscribe = store.subscribe((mutation, state) => {
  console.log(mutation.type)
  console.log(mutation.payload)
})

// you may call unsubscribe to stop the subscription
unsubscribe()

Por padrão, o novo manipulador é adicionado ao final da cadeia, então ele será executado após outros manipuladores que foram adicionados antes. Isso pode ser sobrescrito adicionando prepend: true a options, que irá adicionar o manipulador ao início da cadeia.

store.subscribe(handler, { prepend: true })

O método subscribe retornará uma função unsubscribe, que deve ser chamada quando a assinatura não for mais necessária. Por exemplo, você pode assinar um Módulo Vuex e cancelar a assinatura ao cancelar o registro do módulo. Ou você pode chamar subscribe de dentro de um componente Vue e então destruir o componente mais tarde. Nesses casos, você deve se lembrar de cancelar a assinatura manualmente.

Mais comumente usado em plugins. Detalhes

subscribeAction

  • subscribeAction(handler: Function, options?: Object): Function

Assinatura para as ações do store. O manipulador é chamado para cada ação despachada e recebe o descritor da ação e o estado de armazenamento atual como argumentos. O método subscribe retornará uma função unsubscribe, que deve ser chamada quando a assinatura não for mais necessária. Por exemplo, ao cancelar o registro de um módulo Vuex ou antes de destruir um componente Vue.

const unsubscribe = store.subscribeAction((action, state) => {
  console.log(action.type)
  console.log(action.payload)
})

// you may call unsubscribe to stop the subscription
unsubscribe()

Por padrão, o novo manipulador é adicionado ao final da cadeia, então ele será executado após outros manipuladores que foram adicionados antes. Isso pode ser sobrescrito adicionando prepend: true a options, que irá adicionar o manipulador ao início da cadeia.

store.subscribeAction(handler, { prepend: true })

O método subscribeAction retornará uma função unsubscribe, que deve ser chamada quando a assinatura não for mais necessária. Por exemplo, você pode assinar um Módulo Vuex e cancelar a assinatura ao cancelar o registro do módulo. Ou você pode chamar subscribeAction de dentro de um componente Vue e então destruir o componente mais tarde. Nesses casos, você deve se lembrar de cancelar a assinatura manualmente.

subscribeAction também pode especificar se a função manipuladora da assinatura deve ser chamada antes ou depois de um despacho de ação (o comportamento padrão é antes):

store.subscribeAction({
  before: (action, state) => {
    console.log(`before action ${action.type}`)
  },
  after: (action, state) => {
    console.log(`after action ${action.type}`)
  }
})

subscribeAction também pode especificar uma função manipuladora error para capturar um erro lançado quando uma ação é despachada. A função receberá um objeto error como 3º argumento.

store.subscribeAction({
  error: (action, state, error) => {
    console.log(`error action ${action.type}`)
    console.error(error)
  }
})

O método subscribeAction é mais comumente usado em plugins. Detalhes

registerModule

  • registerModule(path: string | Array<string>, module: Module, options?: Object)

Registra um módulo dinâmico. Detalhes

options podem ter preserveState: true que permite preservar o estado anterior. Bem útil quando fazemos renderização do lado do servidor (server-side-rendering).

unregisterModule

  • unregisterModule(path: string | Array<string>)

Cancela o registro de um módulo dinâmico. Detalhes

hasModule

  • hasModule(path: string | Array<string>): boolean

    Verifica se o módulo com o nome fornecido já foi registrado. Detalhes

hotUpdate

  • hotUpdate(newOptions: Object)

Faz hot swap de novas ações e mutações Detalhes

Métodos Auxiliares de Vinculação aos Componentes

mapState

  • mapState(namespace?: string, map: Array<string> | Object<string | function>): Object

Cria dados computados do componente que retornam a subárvore do store Vuex. Detalhes

O 1º argumento pode ser opcionalmente uma String com namespace. Detalhes

O segundo objeto que compõem os argumentos pode ser uma função. function(state: any)

mapGetters

  • mapGetters(namespace?: string, map: Array<string> | Object<string>): Object

Cria dados computados do componente que retornam o valor calculado de um getter. Detalhes

O 1º argumento pode ser opcionalmente uma String com namespace. Detalhes

mapActions

  • mapActions(namespace?: string, map: Array<string> | Object<string | function>): Object

Cria opções de métodos nos componentes que despacham uma ação. Detalhes

O 1º argumento pode ser opcionalmente uma String com namespace. Detalhes

O segundo objeto que compõem os argumentos pode ser uma função. function(dispatch: function, ...args: any[])

mapMutations

  • mapMutations(namespace?: string, map: Array<string> | Object<string | function>): Object

Cria opções de métodos nos componentes que confirmam (ou fazem um commit de) uma mutação. Detalhes

O 1º argumento pode ser opcionalmente uma String com namespace. Detalhes

O segundo objeto que compõem os argumentos pode ser uma função. function(commit: function, ...args: any[])

createNamespacedHelpers

  • createNamespacedHelpers(namespace: string): Object

Cria métodos auxiliares de componentes vinculados por um nome. O objeto retornado conterá mapState, mapGetters, mapActions e mapMutations, que estão vinculados ao namespace fornecido. Detalhes

Funções de Composição

useStore

  • useStore<S = any>(injectKey?: InjectionKey<Store<S>> | string): Store<S>;

    Busca o store injetado quando chamado dentro do gatilho (ou hook) setup. Ao usar a API de composição, você pode recuperar o store chamando este método.

    import { useStore } from 'vuex'
    
    export default {
      setup () {
        const store = useStore()
      }
    }
    

    Os usuários do TypeScript podem usar uma injection key para recuperar um store tipado. Para que isso funcione, você deve definir a injection key e passá-la junto com o store ao instalar a instância do store na aplicação Vue.

    Primeiro, declare a injection key usando a interface InjectionKey do Vue.

    // store.ts
    import { InjectionKey } from 'vue'
    import { createStore, Store } from 'vuex'
    
    export interface State {
      count: number
    }
    
    export const key: InjectionKey<Store<State>> = Symbol()
    
    export const store = createStore<State>({
      state: {
        count: 0
      }
    })
    

    Então, passe a key definida como o 2º argumento para o método app.use.

    // main.ts
    import { createApp } from 'vue'
    import { store, key } from './store'
    
    const app = createApp({ ... })
    
    app.use(store, key)
    
    app.mount('#app')
    

    Finalmente, você pode passar a key para o método useStore para recuperar a instância tipada do store.

    // no componente vue
    import { useStore } from 'vuex'
    import { key } from './store'
    
    export default {
      setup () {
        const store = useStore(key)
    
        store.state.count // tipado como número
      }
    }