状态管理类

函数	用途	跨组件共享	SSR 安全	可修改
useState	运行时状态	✅ 相同 key 共享	✅	✅
useAppConfig	应用配置	✅ 全局	✅	✅ 通过 updateAppConfig

useState

SSR 安全的跨组件共享状态。相同 key 的 useState 在所有组件中共享同一份状态。

// 基本用法
const count = useState('counter', () => 0)

// 带类型
const user = useState<User | null>('user', () => null)

// 读取和修改
count.value++
console.log(count.value)

// 跨组件共享（相同 key 共享同一状态）
// 组件 A
const count = useState('counter', () => 0)
// 组件 B
const count = useState('counter', () => 0)  // 获取同一个状态

第二个参数是初始化函数

只在首次创建时调用。后续组件使用相同 key 时，直接返回已有状态。

INFO

️ 不要用普通的 ref 替代 useState

• ref：组件内状态，SSR 时数据不传递
• useState：全局共享状态，SSR 时自动通过 Payload 传递

常见模式

// 全局用户状态
const user = useState<User | null>('user', () => null)

// 全局购物车
const cart = useState<CartItem[]>('cart', () => [])

// 全局主题
const theme = useState<'light' | 'dark'>('theme', () => 'light')

useAppConfig

获取应用配置（app.config.ts 中定义）。

const appConfig = useAppConfig()

console.log(appConfig.theme.primaryColor)
console.log(appConfig.layout.sidebarWidth)

配合 app/app.config.ts：

export default defineAppConfig({
  theme: {
    primaryColor: '#00DC82',
    darkMode: false,
  },
  layout: {
    sidebarWidth: 240,
  },
})

useState vs useAppConfig

特性	useState	useAppConfig
可修改	✅ 直接赋值	✅ 通过 updateAppConfig()
跨组件共享	✅ 相同 key	✅ 全局
定义位置	组件中	app.config.ts
构建时配置	❌	✅
环境变量覆盖	❌	❌（用 runtimeConfig）
适用场景	运行时状态	主题/布局配置

选择原则

• 运行时变化的业务数据 → useState
• 主题、布局等配置 → useAppConfig
• 环境变量 → useRuntimeConfig