react-use

react-use

该技能基于 react-use v17.6.0，生成于 2026-01-29。

react-use 是一系列必备 React Hooks 的集合，为 React 应用中的常见模式提供开箱即用的功能。它包含用于传感器、UI 交互、动画、副作用、生命周期管理和状态管理的 Hooks。

核心参考

主题	描述	参考
用法	导入模式与 tree-shaking 建议	core-usage

传感器

传感器 Hook 监听浏览器 API 和设备接口的变化，强制组件以更新后的状态重新渲染。

主题	描述	参考
useBattery	跟踪设备电池状态	sensors-battery
useGeolocation	跟踪用户设备的地理位置状态	sensors-geolocation
useHover	跟踪元素的鼠标悬停状态	sensors-hover
useHash	跟踪位置哈希值	sensors-hash
useIdle	跟踪用户是否处于非活动状态	sensors-idle
useIntersection	跟踪 HTML 元素的交叉状态	sensors-intersection
useKey	跟踪按键	sensors-key
useKeyPress	跟踪按键按下状态	sensors-key-press
useKeyPressEvent	处理按键按下事件	sensors-key-press-event
useKeyboardJs	跟踪键盘按键组合	sensors-keyboard-js
useLocation	跟踪页面导航栏位置状态	sensors-location
useSearchParam	跟踪 URL 搜索参数	sensors-search-param
useLongPress	跟踪长按手势	sensors-long-press
useMedia	跟踪 CSS 媒体查询的状态	sensors-media
useMediaDevices	跟踪已连接硬件设备的状态	sensors-media-devices
useMotion	跟踪设备运动传感器的状态	sensors-motion
useMouse	跟踪鼠标位置状态	sensors-mouse
useMouseWheel	跟踪滚动鼠标滚轮的 deltaY	sensors-mouse-wheel
useNetworkState	跟踪浏览器的网络连接状态	sensors-network-state
useOrientation	跟踪设备的屏幕方向	sensors-orientation
usePageLeave	当鼠标离开页面边界时触发	sensors-page-leave
useScratch	跟踪鼠标点击并拖拽的状态	sensors-scratch
useScroll	跟踪 HTML 元素的滚动位置	sensors-scroll
useScrolling	跟踪 HTML 元素是否正在滚动	sensors-scrolling
useStartTyping	检测用户何时开始输入	sensors-start-typing
useWindowScroll	跟踪 Window 滚动位置	sensors-window-scroll
useWindowSize	跟踪 Window 尺寸	sensors-window-size
useMeasure	跟踪 HTML 元素的尺寸	sensors-measure
useSize	跟踪元素大小	sensors-size
createBreakpoint	通过断点跟踪 innerWidth	sensors-breakpoint
useScrollbarWidth	检测浏览器原生滚动条宽度	sensors-scrollbar-width
usePinchZoom	跟踪指针事件以检测双指缩放	sensors-pinch-zoom

UI

UI hooks 允许你控制和订阅 UI 元素的状态变化。

主题	描述	参考
useAudio	播放音频并暴露其控件	ui-audio
useClickAway	当用户在目标区域外点击时触发回调	ui-click-away
useCss	动态调整 CSS	ui-css
useDrop	跟踪文件、链接和复制粘贴的拖放	ui-drop
useFullscreen	全屏显示元素或视频	ui-fullscreen
useSlider	为任意 HTML 元素提供滑动行为	ui-slider
useSpeech	从文本字符串合成语音	ui-speech
useVibrate	使用 Vibration API 提供物理反馈	ui-vibrate
useVideo	播放视频、跟踪其状态并暴露播放控件	ui-video

Animations

Animation hooks 通常随时间对数值进行插值。

主题	描述	参考
useRaf	在每个 requestAnimationFrame 上重新渲染组件	animations-raf
useInterval	按设定间隔重新渲染组件	animations-interval
useHarmonicIntervalFn	谐波间隔函数	animations-harmonic-interval
useSpring	根据弹簧动力学随时间对数值进行插值	animations-spring
useTimeout	在超时后重新渲染组件	animations-timeout
useTimeoutFn	在超时后调用给定函数	animations-timeout-fn
useTween	在将数值从 0 补间到 1 的过程中重新渲染组件	animations-tween
useUpdate	返回一个在被调用时重新渲染组件的回调	animations-update

副作用

副作用 Hook 允许你的应用使用浏览器 API 触发各种副作用。

主题	描述	参考
useAsync	解析一个异步函数	side-effects-async
useAsyncFn	可手动执行的异步函数	side-effects-async-fn
useAsyncRetry	具备重试能力的异步函数	side-effects-async-retry
useBeforeUnload	当用户尝试重新加载或关闭页面时显示浏览器警告	side-effects-before-unload
useCookie	提供读取、更新和删除 cookie 的方式	side-effects-cookie
useCopyToClipboard	将文本复制到剪贴板	side-effects-copy-to-clipboard
useDebounce	对函数进行防抖处理	side-effects-debounce
useError	错误分发器	side-effects-error
useFavicon	设置页面的 favicon	side-effects-favicon
useLocalStorage	管理 localStorage 中的一个值	side-effects-local-storage
useSessionStorage	管理 sessionStorage 中的一个值	side-effects-session-storage
useLockBodyScroll	锁定 body 元素的滚动	side-effects-lock-body-scroll
useRafLoop	在 RAF 循环中调用给定函数	side-effects-raf-loop
useThrottle	对函数进行节流处理	side-effects-throttle
useThrottleFn	节流函数变体	side-effects-throttle-fn
useTitle	设置页面的标题	side-effects-title
usePermission	查询浏览器 API 的权限状态	side-effects-permission

生命周期

生命周期 Hook 用于修改和扩展内置的 React Hook，或模拟 React Class 组件的生命周期模式。

Topic	Description	Reference
useEffectOnce	修改后的 useEffect，仅运行一次	lifecycles-effect-once
useEvent	订阅事件	lifecycles-event
useLifecycles	调用挂载和卸载回调	lifecycles-lifecycles
useMountedState	跟踪组件是否已挂载	lifecycles-mounted-state
useUnmountPromise	跟踪组件是否已挂载，支持 Promise	lifecycles-unmount-promise
usePromise	仅在组件挂载期间解析 Promise	lifecycles-promise
useLogger	在组件经历生命周期时输出到控制台	lifecycles-logger
useMount	调用挂载回调	lifecycles-mount
useUnmount	调用卸载回调	lifecycles-unmount
useUpdateEffect	仅在更新时运行 effect	lifecycles-update-effect
useIsomorphicLayoutEffect	可在服务端运行的 useLayoutEffect	lifecycles-isomorphic-layout-effect
useDeepCompareEffect	带深度比较的 useEffect	lifecycles-deep-compare-effect
useShallowCompareEffect	带浅比较的 useEffect	lifecycles-shallow-compare-effect
useCustomCompareEffect	带自定义比较函数的 useEffect	lifecycles-custom-compare-effect

状态

状态 Hook 让你可以轻松管理布尔值、数组和映射的状态。

主题	描述	参考
createMemo	记忆化 Hook 的工厂	state-create-memo
createReducer	带自定义中间件的 reducer Hook 工厂	state-create-reducer
createReducerContext	用于在组件之间共享状态的 Hook 工厂	state-create-reducer-context
createStateContext	用于在组件之间共享状态的 Hook 工厂	state-create-state-context
createGlobalState	跨组件共享状态	state-create-global-state
useDefault	当状态为 null 或 undefined 时返回默认值	state-default
useGetSet	返回状态 getter get() 而非原始状态	state-get-set
useGetSetState	useGetSet 与 useSetState 的组合	state-get-set-state
useLatest	返回最新的状态或 props	state-latest
usePrevious	返回先前的状态或 props	state-previous
usePreviousDistinct	类似 usePrevious，但带有一个谓词	state-previous-distinct
useObservable	跟踪 Observable 的最新值	state-observable
useRafState	创建仅在 requestAnimationFrame 之后更新的 setState 方法	state-raf-state
useSetState	创建行为类似 this.setState 的 setState 方法	state-set-state
useToggle	跟踪布尔值的状态	state-toggle
useCounter	跟踪数字的状态	state-counter
useList	跟踪数组的状态	state-list
useMap	跟踪对象的状态	state-map
useSet	跟踪 Set 的状态	state-set
useQueue	实现简单队列	state-queue
useStateList	循环遍历数组	state-state-list
useStateValidator	使用验证器函数验证状态	state-state-validator
useStateWithHistory	存储先前的状态值，并提供在这些值之间穿梭的句柄	state-state-with-history
useMultiStateValidator	类似 useStateValidator，但跟踪多个状态	state-multi-state-validator
useMediatedState	类似常规 useState，但通过自定义函数进行中介	state-mediated-state
useFirstMountState	检查当前渲染是否为首次渲染	state-first-mount-state
useRendersCount	统计组件渲染次数	state-renders-count
useMethods	useReducer 的简洁替代方案	state-methods

其他

主题	描述	参考
useEnsuredForwardedRef	安全地使用 React.forwardedRef	misc-ensured-forwarded-ref