Управление состоянием

Nuxt предоставляет композабл useState и интеграции с библиотеками управления состоянием для реактивного и SSR-совместимого общего состояния.

В Nuxt композабл useState создаёт реактивное общее состояние, совместимое с SSR.

useState — замена ref с учётом SSR: значение сохраняется после серверного рендеринга (при гидрации на клиенте) и разделяется между компонентами по уникальному ключу.

Данные в useState сериализуются в JSON, поэтому не должны содержать классы, функции или символы.
Подробнее о композабле useState.

Рекомендации

Не объявляйте const state = ref() вне <script setup> или функции setup(). Например, export myState = ref({}) приведёт к общему состоянию между запросами на сервере и утечкам памяти.
Используйте паттерн const useX = () => useState('x')

Примеры

Базовое использование

Локальный счётчик: любой компонент, вызывающий useState('counter'), разделяет то же реактивное состояние.

app/app.vue
<script setup lang="ts">
const counter = useState('counter', () => Math.round(Math.random() * 1000))
</script>

<template>
  <div>
    Counter: {{ counter }}
    <button @click="counter++">
      +
    </button>
    <button @click="counter--">
      -
    </button>
  </div>
</template>
Прочитайте и отредактируйте живой пример в Docs > 4 X > Examples > Features > State Management.
Для глобальной инвалидации кэша состояния см. утилиту clearNuxtState.

Инициализация состояния

Часто состояние нужно заполнить асинхронными данными. Используйте компонент app.vue и утилиту callOnce:

app/app.vue
<script setup lang="ts">
const websiteConfig = useState('config')

await callOnce(async () => {
  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
})
</script>
Похоже на экшен nuxtServerInit в Nuxt 2: заполнение начального состояния на сервере перед рендером.
Узнать больше Docs > 4 X > API > Utils > Call Once.

Использование с Pinia

Пример с модулем Pinia для глобального store:

Установите модуль: npx nuxt module add pinia или по инструкции модуля.
export const useWebsiteStore = defineStore('websiteStore', {
  state: () => ({
    name: '',
    description: '',
  }),
  actions: {
    async fetch () {
      const infos = await $fetch('https://api.nuxt.com/modules/pinia')

      this.name = infos.name
      this.description = infos.description
    },
  },
})

Продвинутое использование

import type { Ref } from 'vue'

export const useLocale = () => {
  return useState<string>('locale', () => useDefaultLocale().value)
}

export const useDefaultLocale = (fallback = 'en-US') => {
  const locale = ref(fallback)
  if (import.meta.server) {
    const reqLocale = useRequestHeaders()['accept-language']?.split(',')[0]
    if (reqLocale) {
      locale.value = reqLocale
    }
  } else if (import.meta.client) {
    const navLang = navigator.language
    if (navLang) {
      locale.value = navLang
    }
  }
  return locale
}

export const useLocales = () => {
  const locale = useLocale()
  const locales = ref([
    'en-US',
    'en-GB',
    // ...,
    'ja-JP-u-ca-japanese',
  ])
  if (!locales.value.includes(locale.value)) {
    locales.value.unshift(locale.value)
  }
  return locales
}

export const useLocaleDate = (date: Ref<Date> | Date, locale = useLocale()) => {
  return computed(() => new Intl.DateTimeFormat(locale.value, { dateStyle: 'full' }).format(unref(date)))
}
Прочитайте и отредактируйте живой пример в Docs > 4 X > Examples > Advanced > Locale.

Общее состояние

С автоимпортом композаблов можно задавать глобальные типизированные состояния и использовать их по всему приложению.

composables/states.ts
export const useColor = () => useState<string>('color', () => 'pink')
app/app.vue
<script setup lang="ts">
// ---cut-start---
const useColor = () => useState<string>('color', () => 'pink')
// ---cut-end---
const color = useColor() // То же, что useState('color')
</script>

<template>
  <p>Current color: {{ color }}</p>
</template>

Сторонние библиотеки

Раньше Nuxt использовал Vuex для глобального состояния. При миграции с Nuxt 2 см. руководство по миграции.

Nuxt не навязывает решение для состояния; можно выбрать любое. Есть интеграции с популярными библиотеками:

  • Pinia — официальная рекомендация Vue
  • Harlem — иммутабельное глобальное состояние
  • XState — конечные автоматы с визуализацией и тестами