ahooks-v3

技能：ahooks

适用范围

• 适用于：ahooks v3+ 中用于 React 状态管理、分组状态更新和 localStorage 持久化的实用 Hooks
• 不适用于：数据获取（使用 TanStack Query）、URL 状态管理（使用 nuqs）、复杂状态机、异步操作

假设条件

• ahooks v3+
• 支持 Hooks 的 React 18+
• TypeScript v5+（用于类型推断）
• 仅限客户端（Hooks 需要使用浏览器 API 来访问 localStorage）

原则

• 对于会一起变化的分组状态（不可通过 URL 分享），使用 useSetState
• 对于需要跨浏览器会话持久化的状态，使用 useLocalStorageState
• 对于可通过 URL 分享的状态，优先使用 nuqs，而非 localStorage
• 对于异步操作和加载状态，优先使用 TanStack Query
• 仅在简单且相互独立的状态下使用 useState（较少使用）

约束

必须

• 对于不在 URL 中的分组状态（表单状态、游戏引擎状态、临时 UI 状态），使用 useSetState
• 使用 useLocalStorageState 实现 localStorage 持久化

应当

• 对于可通过 URL 分享的状态，优先使用 nuqs，而非 localStorage
• 对于异步操作和加载状态，优先使用 TanStack Query
• 使用 TypeScript 泛型实现类型安全的状态：useLocalStorageState<boolean>('key', { defaultValue: false })

避免

• 用于 URL 状态（改用 nuqs）
• 用于加载／错误状态（改用 TanStack Query）
• 用于复杂异步操作（改用 TanStack Query）
• 在没有明确同步逻辑的情况下混用 URL 状态和 localStorage

交互

• 与 nuqs-v2 配合管理 URL 状态（可实现双向同步）
• 与 TanStack Query 配合处理异步操作（使用 TanStack Query 获取数据）
• 属于状态管理决策树的一部分（参见 React 规则）
• 适用于 React 18+ Hooks 架构

模式

useSetState 模式

用于会一起更新的分组状态：

import { useSetState } from 'ahooks'

const [state, setState] = useSetState({
  name: '',
  email: '',
  age: 0,
})

// Partial updates (shallow merge)
setState({ name: 'John' })
setState(prev => ({ ...prev, email: '[email protected]' }))

适用场景：表单状态、游戏引擎状态、会一起变化的 UI 状态（不可通过 URL 分享时）

不适用场景：可通过 URL 分享的状态（使用 nuqs）、加载状态（使用 TanStack Query）

useLocalStorageState 模式

用于需要跨浏览器会话持久化的状态：

import { useLocalStorageState } from 'ahooks'

const [value, setValue] = useLocalStorageState<boolean>('key', {
  defaultValue: false,
})

// Type-safe with generics
const [settings, setSettings] = useLocalStorageState<Settings>('settings', {
  defaultValue: { theme: 'light', fontSize: 14 },
})

适用场景：用户偏好设置、调试标记、需要跨会话持久化的设置

不适用场景：可通过 URL 分享的状态（使用 nuqs）、敏感数据（使用安全存储）

与 nuqs 集成

实现 URL 与 localStorage 之间的双向同步：

import { useLocalStorageState } from 'ahooks'
import { useQueryState } from 'nuqs'
import { useEffect, useRef } from 'react'

const [queryState, setQueryState] = useQueryState('debug')
const [storageState, setStorageState] = useLocalStorageState<boolean>('debug', {
  defaultValue: false,
})
const isFirstMount = useRef(true)

// Sync on mount: localStorage → URL
useEffect(() => {
  if (isFirstMount.current) {
    isFirstMount.current = false
    if (storageState && queryState !== 'true') {
      setQueryState('true')
      return
    }
  }
  // Sync changes: URL → localStorage
  if (queryState === 'true' && !storageState) {
    setStorageState(true)
  } else if (queryState === 'false' && storageState) {
    setStorageState(false)
  }
}, [queryState, storageState, setQueryState, setStorageState])

使用场景：需要既可通过 URL 分享又能持久化的调试标记、功能开关

状态管理决策树

1. 可通过 URL 分享的状态 → 使用 nuqs（筛选条件、搜索、标签页、分页）
2. 不在 URL 中的分组状态 → 使用 useSetState（表单状态、游戏引擎状态、临时 UI）
3. 异步操作 → 使用 TanStack Query（数据获取、变更、缓存）
4. localStorage 持久化 → 使用 useLocalStorageState（偏好设置、设置项）
5. 简单且相互独立的状态 → 使用 useState（较少使用，优先选择其他方案）

参考资料

• ahooks 文档 - 官方文档
• React 规则 - 状态管理决策树和模式
• TanStack Query - 异步操作和数据获取模式