Sim 前端 Hook 规范解析:UI/编排 Hook 的结构模板、状态形态约束与 React Query 边界-北京尧图网络

Sim 前端 Hook 规范解析:UI/编排 Hook 的结构模板、状态形态约束与 React Query 边界【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000 builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim本篇技术文章基于 Sim 仓库的 Hook 编写规则文档 sim-hooks.md,系统讲解 Sim 应用中apps/sim下所有自定义 Hook 的结构模板、六条编写规则、状态形态(State shape)的三类陷阱及其修复模式。读完你可以掌握:如何为 UI/编排型 Hook 搭建“props 接口 refs 稳定依赖 useCallback 操作”的标准骨架,如何避免useState(prop)镜像 prop、如何用 render 期prev追踪器安全地从 prop 播种本地状态,以及如何划定 React Query 与本地 Hook 之间的数据边界。适用范围与边界划分该规则文档通过 frontmatter 声明了作用域,覆盖两类文件路径:apps/sim/**/use-*.tsapps/sim/**/hooks/**/*.ts即 Sim 应用下所有自定义 Hook。仓库中的 AGENTS.md 进一步说明:这些规则约束apps/sim/**/hooks/**与apps/sim/**/use-*.ts下的 Hook,并给出“单一职责、props 接口、refs 稳定依赖、返回操作包装useCallback、加载/错误跟踪、异步try/catch、逻辑与渲染分离”的完整约定。规则文档开篇就划定了最核心的边界:服务器数据一律走hooks/queries/下的 React Query Hook,禁止在本层 Hook 里useStatefetch。hooks/queries/目录是 Sim 的服务器数据访问层,包含 140 余个查询/变更 Hook(如 tables.ts、workflows.ts、workspace-files.ts)。例如 useRenameTable 就是一个典型的 React QueryuseMutation:它通过requestJson提交契约、在onError中提取校验错误弹出 toast、在onSettled中失效相关查询缓存。而本文讨论的 UI/编排 Hook 只承担另一件事——持有 UI 专属状态、包装回调、编排多个 React Query Hook 的调用时机。结构模板:一个标准 UI/编排 Hook 的四步骨架规则文档给出的标准结构如下,这是一个只持 UI 状态、对外暴露操作的完整模板:interface UseFeatureProps { id: string onSelect?: (item: Item) void } export function useFeature({ id, onSelect }: UseFeatureProps) { // 1. Refs for stable dependencies const idRef useRef(id) const onSelectRef useRef(onSelect) // 2. UI-only state (never server data) const [isOpen, setIsOpen] useState(false) // 3. Sync refs useEffect(() { idRef.current id onSelectRef.current onSelect }, [id, onSelect]) // 4. Operations (useCallback with empty deps when using refs) const select useCallback((item: Item) { onSelectRef.current?.(item) setIsOpen(false) }, []) return { isOpen, setIsOpen, select } }这四步各有明确意图:props 接口先行:每个 Hook 必须有一个interface UseXxxProps,把参数显式契约化,而不是散落的参数列表。refs 承载不稳定依赖:回调类 prop(如onSelect)每次渲染都可能换引用,直接放进useCallback依赖数组会导致回调频繁重建。改为存入useRef,操作函数即可使用空依赖数组useCallback(fn, []),引用永远稳定。只保留 UI 状态:isOpen这类纯界面状态属于本层;服务器数据一旦进入useState就脱离了 React Query 的缓存、失效与重试体系,被规则明确禁止。useEffect 同步 refs:在提交阶段把最新 props 刷入 refs,操作函数读取的永远是当前值。真实案例一:多路复用内联重命名use-inline-rename.ts 是该模板在生产代码中的完整实现,用于资源表格、文件、知识库等行的内联重命名:interface UseInlineRenameProps { /** * Persists the new name. Return the mutation promise (e.g. React Querys * mutateAsync(...)) — NOT a fire-and-forget mutate(...) — so isSaving * spans the in-flight request and a rejection can revive the edit session. */ onSave: (id: string, newName: string) undefined | Promiseunknown }几个值得注意的实现细节:onSave被包在onSaveRef中且每渲染期直接赋值(而非 useEffect),submitRename用useCallback空依赖数组,返回给调用方的函数引用永远稳定——这正是规则第 3、4 条的落地;Hook 只持有三个 UI 状态:editingId(哪一行在编辑)、editValue(输入中的名字)、isSaving(提交中);持久化本身由外部传入的 React Query mutation promise 完成,Hook 不碰服务器数据;失败路径上它会恢复原始名字、重新武装doneRef守卫,让编辑会话可以再次提交或取消——这对应规则文档中“错误跟踪、异步try/catch”的要求,也演示了 UI 状态如何优雅地吸收网络失败的副作用。真实案例二:侧边栏单项重命名侧边栏的单条目版本 use-item-rename.ts 展示了同一条规则链路的另一种形态:isEditing/editValue/isRenaming三个纯 UI 状态,handleSaveEdit是异步useCallback,在try中await onSave(trimmedValue)、catch中恢复editValue为原值、finally中复位isRenaming;handleKeyDown把 Enter/Escape 映射到保存/取消。两个实现文件头部的注释互相引用对齐,说明仓库内这类编排 Hook 是成族维护的。真实案例三:编排层 Hook 与 React Query 的组合use-table-undo.ts 展示了编排 Hook 的“上限”形态——它自己不定义任何服务器请求,而是组合 hooks/queries/tables.ts 中的九个 React Query mutation(useUpdateTableRow、useBatchCreateTableRows、useAddTableColumn、useRenameTable等),用一组每渲染期同步的 refs(persistLayoutRef、getLocksRef、activeViewIdRef…)让executeAction的useCallback依赖保持最小。undo/redo 执行时,它把“撤销创建一行”翻译成deleteRowMutation.mutate(action.rowId),把“撤销删除”翻译成带orderKeys的批量重建。这就是“Hook 管编排、React Query 管数据”边界的一个完整样本。六条编写规则规则文档的 Rules 章节是硬性约定,逐条说明其动机:规则说明与动机1. 每个 Hook 单一职责一个 Hook 解决一类 UI 交互;useTableUndo只负责撤销栈回放,useInlineRename只负责编辑会话,职责不越界才可能独立测试与复用2. 必须定义 props 接口UseXxxProps接口让参数契约显式化,便于类型检查与文档化(如UseInlineRenameProps.onSave的注释说明了为何要求返回 promise 而非 fire-and-forget)3. 用 refs 承载不稳定回调依赖避免回调 prop 变动导致下游useCallback/useEffect重建4. 返回的函数一律useCallback包装保证父组件传给子组件的 handler 引用稳定,减少无关重渲染5. 服务器数据只走 React Query即hooks/queries/目录;本层useStatefetch是明令禁止的反模式6. 本层只保留 UI/编排状态isOpen、editingId这类状态可留;任何可缓存/可失效的服务器状态都不属于这里状态形态规则:三类反模式与修复方式这是规则文档中信息密度最高的部分,针对“状态如何从 prop 流入本地状态”给出了明确禁令与替代方案。反模式:useState(prop) 同步 useEffect把 prop 镜像进 state 并用useEffect同步是典型错误:prop 变化会覆盖用户正在进行中的本地编辑(modal 打开时用户改了名字,父组件一重渲染,编辑内容被重置)。规则给出三条替代路径,按优先级:直接使用 prop——大多数情况根本不需要本地副本;通过 remountkey重置——让组件整体重挂载来重建状态;仅在状态跃迁时播种——确需从 prop 初始化本地状态(如 modal 打开的瞬间),在render 阶段用prev值追踪器调整,而不是在 effect 里同步。render 期 prev 追踪器:完整写法与三条铁律规则文档给出的标准实现:const [prevOpen, setPrevOpen] useState(open) if (prevOpen ! open) { setPrevOpen(open) if (open) setName(initialName) // closed → open only }React 会立即带着修正后的状态重新渲染,不会把旧值提交给 DOM。它配有三条强制规则:if (prev ! current)守卫是必须的——render 期间无条件setState会造成无限渲染循环;追踪器必须在守卫内部更新——只在检测到跃迁时才写入prev,避免守卫永久失效;只允许设置当前渲染组件自身的状态——不能在 render 期触碰其他组件的状态。为什么追踪器必须是useState而不是useRef这是文档中最容易被忽略、但理由最扎实的一条:React 官方禁止在 render 阶段读写ref.current(React 文档useRef条目明确写有 “Do not writeor readref.currentduring rendering”),react-hooks的refs规则也会对此告警;并发模式安全:useState追踪器在并发渲染下是安全的——被丢弃的渲染会回滚 state;而 render 期被改写的 ref 不会回滚,一旦该渲染被放弃,ref 里留下脏值。规则文档同时承认了存量代码的现实:部分旧组件确实用了useRefprev 追踪器,并给出了仓库中的真实例子——知识库重命名弹窗 rename-document-modal.tsx 中的prevOpenRef。文档的结论是:它能工作,但新代码应优先采用上面的useState形式。追踪器初始值决定挂载行为:要刻意选择初始值的选择直接决定组件首次挂载时的行为,规则文档对此给出了两种场景的判定方法:组件以“未激活”状态挂载(如 modal 挂载时open false):用useState(open)播种。首次渲染守卫为false,挂载时不做任何重置——这是正确的,因为name本来就处于初始值。组件可能以“激活”状态挂载,或被替换掉的 effect 在挂载时就做了真实工作(如 prop 已匹配就打开面板、从已存在的值播种可编辑状态):必须播种一个真实值不可能等于的哨兵(如useStateT | null(null))。否则首次渲染守卫为false,那个本应发生的挂载动作会被静默丢弃。此外,该代码块必须放在任何早退return之前,保证每次渲染都执行。useState与useRef的转换判据规则文档还回答了“什么时候可以把一个useState降级成useRef”:仅当该值从不在 render/JSX 中被读取、且从不出现在任何 Hook 的依赖数组中。依赖数组中的值变化必须触发 Hook 重算,所以它必须保持 state;只有“只写、仅在 handler 或 effect 体内读取”的值(文档举例如 prompt 历史索引、待上传 URL)才可转 ref。反过来,如果 ref 参与了渲染,改写它不会触发重渲染,UI 会停留在过期值。这条与 sim-components.md 中的rerender-state-only-in-handlers规则互为补充:该 lint 报“state 被设置但从未渲染”时,若这个useState实际被某个useEffect依赖消费(效果必须随变化重跑),属于误报,不可转 ref。互斥标志:收敛为一个status枚举描述同一台状态机的多个矛盾布尔值(isLoading/isVerified/isInvalidOtp)应合并为单一枚举:status: idle | verifying | verified | error(外加errorMessage),消费者仍需要的布尔由派生表达式给出(status error)。这消除了“加载中且已验证”这类不可能状态被构造出来的可能。忙/成功标志:从 mutation 对象派生,绝不复制mutation.isPending/mutation.isSuccess不得复制进本地useState——直接读 mutation 对象,重置用mutation.reset()。唯一例外:mutation 覆盖不到的独立阶段可以保留自己的标志,例如提交前的验证码/Turnstile 校验发生在mutate()调用之前,这个前置闸门标志不算复制。如何自查与继续深入规则主体:sim-hooks.md;作用域说明:apps/sim/hooks/AGENTS.md结构模板的边界依据(React Query 层):sim-queries.md、hooks/queries/ 目录标准 Hook 实现样本:use-inline-rename.ts、use-item-rename.ts、use-table-undo.tsrender 期 prev 追踪器的存量 ref 写法:rename-document-modal.tsx相关配套规则:组件侧的 state/ref 判据见 sim-components.md遵循这套规则的实际收益是:每个 Hook 的输入契约、状态形态与副作用边界都可以从签名一眼读全;useCallback空依赖 refs 的组合让 handler 跨渲染保持稳定,减少下游重渲染;而“服务器数据只进 React Query”这条边界,使得缓存失效、错误重试与乐观更新都集中在hooks/queries/一处维护,UI 层 Hook 保持轻量、可独立测试。【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000 builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Sim 前端 Hook 规范解析:UI/编排 Hook 的结构模板、状态形态约束与 React Query 边界

相关推荐

SEO推广工具数据分析功能全解析：从关键词到转化

Refine 项目实战：NVM（Node Version Manager）完整安装与使用指南

医药企业选购扫描电镜的7个硬指标

更多资讯

Carbon 语言名称查找设计解析：作用域、未限定名称解析、名称污染与遮蔽规则

11 个数学可视化与计算工具如何选？awesome-math 免费资源完整指南

CVAT标注平台快速上手：如何用3条命令启动自己的计算机视觉标注服务

CANN/GE LLM数据分发缓存配置

拓扑BICs远场偏振矢量图与拓扑荷的COMSOL提取全流程

相控阵超声声场计算绕不开瑞利积分：原理、离散化与工程实践

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？