
react-use 版本演进全解析从 1.0.0 到 17.6.1 的变更日志深度解读【免费下载链接】react-useReact Hooks — 项目地址: https://gitcode.com/gh_mirrors/re/react-usereact-use 是一套开箱即用的 React Hooks 集合仓库 package.json 中描述为 Collection of React Hooks自 2018 年 10 月发布 1.0.0 以来持续迭代至今。本文以仓库根目录的 CHANGELOG.md 为骨架逐版本梳理 react-use 的功能新增、Bug 修复与破坏性变更Breaking Changes并结合 src 目录下的源码实现帮助你理解每个 Hook 的演进脉络、API 变迁原因以及升级版本时需要关注的兼容性要点。读完本文你将能快速定位某个 Hook 引入的版本、判断升级风险并理解 react-use 内部架构重组的关键节点。一、版本发布节奏与工程化基础CHANGELOG.md 记录了从 1.0.02018-10-28到 17.6.12026-06-10的完整历史共跨越约 8 年、数十个版本。从提交信息格式如feat、fix、BREAKING CHANGES标记可以看出项目采用 Conventional Commits 规范配合 package.json 中配置的semantic-release自动生成版本号与变更日志release脚本为semantic-release发布分支包括master与预发布分支nextprerelease 为rc使用semantic-release/changelog、semantic-release/npm、semantic-release/git三个插件分别维护 CHANGELOG、发布 npm 包、提交版本信息。这正是 CHANGELOG.md 中每个版本都带有compare/vX...vY比较链接和提交哈希的原因——日志是语义化发布流程的自动化产物。仓库当前的入口导出集中维护在 src/index.ts其中可以看到大多数 Hook 的默认导出而useKeyboardJs与useSpring因依赖较大的第三方库被注释掉需要单独引入对应 CHANGELOG 10.0.0 中从 peerDependencies 中移除大体积库的破坏性变更。二、v17 时代稳定性维护与 React 18 适配v17 系列是当前最新的主版本线从 17.0.02021-01-31到 17.6.12026-06-10核心工作集中在适配 React 生态变化与少量 API 调整。17.0.0useNetwork 正式更名为 useNetworkState17.0.0 是一次破坏性变更useNetwork钩子被重命名为useNetworkState源码见 src/useNetworkState.ts。该 Hook 返回一个包含联网状态的对象online浏览器是否联网boolean | undefinedprevious上一次的online值用于判断刚连接还是刚断开since状态变化发生的Date对象downlink/downlinkMax估算带宽MbpseffectiveType连接类型slow-2g | 2g | 3g | 4grtt估算往返时延毫秒saveData用户是否开启省流量模式type底层连接类型bluetooth、cellular、ethernet、none、wifi、wimax、other、unknown。实现上它监听window的online/offline事件并兼容navigator.connection、navigator.mozConnection、navigator.webkitConnection的change事件源码 src/useNetworkState.ts。17.3.xuseAudio 增加 playing 状态性能优化17.3.0 为useAudio增加了playing状态此前媒体类 Hook 仅返回paused见 12.0.0 的破坏性变更说明。17.3.1 则优化了useTitle仅在标题真正变化时才更新 DOM。这两个 Hook 分别由createHTMLMediaHook工厂src/factory/createHTMLMediaHook.ts和 src/useTitle.ts 实现。17.4.x 与 17.5.x新能力与依赖修正17.4.0 新增usePinchZoom传感器 Hook用于监听双指缩放手势实现见 src/usePinchZoom.ts17.4.1、17.5.1 两次升级nano-css依赖服务于useCss等样式相关 Hook17.5.0 为useStateList增加isFirst与isLast返回值。useStateList的完整返回结构在 src/useStateList.ts 中定义state、currentIndex、setStateAt、setState、next、prev、isFirst、isLast。值得注意的实现细节是setStateAt支持越界回绕——索引为负数时从右侧倒数超过列表长度时取模回到前面src/useStateList.ts。17.6.xuseWindowSize 的 onChange 回调与依赖升级17.6.0 为useWindowSize新增onChange回调17.6.1 将js-cookie升级到 v3服务于useCookie。当前版本 src/useWindowSize.ts 的完整签名如下interface Options { initialWidth?: number; // 默认 Infinity initialHeight?: number; // 默认 Infinity onChange?: (width: number, height: number) void; // 窗口尺寸变化时回调 } const useWindowSize ({ initialWidth Infinity, initialHeight Infinity, onChange }: Options {});其内部使用useRafState管理状态通过requestAnimationFrame节流 resize 事件并仅在isBrowser为真时挂载/解绑事件监听src/useWindowSize.ts这是它 SSR 友好的关键。17.3.3React 18 类型适配17.3.3 解决了types/react18的破坏性变更React.FC类型调整并移除了对 React 版本的过旧 peer 依赖限制。升级到 v17 后配合 React 18 使用已无障碍。三、v16目录架构重组16.0.0 是一次典型的结构性破坏性变更不改变功能但改变导入路径所有create*工厂函数被移入factory子目录直接导入时应写为react-use/esm/factory/createBreakpoint形式目录comps更名为component。对应到当前仓库结构工厂类 Hook 统一位于 src/factory 下createBreakpoint、createGlobalState、createHTMLMediaHook、createMemo、createReducer、createReducerContext、createRenderProp、createRouter、createStateContext。如果你在旧代码中使用了react-use/esm/createReducer之类的路径升级后需要按新路径调整。四、v15useMeasure 与 useLocalStorage 的重写15.0.0 是 v17 之前影响面最大的一次破坏性版本主要围绕两个高频 HookuseMeasure 全面重构不再使用resize-observer-polyfill包改为直接依赖原生ResizeObserver默认值从全零改为-1若浏览器不支持或未测量到值在服务端SSR以及没有ResizeObserver的环境中会回退为 noop 实现。当前源码 src/useMeasure.ts 印证了这一设计模块导出时即判断isBrowser typeof window.ResizeObserver ! undefined否则导出返回[noop, defaultState]的占位函数。defaultState中x/y/width/height/top/left/bottom/right均为0——注意这与 CHANGELOG 描述的 -1 默认值存在差异说明后续版本又对默认值做了调整15.0.3 的 typings 修正与 17.2.1 的 SVG 类型支持也与此相关。useLocalStorage 能力增强支持自定义serializer/deserializer13.18.0 引入空值使用undefined而非null新增remove功能可从返回值中解构出第三个元素改进序列化处理与 SSR 兼容。当前实现 src/useLocalStorage.ts 返回[state, set, remove]三元组支持raw: true模式不经过 JSON 序列化和自定义序列化函数并且在 key 变化时通过useLayoutEffect重新初始化对应 17.2.4 的 reinitialize on key change 修复。15.x 其他亮点15.1.0 新增useLatest用于始终持有最新值的 ref实现见 src/useLatest.ts15.2.0 新增useMouseWheel滚轮传感器 Hook15.3.0 重做usePrevious更省内存15.3.1 又因 issue #1315 回退了重写版本15.3.8 改进useStateValidator与useMultiStateValidator的类型定义。五、v13–v14功能爆发期这一阶段2019 年底到 2020 年中是 react-use 新增 Hook 最密集的时期绝大多数当前常用的 Hook 都在此间落地版本新增功能13.7.0useSet13.9.0useFirstMountState、useRendersCount13.10.0useStateHistory即后来的useStateWithHistory13.11.0useUnmountPromise13.12.0useScrollbarWidth13.13.0useShallowCompareEffect、useCustomCompareEffect13.15.0useCookie13.19.0useError13.22.0useLongPress13.23.0createGlobalState全局状态工厂13.24.0createReducerContext、createStateContext13.25.0useBeforeUnload支持传入 dirty 函数13.26.0useMethods14.1.0useHash14.3.0useScratch15.0.0useScratch传感器 Hook 正式版13.x 的破坏性变更13.0.0移除useWait它只是另一个包的简单再导出、移除废弃的useRefMounted请改用useMountedState14.0.0重做useRafLoop返回数组变为[stop, start, isActive]且循环启停不再导致父组件重新渲染。值得关注的性能修复13.10.2修复useUpdate计数器到达Number.MAX_SAFE_INTEGER后无法触发重渲染的问题13.24.1改用fast-deep-equal进行深比较服务于useDeepCompareEffect13.12.1useMap的方法在渲染间保持稳定引用。六、v12 及更早基础 Hook 的积累v12 之前是 react-use 的奠基期很多基础设施型Hook 在此时出现4.9.0useSessionStorage、useWait5.2.0useKeyPress支持按键组合5.9.0useAsyncRetry5.12.0–5.14.0useWindowScroll、useScroll、useLockBodyScroll6.0.0useClickAway替代useOutsideClick7.0.0useKey、useDrop、useDropArea、useEvent、usePageLeave、useThrottleFn等大批 Hook 集中发布9.12.0useInterval11.3.0usePreviousDistinct12.4.0useIntersection12.9.0createBreakpoint12.13.0引入resolveHookState状态解析工具见 src/misc/hookState.tsuseCounter、useGetSet借此重构更贴近 React 的 setState 语义。早期破坏性变更清单升级旧版本项目时以下 API 变迁需要特别注意版本破坏性变更2.0.0 / 3.0.0 / 9.0.0useToggle接口三次调整最终接受任意值并转为布尔4.0.0useCounter接口变更新增useNumber别名5.0.0移除实验性 HookuseRenderProp、useAsync6.0.0useOutsideClick更名为useClickAwayuseCallbag移除KeyboardJS、Rebound 改为单独安装7.0.0useKeyPressEvent改为依赖注入并返回事件对象useThrottle完全重写8.0.0useCopyToClipboard接口变更10.0.0useSpring、useKeyboardJs不再列入 peerDependencies需直接导入11.0.0useTimeout改为返回元组12.0.0媒体类 HookuseAudio/useVideo状态由isPlaying改为paused13.0.0移除useWait、useRefMounted14.0.0useRafLoop返回值顺序改为[stop, start, isActive]15.0.0useMeasure、useLocalStorage实现重构useAsyncFn保留旧结果16.0.0create*工厂移入factory子目录comps更名为component17.0.0useNetwork更名为useNetworkState七、源码验证异步与生命周期 Hook 的稳定性修复CHANGELOG 中反复出现useAsync系列、useUpdateEffect等 Hook 的修复记录结合源码可以理解其设计意图src/useAsyncFn.ts 使用lastCallIdref 记录最近一次调用的 ID仅在组件仍挂载且本次调用仍是最新时才写入状态从而避免竞态对应 13.8.1 does not discard old promises and might produce races 的修复以及 15.0.0 keep previous state in useAsyncFn 的变更——调用期间保留上一次的value/error15.1.1 将useIsomorphicLayoutEffect应用到所有 Hooksrc/useIsomorphicLayoutEffect.ts统一了 SSR 下的 effect 行为17.1.1 修复useMountedState在componentDidUpdate阶段误改状态的问题useMountedState现由 src/useMountedState.ts 实现并被useAsyncFn、useStateList等复用。这些细节说明react-use 的版本历史不仅是加功能更是在持续打磨事件绑定src/misc/util.ts 中的on/off/isBrowser工具、SSR 兼容性与竞态处理。八、如何查阅版本历史与制定升级策略查看完整日志仓库根目录的 CHANGELOG.md 记录了从 1.0.0 至今的全部条目按版本号 发布日期 变更类型Features / Bug Fixes / Performance Improvements / BREAKING CHANGES组织是最权威的升级参考核对导出面升级前对照 src/index.ts 确认目标版本是否仍导出你使用的 Hook 及导入路径尤其注意 16.0.0 的factory目录调整和 10.0.0 起useSpring/useKeyboardJs需单独安装关注 Breaking Changes 标记本文第七节的表格汇总了历次破坏性变更升级跨越多个大版本时建议逐个版本对照检查查阅对应文档与故事每个 Hook 在 docs 目录有独立 Markdown 文档在 stories 目录有 Storybook 演示用例如 stories/useWindowSize.story.tsx可用于验证新 API 的实际用法运行测试仓库提供了完善的 Jest 测试集tests 目录升级后可通过yarn test快速回归。结语透过 CHANGELOG.md 这份 2000 余行的版本日志可以清晰看到 react-use 从一套基础 Hook 集合成长为覆盖传感器、状态管理、生命周期、UI 交互等多维度工具库的全过程。对使用者而言掌握哪个 Hook 在哪个版本出现、哪些版本引入了破坏性变更是安全升级与排查兼容问题的关键。当前仓库处于 17.6.1如果你的项目仍停留在 v15 或更早版本建议参照本文的破坏性变更清单重点核对useMeasure、useLocalStorage、useNetworkState、useRafLoop等 Hook 的 API 差异后再进行升级。【免费下载链接】react-useReact Hooks — 项目地址: https://gitcode.com/gh_mirrors/re/react-use创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考