v4 开发计划（v4 Development Plan）

[liuyib]

预期目标

• 处理完所有  bug  类的  PR  和绝大部分  bug  类  Issue
• React 18  兼容测试、适配
• 严格模式下跑通所有测试用例（目前跑严格模式的指令大部分都没有生效，单测文件中 renderHook 需要从 /packages/hooks/src/utils/tests 下引入才能测严格模式，而目前大部分是直接从 @testing-library/react 引的）
• 解决存在问题的历史包袱：render  时读/写  ref
  • 相关  issue：usePrevious shouldn't use a ref #2162、当前的usePrevious实现违反了useRef的使用准则的。 #780
  • React  文档建议（Do not write or read ref.current during rendering）：https://react.dev/reference/react/useRef
• 良好的参数校验

useRequest

• 所有  open  状态的  Issue/PR：https://github.com/alibaba/hooks/issues?q=is%3Aopen+in%3Atitle+useRequest+
• 轮询重启（需要讨论是否支持）useRequest 轮询重启 #1827 (comment)
• 整理  useRequest  目前所有待处理的  issue，看有哪些问题，是否需要去修复，有些功能是否可以增强；
• 参考一下  react-query，有一些好的功能可以借鉴过来；

问题修复  🐛

Scene

• useVirtualList：overscan  属性设置为  0  时，第一条数据不会渲染  useVirtualList里的overscan属性设置为0时，第一条数据不会渲染 #1538
  对应 PR（以下 PR 都处理了 useVirtualList里的overscan属性设置为0时，第一条数据不会渲染 #1538 需要再次确认，采用哪个 PR 的方案或综合考虑）：
  • fix(useVirtualList): when overscan is 0, the list is not correct #1808
  • fix(useVirtualList): get correct offset when itemHeight is fixed #2279
• useVirtualList：当  itemHeight  为  number  时，list  变化后  offset  计算错误。fix(useVirtualList): 修复当itemHeight为number时，list变化滚动条位置 #2015
• useVirtualList:  数据抖动  fix(useVirtualList): 数据抖动 #1807
• useCountDown: targetDate resets leftTime fix(useCountDown): targetDate resets leftTime #2346
• useWebSocket：React 18  严格模式下不可用的问题  fix(useWebSocket): add init phase to pass React 18 Strict Mode #1923
• useWebSocket  的  onOpen  问题  useWebSocket的onOpen问题 #1817
• useSelections  支持复杂数据类型（或在文档中标注  T  不能为对象）：useSelections当defaultSelected是数组对象的时候checkbox无法选中 #1105

State

• useResetState：随机初始值  reset  后，没有正常还原的问题  fix(useResetState): reset random initial value incorrectly #2562

Effect

• useThrottleFn：对  wait  参数默认值取值逻辑调整，以支持底层节流防抖的实现细节：feat(useThrottleFn/useDebounceFn): support requestAnimationFrame #2332

Dom

• useLongPress：滑动过程中触发了长按的回调  fix(useLongPress): deal with touchcancel event #2133
• useClickAway：点击目标元素里的动态子元素时，仍触发了回调的问题：useClickAway works wrong #2321

功能增强  ✨

Scene

• useInfiniteScroll：新增  isInverse  参数，控制滚动方向  feat(useInfiniteScroll): using useInfiniteScroll with isInverse prop #2315
• useInfiniteScroll：强制加载更多的能力  useInfiniteScroll loadMore 不能强制加载更多？ #2180
• useDynamicList：新增  batchRemove  批量移除的方法   feat(useDynamicList): add batchRemove method #2340
• useDynamicList：允许定制  key  以支持复杂类型的数组  useDynamicList 的 getIndex 能否指定比较的参数？ #2280
• useVirtualList：添加滚动回调  feat: useVirtualList 添加滚动回调 #2010
• useHistoryTravel：支持手动更新   类似于  VueUse  的  useManualRefHistory：feat(useHistoryTravel): add manual update option #2278
• useWebSocket:  新增  binaryType  参数：feat(useWebSocket): add 'binaryType' parameter #1941
• useWebsocket：新增重试回调  useWebsocket触发reconnectLimit上线能否有个回调 #2345

State

• useSession/LocalStorageState：存储值变化时，所有  key  相同的  useSession/LocalStorageState  会同步状态，包括同一浏览器不同  Tab  之间：feat(useStoage): listen to storage event #2298
• 💥 useGetState：同步获取最新状态（之前组件下一次  render  时才能获取最新状态）feat(useGetState): get state synchronously #2268
  • （也可以通过新增  hook，而不引入破坏性）新增  useStateRef hook：feat: add useRefState hooks #2348
• 💥 createUseStorageState：支持批量更新：fix(createUseStorageState): batched updates #2082，类似需求：
  • 💥 useCookieState  支持批量更新  fix(useCookieState): batch updates #2084
  • （破坏性待确认）useRafState  支持批量更新
• 💥 useUrlState：支持嵌套对象：[feature] useUrlState 支持嵌套对象 #2205
• 💥 useStorageState/useUrlState/useCookieState  默认值是否应该被持久化？

  • fix(useStorageState): default value is not stored #2064- storage

  • fix(useCookieState): default value is not stored #2098- cookie

Dom

• 💥 useClickAway：空  target  数组也允许触发回调：feat(useClickAway): allow falsy target #1953
• 💥 useClickAway：支持  Shadow DOM  外的点击事件触发  callback：feat(useClickAway): supports triggering callback by events outside the shadow dom #2190
• useClickAway  的  target  传函数时，支持返回多个  dom target：[提案] useClickAway 的 target 传函数时，支持返回多个 dom target #1988
• 💥 useKeyPress  的兼容性处理，采用  key  方案：fix(useKeyPress): make alias of keyCode more compatible #2054
  • 相关  issue：useKeyPress 在 firfox 下的兼容问题 #1467
  • 成熟库参考：https://github.com/jamiebuilds/tinykeys
• useKeyPress:  支持连续按下  N  次按键后再触发回调：useKeyPress是否可以支持重复按一个按键N次然后再触发回调逻辑 #2286
• useSize：新增参数以支持  ResizeObserver  的  options参数：
  • [Feature Request] useSize() options support #2227
  • useSize返回的值，不会把border的宽度算进去 #2114

Advanced

• useControllableValue：更好的类型提示  feat(useControllableValue): improve types using key of props #1748
• useReactive:  添加安全机制（options.safe  参数），组件卸载后不再执行异步回调中的状态变化  feat(useReactive): 添加 safe 机制，组件卸载后不再执行异步回调中的状态变化 #1494

性能提升  🚀

Scene

• useVirtualList：配合  IntersectionObserver  出现抖动：useVirtualList 配合 IntersectionObserver 出现抖动 #2324，有  fork  版解决了这个问题

新  Hook ✨

Scene

• useModal：对组件库的弹框组件（Modal、Drawer  等）进行包裹，简化使用、统一代码风格  feat(useModal): add new hook useModal #2304，优缺点对比：[RFC] useModal #2302 (comment)
• usePostMessage：封装  postMessage API，支持跨文档通信  feat: usePostMessage #1977

Effect

• 统一暴露  createDeepCompareHook，再把深比较的  hook  都删了：feat: useDeepCompareMemo #1972

Dom

• useBounding：封装getBoundingClientRect API，支持页面  resize、scroll  时更新  feat: add new hook "useBounding" #2063
• useSwipe：手势检测  feat: useSwipe #2337

文档  📝

• 官网生成工具  dumi  升级  v2（目前已在  chore_dumi_upgrade分支完成升级，已合并到 v4 分支）
• useKeyPress  在  Mac  下  Meta  键   和  keyup  的问题  FAQ  文档编写：docs: update useKeyPress docs #2058
• useMemoizedFn cannot replace useCallback when functions called during render [docs] useMemoizedFn cannot replace useCallback when functions called during render #2341
• （🚧 持续更新中）v3->v4 升级文档
• 英文文档

杂项  🛠

• 项目在  node > 17  版本中无法运行：The project itself doesn't work when the node version is higher than 17 #2276
• 解决项目中的  TS Warnings：chore: solve ts warnings #2339
• 升级  query-string  依赖，其底层依赖了有漏洞的  decode-uri-component  版本：chore: bump query-string to ^8.1.0 and update jest config #2319
• 升级  prettier from 2.2.0 to 3.0.0 chore(dev-deps): bump prettier & eslint #2248
• (❌ 不予处理) 移除打包  es  产物时，多余的  pipe  步骤（貌似不需要过  babel）：chore: remove babel pipe when building es bundle #2314
• 升级  webpack5，打包产物改为  esnext  以优化体积：Create ES6 build without inlined helpers for async-await, iterators, rest-spread etc #1898
• 文档站点中，Logo  插入逻辑性能优化：chore: update eslintrc.js and config.ts #2307
• （🚧 codesandbox 的示例应该是 dumi 自动生成的，待验证升级到 dumi v2 后，这些问题是否解决）文档里的  codesandbox  初始打开后就会报错：
  • 相关 issue：官网案例codesanbox打开后，react与react-dom版本不一致导致案例无法显示 #2226
  • https://ahooks.js.org/zh-CN/hooks/use-dynamic-list->  第一个  codesandbox  默认不能用
  • https://ahooks.js.org/zh-CN/hooks/use-selections->  第一个  codesandbox  默认不能用
• 创建  Issue Helper？帮助规范提  issue，参考  antd https://github.com/ant-design/antd-issue-helper

未分类（待确认是否需要处理或支持）

Scene

• useInfiniteScroll  异步  bug useInfiniteScroll 异步bug #2303
• useInfiniteScroll  无限滚动加载到第二页以上，执行 reload 数据不会清空而是叠加：useInfiniteScroll 无限滚动加载到第二页以上，执行reload数据不会清空而是叠加 #2224
• useInfiniteScroll 在切换 tab 场景下执行两次的问题  useInfiniteScroll在切换tab场景下执行两次的问题 #1652
• usePagination cache cannot use current page to cache pages：usePagination cache cannot use current page to cache pages  #2200
• useCountDown  数据错误当本地时间错误时  useCountDown showing wrong count down time if user local time wrong #1455
• next.js  中  useWebSocket options 的  on  事件都不生效  nextjs 中 useWebSocket options的on事件都不生效 #2309
• (❌ 不予处理) useWebSocket  优化提议  socketUrl  参数支持数组：useWebSocket 优化提议 #2187

State

• useUrlState to use react-router-dom instead of react-router useUrlState to use react-router-dom instead of react-router #1725

Effect

• useInterval clear 后，如何重启？ useInterval clear后，如何重启？ #1829

Dom

• useLongPress  如何可以控制子元素的  onClick  事件  useLongPress如何可以控制子元素的onClick事件 #2325
• useLongPress  在内嵌到 ios 的网页中使用时，如果长按结束后弹出一个蒙层，蒙层绑定了 click 事件，在松开手指时会直接触发蒙层的 click 事件useLongPress 在内嵌到ios的网页中使用时，如果长按结束后弹出一个蒙层，蒙层绑定了click事件，在松开手指时会直接触发蒙层的click事件 #2289
• useLongPress  的  moveThreshold  支持对  onClick  生效  useLongPress的moveThreshold支持对onclick生效 #2166
• (❌ 不予处理) useClickAway  判断不对  useClickAway判断不对 #1641
• useDrop child trigger avoidance does not work reliably useDrop child trigger avoidance does not work reliably #2036

待分类

• (❌ 不予处理) [RFC] usePromiseQueue  将多个并发请求，通过队列形式逐个请求  [RFC] usePromiseQueue #2016
• [RFC] useRightClickMenu / useContextMenu  右键菜单  [RFC] useRightClickMenu / useContextMenu #1771
• [RFC] useLoading [RFC] useLoading #1745

其他项目引入的问题

Dom

• useResponsive：在  Next.js  中导入报错  useResponsive giving error #2263（需要  Next.js  来修复）

其他

• 没有记录到本文档的  issue，时间比较久远，从这一页开始往后：https://github.com/alibaba/hooks/issues?page=4&q=is%3Aissue+is%3Aopen

竞品参考

• https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/hooks/src
• https://github.com/juliencrn/usehooks-ts/tree/master/packages/usehooks-ts/src
• https://github.com/uidotdev/usehooks
• https://github.com/sergeyleschev/react-custom-hooks/tree/main/src/hooks
• react-use （不再维护，且有很多打破  ref  规则的用法，慎重参考）
• vue-use

总结

• Scene： 15（已分类）+ 8（未分类）
• State： 8（已分类）+ 1（未分类）
• Effect： 2（已分类）+ 1（未分类）
• Dom： 10（已分类）+ 5（未分类）
• Advanced：2（已分类）
• 文档： 3
• 杂项： 9

人员分工：

• Scene：1  核心  + 2  社区（任务数占比  45%）
• State+杂项：1  核心  + 1  社区（任务数占比  24%）
• Effect+Dom+Advanced+文档：1  核心  + 2  社区（任务数占比  31%）
• useRequest：3  个核心都参与+ 1  社区

[liuyib]

转 @crazylxr 的建议：

useBounding

有了这个 useSize 是不是可以不需要了

useSwipe

手势相关的我想把缩放，旋转这些也加进来，加个 usePinch、useRotate

usePromiseQueue

这个可以改一下，我的想法是加一个 usePromise 的 hook，这里面有更多的基于 promise 扩展的，比如 超时、队列，promisify 等逻辑。

添加 useFPS。

[chenJJ-88]

感觉v4 是不是还有点遥遥无期

[xmsz-stu]

支持useArray吗？感觉很常用啊

https://github.com/mantinedev/mantine/blob/master/packages/%40mantine/hooks/src/use-list-state/use-list-state.ts
https://github.com/uidotdev/usehooks/blob/90fbbb4cc085e74e50c36a62a5759a40c62bb98e/index.js#L564
https://github.com/sergeyleschev/react-custom-hooks/tree/main/src/hooks/useArray

[crazylxr]

https://ahooks.pages.dev/zh-CN/hooks/use-reactive 这个能满足你需求么

[xmsz-stu]

https://ahooks.pages.dev/zh-CN/hooks/use-reactive 这个能满足你需求么

用起来会有点『复杂』，一个改变了赋值习惯，一个是数组会有一些情况很容易忘记比如需要拷贝后才能监听到变化。