Nuxt 3 已于 31 July 2026 结束生命周期
此版本将不再接收错误修复或安全补丁。 升级到 Nuxt 4 或获取 HeroDevs 提供的延长支持

useState

源码
useState 组合函数创建一个响应式且支持 SSR 的共享状态。

Maschinelle Übersetzung ·0 % geprüft

用法

// 创建一个响应式状态并设置默认值
const count = useState('counter', () => Math.round(Math.random() * 100))
Weitere Informationen findest du unter Docs > Getting Started > State Management.
由于 useState 内的数据会被序列化为 JSON，非常重要的一点是它不能包含无法序列化的内容，比如类、函数或符号。
useState 是被编译器转换的保留函数名，因此不应将自己的函数命名为 useState。

使用 shallowRef

如果你的状态不需要深度响应式，可以将 useState 和 shallowRef 结合使用。当你的状态包含大型对象和数组时，这样可以提升性能。

const state = useState('my-shallow-state', () => shallowRef({ deep: 'not reactive' }))
// isShallow(state) === true

类型

Signatur
export function useState<T> (init?: () => T | Ref<T>): Ref<T>
export function useState<T> (key: string, init?: () => T | Ref<T>): Ref<T>
  • key：一个唯一键，确保数据获取在多个请求间正确去重。如果未提供键，则会为你生成一个与 useState 实例所在文件及行号唯一对应的键。
  • init：当状态尚未初始化时，为其提供初始值的函数。此函数也可以返回一个 Ref。
  • T：（仅限 TypeScript）指定状态的类型

故障排除

Cannot stringify arbitrary non-POJOs

当你尝试使用 useState 存储不可序列化的内容（如类实例）时，会出现此错误。

如果你想使用 useState 存储 Nuxt 不支持的类实例，可以使用 definePayloadPlugin 为你的类添加自定义序列化器和反序列化器。

Weitere Informationen findest du unter Docs > API > Composables > Use Nuxt App#payload.