QuillForms React Hooks 深度解析：useRendererStoreActions 等 8 个强大 Hook 完整使用指南

QuillForms React Hooks 深度解析：useRendererStoreActions 等 8 个强大 Hook 完整使用指南

【免费下载链接】quillformsOpen Source TypeForm Alternative Based on React JS and Typescript | Best Typeform Clone | Conversational Multi Step Form项目地址: https://gitcode.com/gh_mirrors/qu/quillforms

QuillForms 是一款基于 React.js 和 TypeScript 构建的开源 TypeForm 替代品，帮你打造对话式多步骤表单。想扩展它的功能吗？本文将带你快速掌握 8 个核心 React Hooks——从状态管理到答案读取、主题获取，全部来自@quillforms/renderer-core包，让你无需深入源码就能轻松定制表单渲染器。

为什么 QuillForms React Hooks 这么有用？

QuillForms 的渲染核心（renderer-core）把整个表单的所有状态（当前步骤、用户答案、提交状态、校验结果……）都集中存放在一个响应式数据仓库中。这些 Hook 就是访问这个仓库的"快捷通道"：

• 读数据：当前激活的题块、所有答案、单个字段答案、主题、表单消息；
• 写操作：前进/后退、跳转指定题块、提交表单、设置答案、重置答案等；
• 算指标：一键拿到表单完成进度百分比。

所有 Hook 的源码都位于 packages/renderer-core/src/hooks/ 目录，状态定义在 packages/renderer-core/src/store/actions.ts，官方用法清单见 react-docs/available-react-hooks.md。

1. useRendererStoreActions：掌控全局的"万能遥控器"

这是最强大的一个 Hook。它直接返回@wordpress/data的useDispatch('quillForms/renderer-core')，也就是说整个 store 的所有 action 你都能调用（源码：use-renderer-store-actions.ts）：

import { useRendererStoreActions } from '@quillforms/renderer-core'; const { goNext, goPrev, completeForm, setFieldAnswer, resetAnswers } = useRendererStoreActions();

常用 action 一览：

👉 适合场景：自定义"提交按钮"、实现"重新填写"、或者做答题跳转逻辑。

2. useGoToBlock：一步直达指定题目

如果你只想做一件事——跳转题块，用这个更简单的封装版：

import { useGoToBlock } from '@quillforms/renderer-core'; const goToBlock = useGoToBlock(blockId);

源码 use-go-to-block.ts 显示它本质上就是调用 store 的goToBlockaction，并支持forceUpdateState强制刷新，是做"返回上一题修改"或"题目间跳转逻辑"的利器。

3. useCurrentBlock：知道用户此刻在哪一题

多步骤表单的灵魂是"当前在哪"。useCurrentBlock会返回当前激活的题块对象（含id、name等），实现原理是拿 store 里的currentBlockId，再从题块列表（含自动追加的感谢页default_thankyou_screen）中查找匹配项：

import { useCurrentBlock } from '@quillforms/renderer-core'; const currentBlock = useCurrentBlock(); console.log(currentBlock?.name); // 例如 "short-text"

源码：use-current-block.ts 和 use-blocks.ts。 👉 适合场景：根据题型切换 UI 样式、实现条件逻辑判断。

4. useFormAnswers：一次性拿到全部答案

import { useFormAnswers } from '@quillforms/renderer-core'; const formAnswers = useFormAnswers(); // { [fieldId]: { value, ... }, ... }

它订阅 store 的getAnswers()，用户每回答一题数据都会自动更新。这是实现"实时预览答案"、"数据联动"（比如选中某选项后显示对应价格）的核心 Hook。

5. useFieldAnswer：精准读取单个字段答案

只需要一个字段的答案？别遍历整个对象，直接按 ID 取：

import { useFieldAnswer } from '@quillforms/renderer-core'; const fieldAnswer = useFieldAnswer(fieldId);

源码 use-field-answer.ts 通过getFieldAnswerVal(id)选择器实现，答案变化时组件自动重渲染。 👉 适合场景：选项选中态高亮、答案驱动的条件显示。

6. useTheme：读取当前表单主题

import { useTheme } from '@quillforms/renderer-core'; const theme = useTheme();

它内部委托给use-general-theme（use-theme.ts），返回整个表单的配色、字体等主题配置。自定义题块想要与全站视觉保持一致时，用它读取主色、字号再透传给子元素即可。

7. useMessages：获取表单文案消息

import { useMessages } from '@quillforms/renderer-core'; const messages = useMessages();

它从表单上下文中取出messages（源码：use-messages.ts），包含校验提示、提交成功/失败等各类文案。做自定义校验提示或自定义按钮文案时，这里就是文案的唯一可信来源，还能自动支持多语言。

8. useProgressPercent：一行代码算出完成率

最后一个高颜值 Hook——直接返回0~100 的整数进度：

import { useProgressPercent } from '@quillforms/renderer-core'; const percent = useProgressPercent();

它的实现（use-progress-percent.ts）很值得学习：统计所有支持编辑（supports.editable）的题块，再数出已有答案的数量，两者相除取整，NaN 时安全兜底为 0。拿来渲染顶部进度条，一行搞定。

组合拳：进阶技巧

搭配 WordPress Hooks 扩展。QuillForms 还内置了@wordpress/hooks风格的 action 钩子（详见 react-docs/available-actions-and-filters.md），比如：

import { addAction } from '@wordpress/hooks'; addAction('QuillForms.RendererCore.FieldAnsweredActive', 'myTracking', ({ id, label }) => { console.log(`字段 ${label} 已作答`); });

Hooks + Actions 组合：用useFieldAnswer监听某个字段，达到条件时调用useGoToBlock跳转、或用useRendererStoreActions触发completeForm提前结束问卷——这就是"条件跳转逻辑"的完整闭环。

常见问题 FAQ

Q：这些 Hook 只能用在 QuillForms 内部吗？A：不行，它们面向的就是第三方开发者。只要你的 React 组件运行在 QuillForms 渲染器的上下文中（如自定义题块、嵌入扩展组件），就可以直接import使用。

Q：useRendererStoreActions 和具体 Hook（如 useGoToBlock）怎么选？A：单一用途选封装好的 Hook，语义清晰且调用更短；需要批量操作或访问未封装的 action 时，再上"万能遥控器"。

Q：答案数据实时吗？A：是。所有读取类 Hook 基于@wordpress/data的useSelect订阅机制，store 一变组件立即重渲染，无需手动刷新。

总结

8 个 Hook 各司其职：useRendererStoreActions管"写"，useCurrentBlock/useFormAnswers/useFieldAnswer管"读"，useGoToBlock管"跳"，useTheme/useMessages管"样式与文案"，useProgressPercent管"进度"。掌握了这套组合拳，你就能在开源的 QuillForms 之上，搭出媲美 TypeForm 的对话式表单体验。

【免费下载链接】quillformsOpen Source TypeForm Alternative Based on React JS and Typescript | Best Typeform Clone | Conversational Multi Step Form项目地址: https://gitcode.com/gh_mirrors/qu/quillforms