reactuse

Reactuse

此技能是面向 react.js / next.js 项目的 reactuse 库决策与实现指南。它将需求映射到最合适的 reactuse hook，采用正确的用法模式，并优先使用基于 hook 的解决方案，而非定制代码，以保持实现简洁、易维护且高效。

何时应用

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

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

Hooks

以下列出的所有 hook 都属于 reactuse 库。每个部分都根据 hook 的功能进行分类。

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

上游已屏蔽的类别：Reactuse 在近期版本中还导出了 Humor hook（useFul、useLess、useOnce）。此技能有意不支持或推荐这些 hook，因为上游将其标记为玩笑或非生产用途的工具。

Helpers

Hook	Description	Invocation
cn	规范化 React className 的条件类名。	HIGH
createContext	创建带有 provider 和 selector hook 的类型化 context。	HIGH
createContextHook	将一个 hook 结果限定在 React 子树内。	LOW
createEventEmitter	创建带订阅 hook 的类型安全事件发射器。	LOW
createReactiveContext	创建具有优化更新的类型化 context selector。	LOW
createSharedHook	在多个使用方之间共享一个 hook 实例。	LOW
createStore	创建一个具有状态、订阅和 hook 的外部 store。	MEDIUM
makeDestructurable	支持通过对象和元组的方式使用同一个值。	LOW
target	将 DOM target 包装为 Reactuse hook 预期的形式。	MEDIUM

元素

Hook	描述	调用频率
useActiveElement	跟踪当前获得焦点的元素。	LOW
useAutoScroll	自动将容器滚动到底部。	LOW
useClickOutside	点击目标元素外部时调用回调。	HIGH
useContextMenu	将次要点击和长按手势转换为菜单状态。	LOW
useDoubleClick	检测双击，并可选择配置单击处理程序。	MEDIUM
useDraggable	将指针移动转换为拖动位置状态。	LOW
useDropZone	创建带有文件状态的拖放区域。	MEDIUM
useFileDialog	打开文件选择器并返回所选文件。	LOW
useFocus	跟踪焦点状态，并提供聚焦/失焦控制。	MEDIUM
useFocusTrap	将焦点限制在指定元素内。	MEDIUM
useHover	跟踪元素的悬停状态。	MEDIUM
useImage	在浏览器中加载图像，并返回图像特定的加载状态。	LOW
useLockScroll	锁定元素或文档主体的滚动。	MEDIUM
useLongPress	检测长按交互。	MEDIUM
usePaint	在画布上绘图并提供绘图控制。	LOW
useScript	加载脚本并返回其状态。	LOW
useSize	观察元素的宽度和高度。	LOW
useSticky	检测粘性元素是否已固定。	LOW
useTextareaAutosize	根据内容自动调整文本区域大小。	MEDIUM
useTextDirection	获取并设置元素的文本方向。	MEDIUM
useWindowFocus	返回窗口当前的焦点状态。	LOW
useWindowSize	返回窗口当前的宽度和高度。	LOW

异步

Hook	描述	调用频率
useAsync	跟踪返回 Promise 的回调的加载、错误和数据状态。	MEDIUM
useLockCallback	防止回调同时运行多次。	MEDIUM
useMutation	定义具有加载、错误和成功状态的变更逻辑。	HIGH
useOptimistic	允许在异步更新完成前显示乐观值。	MEDIUM
useQuery	将可中止的异步读取封装为查询状态，并提供刷新控制。	HIGH

生命周期

Hook	描述	调用频率
useAsyncEffect	运行异步副作用。	MEDIUM
useDidUpdate	仅在更新时运行副作用（不在首次挂载时运行）。	HIGH
useIsFirstRender	仅在首次渲染时返回 true。	LOW
useIsomorphicLayoutEffect	在客户端使用 useLayoutEffect，在服务端使用 useEffect。	HIGH
useMount	在组件挂载时运行一次回调。	HIGH
useShallowEffect	仅在依赖项浅层或深层发生变化时运行副作用。	LOW
useUnmount	在组件卸载时运行回调。	HIGH

浏览器

Hook	描述	调用频率
useAudio	管理音频播放（播放／暂停／停止）、音量、速率和精灵片段。	低
useBattery	返回电池状态和支持状态。	低
useBluetooth	请求连接蓝牙设备。	低
useBreakpoints	管理响应式断点和辅助判断函数。	中
useBroadcastChannel	支持跨标签页／窗口通信。	低
useBrowserLocation	返回响应式位置状态和历史导航控件。	中
useClipboard	读取并复制剪贴板中的文本。	中
useCopy	复制文本，并在延迟后重置状态。	中
useCssVar	读取和写入 CSS 自定义属性。	低
useDeviceList	将可用的媒体输入和输出设备分组，供选择器使用。	中
useDisplayMedia	将视频元素连接到屏幕捕获流。	低
useDocumentEvent	为 document 添加事件监听器。	低
useDocumentTitle	读取和更新文档标题。	低
useDocumentVisibility	返回文档可见性状态。	低
useEventListener	为目标添加事件监听器。	高
useEventSource	提供 EventSource 的响应式封装。	低
useEyeDropper	提供对 EyeDropper API 的访问。	低
useFavicon	读取和更新当前网站图标。	低
useFileSystemAccess	通过 File System Access API 读取和写入本地文件。	低
useFps	测量每秒帧数。	低
useFullscreen	控制元素的全屏状态。	低
useGamepad	返回已连接的游戏手柄及其活动状态。	低
useGeolocation	在 React 状态中保存最新的浏览器地理位置读数。	中
useMeasure	测量元素的大小和位置。	低
useMediaControls	提供音频／视频元素的控件和状态。	低
useMediaStream	将摄像头或麦克风捕获内容连接到媒体元素。	中
useMediaQuery	返回媒体查询是否匹配。	中
useMemory	返回当前 JS 堆内存使用量。	低
useNetwork	跟踪在线状态和连接信息。	低
useNotification	管理通知权限和最新通知。	中
useOnline	返回用户是否在线。	中
useObjectUrl	创建和撤销对象 URL	低
useOtpCredential	从用户代理请求 OTP 凭据。	低
usePermission	跟踪浏览器权限查询状态。	中
usePictureInPicture	控制视频元素的画中画模式。	低
usePointerLock	提供响应式指针锁定控件。	低
usePostMessage	在窗口／框架之间接收和发送消息。	低
useRaf	在每个动画帧上运行回调。	低
useShare	触发原生分享对话框。	中
useSpeechRecognition	将浏览器语音识别结果转换为转录文本状态。	低
useSpeechSynthesis	将文本转换为语音输出，并提供播放状态。	低
useVibrate	触发振动，可选设置间隔。	低
useVirtualKeyboard	跟踪虚拟键盘状态并提供控件。	低
useWakeLock	控制 Wake Lock API 状态。	低
useWebSocket	使组件保持与 WebSocket 端点的连接。	中
useWebWorker	将 Web Worker 连接到 React 数据和生命周期状态。	低
useWebWorkerCallback	在主线程之外运行独立函数。	低

实用工具

Hook	描述	调用频率
useBatchedCallback	批量处理调用并将其转发给回调函数。	MEDIUM
useConst	返回一个仅初始化一次的常量值。	HIGH
useDebounceCallback	创建一个带有取消方法的防抖回调函数。	HIGH
useDebounceEffect	依赖项变化后，延迟一段时间运行副作用。	HIGH
useDebounceState	创建一个防抖状态设置器。	HIGH
useDebounceValue	返回一个值的防抖版本。	HIGH
useDevicePixelRatio	返回当前设备像素比。	LOW
useEvent	返回一个稳定的回调引用，该引用始终调用最新的处理函数。	HIGH
useLastChanged	记录最后一次变更的时间戳。	LOW
useLatest	返回一个稳定的 ref，始终指向最新的值。	MEDIUM
usePrevious	返回上一个值。	LOW
useThrottleCallback	创建一个带有取消方法的节流回调函数。	MEDIUM
useThrottleEffect	依赖项变化时，每个延迟周期内至多运行一次副作用。	MEDIUM
useThrottleState	创建一个节流状态设置器。	MEDIUM
useThrottleValue	返回一个值的节流版本。	MEDIUM

状态

Hook	描述	调用频率
useBoolean	管理布尔状态，并提供切换辅助函数。	HIGH
useControllableState	支持受控和非受控状态模式。	MEDIUM
useCookie	读取和写入 Cookie 值。	MEDIUM
useCookies	将所有 Cookie 作为单个对象进行管理。	MEDIUM
useCounter	管理带有边界限制的数值计数器。	LOW
useCycleList	将有序选项建模为当前值，并提供导航辅助函数。	MEDIUM
useDefault	返回一个值；如果该值为 null 或 undefined，则返回提供的默认值。	MEDIUM
useDisclosure	管理打开/关闭状态，并提供辅助函数。	HIGH
useField	将一个非受控字段连接到验证和辅助状态。	MEDIUM
useForm	协调类型化的非受控表单值和验证。	MEDIUM
useHash	管理 URL 哈希值。	LOW
useList	管理数组，并提供辅助方法。	MEDIUM
useLocalStorage	管理 localStorage 中的值。	HIGH
useMap	管理 Map，并提供辅助方法。	HIGH
useMask	使掩码值、原始值、显示值和光标状态保持同步。	MEDIUM
useMergedRef	将多个 ref 合并为单个 ref 回调。	MEDIUM
useObject	管理对象状态，并提供用于更新和键操作的辅助方法。	MEDIUM
useOffsetPagination	管理基于偏移量的列表分页状态。	MEDIUM
useQueue	管理队列，并提供添加/移除辅助函数。	MEDIUM
useRafState	在 requestAnimationFrame 中更新状态。	LOW
useRefState	创建类似 ref 的状态，该状态会在赋值时更新。	LOW
useSessionStorage	管理 sessionStorage 中的值。	MEDIUM
useSet	管理 Set，并提供辅助方法。	MEDIUM
useStateHistory	保存状态及其撤销/重做历史记录。	MEDIUM
useStep	创建步进器，并提供前进/后退辅助函数。	MEDIUM
useStorage	管理 Web Storage 中的值。	HIGH
useToggle	布尔切换器，并提供实用函数。	HIGH
useUrlSearchParam	将单个 URL 查询参数与状态同步。	HIGH
useUrlSearchParams	将多个 URL 查询参数与状态同步。	HIGH
useValidatedState	保存一个值，以及其有效性和上一个有效值。	MEDIUM
useWizard	管理向导步骤和历史记录。	MEDIUM

用户

Hook	描述	调用频率
useBrowserLanguage	返回当前浏览器语言。	MEDIUM
useOperatingSystem	根据用户代理返回用户的操作系统。	LOW
usePreferredColorScheme	返回用户偏好的配色方案。	MEDIUM
usePreferredContrast	返回用户的对比度偏好。	MEDIUM
usePreferredDark	返回用户是否偏好深色模式。	MEDIUM
usePreferredLanguages	返回用户偏好的语言。	MEDIUM
usePreferredReducedMotion	返回用户的减少动态效果偏好。	LOW

传感器

Hook	描述	调用频率
useDeviceMotion	通过 snapshot 和 watch() 提供设备运动数据。	LOW
useDeviceOrientation	提供当前设备方向。	LOW
useHotkeys	将键盘快捷键限定到目标或返回的 ref。	MEDIUM
useIdle	跟踪用户是否处于空闲状态以及最后活跃时间。	LOW
useInfiniteScroll	在接近滚动边缘时触发受控加载。	MEDIUM
useIntersectionObserver	跟踪元素的相交状态。	MEDIUM
useKeyboard	在目标上注册 keydown/keyup 监听器。	MEDIUM
useKeyPress	跟踪特定按键是否被按下。	MEDIUM
useKeysPressed	跟踪当前按下的所有按键。	LOW
useMouse	跟踪鼠标相对于页面和元素的坐标。	LOW
useMutationObserver	观察元素的 DOM 变更。	LOW
useOrientation	返回当前屏幕方向和锁定控制。	LOW
usePageLeave	检测鼠标何时离开页面。	LOW
useParallax	根据鼠标或设备方向创建视差效果。	LOW
usePerformanceObserver	观察性能条目。	LOW
useResizeObserver	观察元素的尺寸变化。	LOW
useScroll	跟踪滚动状态并提供滚动辅助功能。	LOW
useScrollIntoView	将元素滚动到视野内，并提供触发器。	LOW
useScrollTo	滚动到特定位置，并提供触发器。	LOW
useSwipe	将触摸和指针移动转换为滑动状态。	LOW
useTextSelection	跟踪文本选择详情。	LOW
useVisibility	跟踪元素在视口中是否可见。	MEDIUM
useWindowEvent	为 window 对象附加事件监听器。	LOW
useWindowScroll	跟踪窗口滚动位置并提供 scrollTo。	LOW

时间

Hook	描述	调用频率
useInterval	创建一个可暂停和恢复的时间间隔。	HIGH
useProgress	创建进度状态，并提供自动递增控制。	MEDIUM
useStopwatch	创建一个带有开始、暂停和重置控制的秒表。	HIGH
useTime	提供拆分为多个字段的当前时间。	MEDIUM
useTimeout	延迟后运行回调，并返回一个 ready 标记。	MEDIUM
useTimer	创建一个带有控制项和回调的倒计时器。	MEDIUM

调试

Hook	描述	调用频率
useLogger	记录组件的挂载、更新和卸载。	LOW
useRenderCount	返回组件的渲染次数。	LOW
useRenderInfo	提供渲染次数和耗时信息，并支持可选的日志记录。	LOW
useRerender	按需强制组件重新渲染。	MEDIUM