ahooks-v3

用途

ahooks-v3 技能用于指导在 React 项目中正确使用 ahooks v3+ 的实用 Hooks 进行状态管理，重点解决两类问题：一是管理会一起变化的分组状态，二是将状态持久化到 localStorage。它同时明确了 ahooks 的适用边界，帮助开发者在多种状态管理方案之间做出选择。

适用范围与前提

该技能适用于 ahooks v3+ 的实用 Hooks，覆盖分组状态更新与 localStorage 持久化。它不覆盖数据获取（应使用 TanStack Query）、URL 状态管理（应使用 nuqs）、复杂状态机以及异步操作。

使用前提包括：ahooks v3+；React 18+ 且支持 Hooks；TypeScript v5+（用于类型推断）；仅限客户端使用，因为 Hooks 需要浏览器 API 来访问 localStorage。

主要能力与原则

技能给出的核心原则是：使用 useSetState 管理会一起变化的分组状态（不用于 URL 可共享的场景）；使用 useLocalStorageState 实现跨浏览器会话的持久状态；对于 URL 可共享状态，优先使用 nuqs 而非 localStorage；对于异步操作和加载状态，优先使用 TanStack Query；仅在简单且独立的状态场景下使用 useState（这种情况较少）。

使用方式

useSetState 模式

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

import { useSetState } from 'ahooks'

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

// 部分更新（浅合并）
setState({ name: 'John' })
setState(prev => ({ ...prev, email: 'john@example.com' }))

适用场景：表单状态、游戏引擎状态、会一起变化的 UI 状态（前提是这些状态不需要通过 URL 共享）。不适用场景：URL 可共享状态（应使用 nuqs）、加载状态（应使用 TanStack Query）。

useLocalStorageState 模式

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

import { useLocalStorageState } from 'ahooks'

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

// 使用泛型实现类型安全
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)

// 挂载时同步：localStorage → URL
useEffect(() => {
  if (isFirstMount.current) {
    isFirstMount.current = false
    if (storageState && queryState !== 'true') {
      setQueryState('true')
      return
    }
  }
  // 变更同步：URL → localStorage
  if (queryState === 'true' && !storageState) {
    setStorageState(true)
  } else if (queryState === 'false' && storageState) {
    setStorageState(false)
  }
}, [queryState, storageState, setQueryState, setStorageState])

使用场景：既需要 URL 可共享、又需要持久化的调试标志与功能开关。

状态管理决策树

URL 可共享状态 → 使用 nuqs（筛选、搜索、标签页、分页）
不在 URL 中的分组状态 → 使用 useSetState（表单状态、游戏引擎、临时 UI）
异步操作 → 使用 TanStack Query（数据获取、变更、缓存）
localStorage 持久化 → 使用 useLocalStorageState（偏好、设置）
简单独立状态 → 使用 useState（较少见，优先考虑其他方案）

约束与注意事项

必须：对不在 URL 中的分组状态（表单状态、游戏引擎状态、临时 UI 状态）使用 useSetState；对 localStorage 持久化使用 useLocalStorageState。

建议：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 架构配合使用。

限制

该技能仅限客户端使用，因为 localStorage 依赖浏览器 API。它不覆盖数据获取、URL 状态管理、复杂状态机与异步操作，这些场景应分别使用 TanStack Query 与 nuqs 等方案。关于具体版本兼容性、安装命令或更多 API 细节，资料中暂未提供。