react-use-hooks

React-Use Hooks

本技能是 React 项目中 react-use hooks 的决策与实现指南。它会将需求映射到最合适的 react-use hook，采用正确的用法模式，并优先选择基于 hook 的解决方案，而非专门编写代码，以保持实现简洁、易于维护且高效。

适用时机

• 在协助用户进行 React 开发时应用此技能。
• 始终先检查是否可以使用 react-use hook 实现需求。
• 优先使用 react-use hooks，而不是自定义代码，以提升可读性、可维护性和性能。
• 将需求映射到最合适的 hook，并遵循该 hook 的调用规则。
• 请参阅下方 hooks 表格中的 Invocation 字段。例如：
  • AUTO：适用时自动使用。
  • EXTERNAL：仅当用户已安装所需的外部依赖时使用；否则应重新考虑，只有确实需要时才询问用户是否安装。
  • EXPLICIT_ONLY：仅在用户明确要求时使用。

  注意：提示词或 AGENTS.md 中的用户指令可能会覆盖 hook 默认的 Invocation 规则。

Hooks

以下列出的所有 hooks 都属于 react-use 库，各章节按功能对 hooks 进行分类。

重要：每个 hook 条目都包含简短的 Description 和详细的 Reference。使用任何 hook 时，务必查阅 ./references 中对应的文档，了解用法详情和类型声明。

传感器

Hook	描述	调用方式
createBreakpoint	laptopL: 1440，laptop: 1024，tablet: 768	AUTO
useBattery	跟踪电池状态的 React 传感器 Hook。	AUTO
useGeolocation	跟踪用户地理位置的 React 传感器 Hook。此 Hook 接受[位置选项](https	AUTO
useHash	跟踪浏览器位置哈希的 React 传感器 Hook。	AUTO
useHover	跟踪某个元素是否处于悬停状态的 React UI 传感器 Hook	AUTO
useHoverDirty	使用 ref 跟踪鼠标悬停状态（比 useHover 更直接）。	AUTO
useIdle	跟踪页面上的用户是否处于空闲状态的 React 传感器 Hook。	AUTO
useIntersection	跟踪目标元素与祖先元素相交状态变化的 React 传感器 Hook	AUTO
useKey	按下键盘按键时执行 handler 的 React UI 传感器 Hook。	AUTO
useKeyboardJs	检测复杂按键组合的 React UI 传感器 Hook，例如检测	EXTERNAL
useKeyPress	检测用户何时按下特定按键的 React UI 传感器 Hook	AUTO
useKeyPressEvent	此 Hook 会触发 keydown 和 keyup 回调，类似于 useKey	AUTO
useLocation	跟踪浏览器位置的 React 传感器 Hook。	AUTO
useLongPress	长按后触发回调的 React 传感器 Hook。	AUTO
useMeasure	使用 [Resize Observer API](https:// 跟踪 HTML 元素尺寸的 React 传感器 Hook	AUTO
useMedia	跟踪 CSS 媒体查询状态的 React 传感器 Hook。	AUTO
useMediaDevices	跟踪已连接硬件设备的 React 传感器 Hook。	AUTO
useMotion	使用设备的加速度传感器跟踪其运动的 React 传感器 Hook。	AUTO
useMouse	鼠标位置变化时重新渲染的 React 传感器 Hook。useMouse 只跟踪	AUTO
useMouseHovered	扩展鼠标跟踪功能，支持限定坐标范围和仅在悬停时跟踪。	AUTO
useMouseWheel	获取鼠标在窗口中滚动时 deltaY 值的 React Hook。	AUTO
useNetworkState	跟踪浏览器网络连接状态。	AUTO
useOrientation	跟踪用户设备屏幕方向的 React 传感器 Hook。	AUTO
usePageLeave	鼠标离开页面时触发回调的 React 传感器 Hook。	AUTO
usePinchZoom	跟踪指针触摸事件变化并检测捏合差值的 React 传感器 Hook	AUTO
useScratch	跟踪鼠标“擦动”（或“抓挠”）状态的 React 传感器 Hook。	AUTO
useScroll	DOM 元素中的滚动位置变化时重新渲染的 React 传感器 Hook。	AUTO
useScrollbarWidth	返回当前浏览器滚动条宽度的 Hook。	AUTO
useScrolling	跟踪用户是否正在滚动的 React 传感器 Hook。	AUTO
useSearchParam	跟踪浏览器位置搜索参数的 React 传感器 Hook。	AUTO
useSize	跟踪 HTML 元素尺寸的 React 传感器 Hook。	AUTO
useStartTyping	用户开始输入时触发回调的 React 传感器 Hook。可用于	AUTO
useWindowScroll	窗口滚动时重新渲染的 React 传感器 Hook。	AUTO
useWindowSize	跟踪浏览器窗口尺寸的 React 传感器 Hook。	AUTO

UI

Hook	描述	调用方式
useAudio	创建 <audio> 元素，跟踪其状态并提供播放控制功能。	AUTO
useClickAway	React UI Hook，用户	AUTO
useCss	React UI Hook，可动态更改 [CSS][gen-5]。其作用类似于“虚拟 CSS” —	AUTO
useDrop	在拖放文件、链接以及复制粘贴时触发。	AUTO
useFullscreen	让元素全屏显示，可选在 iOS 上为全屏视频提供回退方案。	AUTO
useSlider	React UI Hook，可让任意 HTML 元素具备滑动行为。支持鼠标和触摸，还	AUTO
useSpeech	React UI Hook，可合成人声朗读给定字符串。	AUTO
useVibrate	React UI Hook，使用 [Vibration API]( 通过设备的振动硬件提供物理反馈	AUTO
useVideo	创建 <video> 元素，跟踪其状态并提供播放控制功能。	AUTO

动画

Hook	描述	调用方式
useHarmonicIntervalFn	与 useInterval Hook 相同，但会以相同的延迟触发所有效果	AUTO
useInterval	基于 [Dan Abramov 在 overreacted.io 上的文章](https://overreacted.i 的声明式间隔 Hook	AUTO
useRaf	React 动画 Hook，每次 requestAnimationFrame 时强制组件重新渲染，	AUTO
useSpring	React 动画 Hook，会随时间更新单个数值	EXTERNAL
useTimeout	指定毫秒数后重新渲染组件。	AUTO
useTimeoutFn	在指定毫秒数后调用给定函数。	AUTO
useTween	React 动画 Hook，可在 0 到 1 之间补间一个数值。	AUTO
useUpdate	React 工具 Hook，返回一个强制组件	AUTO

副作用

Hook	描述	调用方式
useAsync	React Hook，可解析 async 函数或返回	AUTO
useAsyncFn	React Hook，为 async 函数返回状态和回调，或	AUTO
useAsyncRetry	使用 useAsync，并添加 retry 方法，以便轻松重试/刷新异步函数；	AUTO
useBeforeUnload	React 副作用 Hook，当用户尝试重新加载或关闭页面时显示浏览器警告。	AUTO
useCookie	React Hook，返回当前 cookie 值以及用于更新 cookie 的回调	AUTO
useCopyToClipboard	将文本复制到用户的剪贴板。	AUTO
useDebounce	React Hook，在距上次调用经过指定等待毫秒数后再调用函数	AUTO
useError	React 副作用 Hook，返回一个错误调度器。	AUTO
useFavicon	React 副作用 Hook，设置页面的 favicon。	AUTO
useLocalStorage	React 副作用 Hook，管理单个 localStorage 键。	AUTO
useLockBodyScroll	React 副作用 Hook，锁定 body 元素的滚动。适用于模态框和其他覆盖层	AUTO
usePermission	React 副作用 Hook，用于查询浏览器 API 的权限状态。	AUTO
useRafLoop	此 Hook 在 RAF 循环中调用给定函数，而不会让父组件重新渲染。	AUTO
useSessionStorage	React 副作用 Hook，管理单个 sessionStorage 键。	AUTO
useThrottle	用于节流的 React Hook。	AUTO
useThrottleFn	React Hook，调用函数后延迟后续函数调用，直到经过指定等待毫秒数	AUTO
useTitle	React 副作用 Hook，设置页面标题。	AUTO

生命周期

钩子	描述	调用方式
useCustomCompareEffect	修改版的 useEffect 钩子，接受一个比较器，用于比较依赖项中的	AUTO
useDeepCompareEffect	修改版的 useEffect 钩子，对依赖项进行深度比较，而不是引用相等	AUTO
useEffectOnce	React 生命周期钩子，只运行一次 effect。	AUTO
useEvent	React 传感器钩子，用于将 handler 订阅到事件。	AUTO
useIsomorphicLayoutEffect	useLayoutEffect，在服务端渲染时不会显示警告，参见 [Alex Reardon 的文章	AUTO
useLifecycles	React 生命周期钩子，在组件	AUTO
useLogger	React 生命周期钩子，在组件经历各个生命周期时将参数记录到控制台。	AUTO
useMount	React 生命周期钩子，在组件挂载后调用函数。如果你	AUTO
useMountedState	> 注意！： 尽管名称中有 State，此钩子不会导致组件重新渲染。	AUTO
usePromise	React 生命周期钩子，返回一个用于包装 promise 的辅助函数。	AUTO
useShallowCompareEffect	修改版的 useEffect 钩子，对每个依赖项进行浅比较，而不是引用	AUTO
useUnmount	React 生命周期钩子，在组件即将卸载时调用函数。如果你	AUTO
useUnmountPromise	生命周期钩子，提供一个高阶 promise，在组件卸载时不会解析。	AUTO
useUpdateEffect	React effect 钩子，忽略首次调用（例如挂载时）。其签名与	AUTO

状态

Hook	描述	调用方式
createGlobalState	用于创建全局共享状态的 React Hook。	AUTO
createMemo	Hook 工厂，接收一个要记忆化的函数，并返回一个记忆化的 React Hook。	AUTO
createReducer	用于创建带自定义中间件的 reducer Hook 的工厂，其 API 与 [React 的 useReducer](htt 相同	AUTO
createReducerContext	用于创建行为与 [React 的 useReducer](https://reactjs.or 一致的 React context Hook 的工厂	AUTO
createStateContext	用于创建行为与 [React 的 useState](https://reactjs.org/ 一致的 React context Hook 的工厂	AUTO
useBoolean	useToggle 的别名。提供切换函数的布尔状态 Hook。	AUTO
useCounter	用于跟踪数值的 React 状态 Hook。	AUTO
useDefault	当状态为 null 或 undefined 时返回默认值的 React 状态 Hook。	AUTO
useFirstMountState	如果组件刚刚挂载（首次渲染），则返回 true；否则返回 false。	AUTO
useGetSet	返回状态获取函数而不是	AUTO
useGetSetState	useGetSet 和 useGetSetState 的组合。	AUTO
useLatest	返回最新状态的 React 状态 Hook，详见 [React Hook 常见问题解答](https://reactjs	AUTO
useList	跟踪数组并提供修改数组的方法。	AUTO
useMap	跟踪对象值的 React 状态 Hook。	AUTO
useMediatedState	与标准 useState 非常相似，但加入了中介处理过程。	AUTO
useMethods	简化 useReducer 实现的 React Hook。	AUTO
useMultiStateValidator	每当给定状态中的任一状态发生变化时，都会调用验证函数。	AUTO
useNumber	useCounter 的别名。提供实用函数的数值计数器状态。	AUTO
useObservable	跟踪 Observable 最新值的 React 状态 Hook。	EXTERNAL
usePrevious	返回先前状态的 React 状态 Hook，详见 [React Hook 常见问题解答](https://react	AUTO
usePreviousDistinct	与 usePrevious 类似，但仅在值实际发生变化时才更新。这一点很重要	AUTO
useQueue	实现简单 FIFO 队列的 React 状态 Hook。	AUTO
useRafState	仅在 [requestAnimationFrame](https://develo 回调中更新状态的 React 状态 Hook	AUTO
useRendersCount	跟踪组件的渲染次数，包括首次渲染。	AUTO
useSet	跟踪 [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Referen 的 React 状态 Hook	AUTO
useSetState	创建 setState 方法的 React 状态 Hook，其工作方式类似于	AUTO
useStateList	提供用于循环遍历状态列表的操作句柄。	AUTO
useStateValidator	每当给定状态发生变化时，都会调用验证函数。	AUTO
useStateWithHistory	保存指定数量的先前状态值，并提供用于在这些状态值之间切换的操作句柄。	AUTO
useToggle	跟踪布尔值的 React 状态 Hook。	AUTO

其他

Hook	描述	调用方式
useEnsuredForwardedRef	用于安全使用 ForwardedRef 的 React Hook。	AUTO