beautiful-react-hooks：轻量级 React 自定义 Hook 集合库全解——从安装、Hook 目录到源码级设计剖析

前端开发工具【免费下载链接】beautiful-react-hooks A collection of beautiful and (hopefully) useful React hooks to speed-up your components and hooks development 项目地址https://gitcode.com/gh_mirrors/be/beautiful-react-hooks点击查看免费下载本文围绕 beautiful-react-hooks 官方文档日文版 README展开完整覆盖该库的设计动机、安装方式、全部 Hook 清单、Peer 依赖策略与贡献流程并结合当前仓库源码剖析useInterval、useDebouncedCallback、createStorageHook等代表性 Hook 的实现原理与测试体系。读完后你将能够在本项目中快速定位并使用所需的 Hook理解其底层实现约定并按项目规范进行测试与文档补充。设计动机为什么需要 beautiful-react-hooks根据 docs/README.jp-JP.md 中的「なぜ?为什么」章节作者长期维护并跨项目共享的自定义 Hook 呈现出高度相似的共性大量涉及回调引用callback references、事件绑定与组件生命周期管理。这些重复模式被抽象沉淀为beautiful-react-hooks这一 Hook 集合目的是帮助企业和专业开发者加速开发流程。文档中还强调了两个关键设计理念简练且具体的 API优先考虑代码可读性尽可能降低学习曲线让更大的团队能够使用并共享同一套 Hook。文档同时给出一条醒目的提示使用任何 Hook 之前请务必先阅读其对应文档每个 Hook 在docs/目录下都有独立文档页例如 useInfiniteScroll 文档。从仓库结构看项目以 TypeScript 编写每个 Hook 一个独立源文件src/useXxx.ts配套独立测试test/useXxx.spec.js与独立文档docs/useXxx.md这种一 Hook 一文件的组织方式正是其低学习曲线理念在工程结构上的体现。核心特性原文档「特徴特性」一节列出了三点核心特性简练的 API簡潔な API轻量軽量库运行时仅依赖两个 lodash 工具函数其余能力全部基于 React 原生 Hook 与浏览器 Web API 实现易学习学習が容易。轻量这一点可以直接从 package.json 中得到验证dependencies中只有两个依赖dependencies: { lodash.debounce: ^4.0.8, lodash.throttle: ^4.1.1 }而所有 Hook 均以独立入口按需提供见下文按需引入与双模块支持这意味着未使用的 Hook 不会进入你的打包产物。安装按照原文档「インストール安装」章节支持 npm 与 yarn 两种方式使用npm$ npm install beautiful-react-hooks使用yarn$ yarn add beautiful-react-hooks环境前提Peer Dependencies 策略原文档「Peer dependencies」章节指出部分 Hook 构建于第三方库rxjs、react-router-dom 等之上因此它们被声明为 peer dependencies如果你不直接使用这些 Hook则无需安装这些依赖。package.json 中实际声明的 peer 依赖范围为peerDependencies: { react: 18.2.0 20.0.0, react-dom: 18.2.0 20.0.0, react-router-dom: 5.0.0, rxjs: 7.0.0 }可以推断出对应的依赖关系react/react-dom 18.2.0 20.0.0库运行于 React 18 环境react-router-dom 5.0.0服务于 URL 查询类 HookuseQueryParam、useQueryParams、useSearchQuery、useURLSearchParamsrxjs 7.0.0服务于响应式类 Hook如useObservable。按需安装的收益与exports映射见下节共同构成了该库的轻量承诺只引入你实际使用的那一个 Hook 的入口。基本用法与按需引入英文版主 README 给出了基本用法示例日文版文档在 Hook 链接中对应同类说明import useSomeHook from beautiful-react-hooks/useSomeHookpackage.json 中的exports字段为每个 Hook 都定义了独立的子路径导出并同时提供ESM、CJS 与类型声明三种产物。以useInterval为例./useInterval: { import: ./dist/esm/useInterval.js, require: ./dist/useInterval.js, types: ./dist/useInterval.d.ts }这意味着ESM 打包器Vite、现代 Webpack走dist/esm/下的 ESM 产物CommonJS 环境走dist/下的 CJS 产物TypeScript 用户自动获得对应.d.ts类型。构建脚本build-cjs、build-esm、build-types分别对应 tsconfig.cjs.json、tsconfig.esm.json、tsconfig.types.json 三套 tsconfig与上述三套产物一一对应。仓库 usage_example.png 中展示的官方示例代码演示了在一个组件中组合使用useMouse、useGeolocation、useMediaQuery、useWindowResize的典型场景import React, { useRef } from react; import useMediaQuery from beautiful-react-hooks/useMediaQuery import useGeolocation from beautiful-react-hooks/useGeolocation import useWindowResize from beautiful-react-hooks/useWindowResize import useMouse from beautiful-react-hooks/useMouse const SomeComponent () { const ref useRef() const mouse useMouse(ref) // 元素被悬停时返回鼠标信息 const [geoState, { onChange }] useGeolocation() // 返回地理位置信息 const isTablet useMediaQuery((max-width: 48rem)) // 组件内媒体查询 const onWindowResize useWindowResize() onWindowResize(() { trackWindowSize() }) return ( main classNamesome-component ref{ref} {isTablet ? TabletNavigation / : DesktopNavigation /} {/* ...根据 geoState.isRetrieving / isSupported / position 渲染... */} /main ) }Hook 全量目录按主题分类原文档「Hooks」一节共列出约 50 个 Hook。为保证文章可读性以下在完整继承清单的前提下按主题重新编排所有链接均指向仓库内的独立文档页状态管理类useMutableStateuseDefaultedStateuseObjectStateuseValidatedStateusePreviousValueuseValueHistoryuseToggleuseRenderInfo事件与回调类useEventuseGlobalEventuseDebouncedCallbackuseThrottledCallbackuseMouse、useMouseState、useMouseEventsuseTouch、useTouchState、useTouchEventsuseSwipe、useHorizontalSwipe、useVerticalSwipeuseSwipeEventsuseLongPressuseDrag、useDropZone、useDragEvents生命周期类useLifecycleuseDidMountuseWillUnmountuseUnmountuseUpdateEffectuseIsFirstRender时间类useTimeoutuseIntervaluseConditionalTimeoutuseRequestAnimationFrame浏览器环境与存储类useMediaQueryuseOnlineStateuseViewportSpyuseViewportStateuseWindowResizeuseWindowScrolluseResizeObserveruseMutationObserveruseInfiniteScrolluseLocalStorageuseSessionStorageuseCookieuseDarkMode地理位置与语音类useGeolocation、useGeolocationState、useGeolocationEventsuseSpeechRecognition、useSpeechSynthesis、useSystemVoices其他useObservableuseAudiouseQueryParam、useQueryParams、useSearchQuery、useURLSearchParams源码级实现剖析以下选取几个代表性 Hook结合源码说明该库的实现约定帮助读者理解其 API 背后的行为边界。useGeolocation组合式 Hook 的快捷方式useGeolocation 本身不做任何底层工作它是useGeolocationState与useGeolocationEvents的组合快捷方式const useGeolocation (options: PositionOptions geoStandardOptions) { const state useGeolocationState(options) const events useGeolocationEvents(options) return [state, events] as [UseGeolocationStateResult, UseGeolocationEventsResult] }可以推断出该库的一个设计模式状态读取与事件绑定分离——多数交互类 HookGeolocation、Mouse、Touch、Drag都提供State只读状态与Events回调设置器两种形态并再提供一个聚合版本让调用方按粒度自选。useInterval毫秒参数变化即重置定时器useInterval 的签名是(fn, milliseconds, options)其中options支持cancelOnUnmount默认true。其实现要点const useInterval TCallback extends GenericFunction (fn: TCallback, milliseconds: number, options: UseIntervalOptions defaultOptions) { // ... // when the milliseconds change, reset the timeout useEffect(() { if (typeof milliseconds number) { timeout.current setInterval(() { callback.current() }, milliseconds) } return clear }, [milliseconds]) // when component unmount clear the timeout useEffect(() () { if (opts.cancelOnUnmount) { clear() } }, []) return [isCleared, clear] as [boolean, () void] }两个值得注意的实现细节回调通过useRef保存最新引用callback.current fn因此修改回调函数不需要重建定时器只有milliseconds变化才会触发定时器重建——这是一个重要的行为边界卸载时依据cancelOnUnmount选项决定是否清除定时器默认会清除避免内存泄漏。返回值是[isCleared, clear]一个标记定时器是否已被清除的布尔值与手动清除函数。useDebouncedCallback默认 600ms 与 lodash 底座useDebouncedCallback 的签名与默认值const useDebouncedCallback TCallback extends GenericFunction (fn: TCallback, dependencies: DependencyList [], wait: number 600, options: DebounceOptions defaultOptions) { const debounced useRef(debounceTCallback(fn, wait, options)) useEffect(() { debounced.current debounce(fn, wait, options) }, [fn, wait, options, ...dependencies]) useWillUnmount(() { debounced.current?.cancel() }) return useCallback((...args: ParametersTCallback) debounced.current(...args), [...dependencies]) }可确认的实现事实wait默认600msJSDoc 中另有一处注释写 250ms以代码实际默认值 600 为准options支持leading、trailing、maxWait三个 lodash debounce 选项默认为leading: false, trailing: true底层复用lodash.debounce这正是 package.json 中仅有的两个运行时依赖之一组件卸载时自动cancel()未执行的防抖调用复用本库的 useWillUnmount。useThrottledCallback 与之对应底座是lodash.throttle。createStorageHook工厂模式生成存储 HookuseLocalStorage 与 useSessionStorage 并非各自独立实现而是由共享工厂 createStorageHook 生成。工厂的核心逻辑const createStorageHook (type: session | local) { type SetValueTValue (value: TValue | ((previousValue: TValue) TValue)) void const storageName: ${typeof type}Storage ${type}Storage if (isClient !isAPISupported(storageName)) { warnOnce(${storageName} is not supported) } return function useStorageCreatedHookTValue(storageKey: string, defaultValue?: any) { if (!isClient) { // SSR 下返回默认值与空函数避免访问 window return [JSON.stringify(defaultValue) as unknown as TValue, noop] } // 客户端读取 storage.getItemJSON 安全解析 // setValue 支持函数式更新并同步写回 storage } }这段工厂代码集中体现了该库的几个通用工程约定SSR 安全非客户端环境直接返回默认值开发模式下通过warnOnce提示${storageName} could not be available during SSR特性检测isAPISupported 检查window上是否存在对应存储 API不支持时仅警告一次而非抛错JSON 安全读写配合 safelyParseJson 与 try/catch 包裹的setItem存储读写失败时静默降级函数式更新支持setValue兼容setValue(v v 1)风格的 updater。该工厂位于 src/factory 目录与 createHandlerSetter 一起印证了用少量工厂抽象重复模式的实现思路。共享工具层src/shared所有 Hook 共用的判断与工具函数集中在 src/shared 目录例如isClient.ts环境判断isAPISupported.tsapi in window特性检测warnOnce.ts警告去重safelyParseJson.ts安全 JSON 解析geolocationUtils.ts地理位置标准选项geoStandardOptionsuseGeolocation的默认参数即来源于此swipeUtils.ts滑动判断共享逻辑服务useSwipe/useHorizontalSwipe/useVerticalSwipe三兄弟。测试体系与质量保障原文档「利用しているライブラリ使用的库」章节列出React、Mocha、Chai、testing-library/react、testing-library/react-hooks。结合 package.json 可确认完整的测试与工具链scripts: { lint: eslint src/ --ext .ts, test: nyc mocha --recursive --exit \./test/**/*.spec.(js|jsx)\, build: npx del-cli dist npm run build-cjs npm run build-esm npm run build-types, start: npx styleguidist server }测试运行器为Mocha Chai覆盖率由nyc统计DOM 模拟使用jsdom时间/异步行为使用sinon针对浏览器 API 的测试依赖 test/mocks 目录下的手工 Mock如 AudioApi.mock.js、GeoLocationApi.mock.js、ResizeObserver.mock.js、SpeechSynthesis.mock.js 等每个 Hook 都有独立规格文件test/useXxx.spec.js与源码文件一一对应文档站由react-styleguidist驱动npm start启动本地文档服务器build-doc会先执行 scripts/generate-doc-append-types.js 将类型信息附加进文档再构建静态站。贡献指南原文档「コントリビューション贡献」章节明确提交 PR 前必须阅读 CONTRIBUTING 指南必须为代码编写测试并在提交前运行npm test与npm build确认无问题若新增自定义 Hook必须补充文档可使用 HOOK_DOCUMENTATION_TEMPLATE 作为文档模板。补充说明 CONTRIBUTING 与 HOOK_DOCUMENTATION_TEMPLATE 均位于仓库根目录可直接查看。总结beautiful-react-hooks 的价值主张可以归纳为约 50 个覆盖状态、事件、生命周期、时间、浏览器环境、存储、地理位置与语音等主题的开箱即用 React Hook配合一 Hook 一文档一测试的工程组织、仅两个 lodash 运行时依赖、ESM/CJS 双产物与逐 Hook 的exports按需引入为 React 团队提供了一条低学习曲线的业务逻辑抽象路径。上手路径建议先在本文Hook 全量目录中定位目标 Hook打开其docs/useXxx.md文档确认 API 签名与默认值再参考 src/shared 与对应源码文件理解边界行为最后按 CONTRIBUTING 流程为使用或扩展该 Hook 的代码补上测试与文档。赞分享前端开发工具【免费下载链接】beautiful-react-hooks A collection of beautiful and (hopefully) useful React hooks to speed-up your components and hooks development 项目地址https://gitcode.com/gh_mirrors/be/beautiful-react-hooks点击查看免费下载相关推荐beautiful-react-hooks一套轻量级 React 自定义 Hooks 集合的安装、选型与实现原理beautiful react hooks一套轻量级 React 自定义 Hooks 集合的安装、选型与实现原理 本文以 beautiful react ho前端开发工具解析 beautiful-react-hooks 的 HOOK_DOCUMENTATION_TEMPLATE:如何为自定义 React Hook 编写规范文档解析 beautiful react hooks 的 HOOK_DOCUMENTATION_TEMPLATE:如何为自定义 React Hook 编写规范文档前端开发工具React Hooks完全指南从useState到自定义Hook实战React Hooks完全指南从useState到自定义Hook实战 引言为什么React Hooks彻底改变了组件开发 你是否曾在React类组件中挣扎前端UI组件上一篇腾讯混元4B-AWQ256K超长上下文混合推理轻量级大模型改写企业AI部署规则下一篇设计标记实战指南如何用Awesome-Design-Tokens构建高效设计系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考