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): random initial value changed #2308

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
• [x]（❌ 不予处理）移除打包  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
• [x]（❌ 不予处理）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
• [x]（❌ 不予处理）useClickAway  判断不对  useClickAway判断不对 #1641
• useDrop child trigger avoidance does not work reliably useDrop child trigger avoidance does not work reliably #2036

待分类

• [x]（❌ 不予处理）[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 是不是还有点遥遥无期