NocoBase FlowEngine 渲染指南:FlowModelRenderer 将 FlowModel 渲染为 React 组件

NocoBase FlowEngine 渲染指南:FlowModelRenderer 将 FlowModel 渲染为 React 组件 NocoBase FlowEngine 渲染指南FlowModelRenderer 将 FlowModel 渲染为 React 组件【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobaseFlowModelRenderer 是 NocoBase FlowEngine流程引擎中负责把 FlowModel 实例转换为可视化 React 组件的核心渲染入口。本文围绕 FlowModelRenderer 及其配套的 FieldModelRenderer 展开完整覆盖 Props 参数、showFlowSettings 详细配置、渲染生命周期、错误处理与性能优化并结合packages/core/flow-engine源码说明底层实现原理帮助你在 NocoBase 中正确、高效地渲染各种流程模型。背景FlowModel 与 FlowModelRenderer 的关系在 NocoBase FlowEngine 中FlowModel是描述一段流程/一个 UI 结构的最小模型单元。它承载了props、stepParams、subModels等响应式状态并通过render()方法输出自己的 UI。而FlowModelRenderer正是模型 → 组件的桥接组件它接收一个 FlowModel 实例统一处理自动流程AutoFlows、错误边界、流程设置入口等外围逻辑最终把模型渲染成 React 组件。从源码看FlowModelRenderer.tsx 对外导出的FlowModelRenderer本身是一个observer组件基于formily/reactive-react它在内部依次完成校验model及model.render是否有效无效时返回null并给出警告通过useApplyAutoFlows在渲染前执行模型注册的自动流程默认执行beforeRender事件用FlowModelProvider把模型实例注入组件上下文配合useFlowModel消费根据showFlowSettings与flowSettingsVariant决定是否包裹流程设置组件可选地在外层包裹FlowErrorFallback错误边界。基本使用FlowModelRenderer最小使用方式只需要传入modelimport { FlowModelRenderer } from nocobase/flow-engine; // 基本使用 FlowModelRenderer model{myModel} /说明nocobase/flow-engine为当前仓库 packages/core/flow-engine 中导出的核心包FlowModelRenderer与FieldModelRenderer均可直接从该包导入。FieldModelRenderer对于受控的字段 Model如表单字段使用 FieldModelRenderer 渲染。它会在FlowModelRenderer之上补齐受控组件的onChange、中文输入法组合事件onCompositionStart/onCompositionEnd等处理import { FieldModelRenderer } from nocobase/flow-engine; // 受控字段渲染 FieldModelRenderer model{fieldModel} /从实现上看FieldModelRenderer.tsx 会把onChange归一化后通过model.setProps({ value: val })写回模型再透传rest给FlowModelRenderer因此字段 Model 的渲染天然保持模型即状态源的受控语义。Props 参数FlowModelRendererProps以下为FlowModelRendererProps的全部参数与源码 FlowModelRenderer.tsx 保持一致参数类型默认值说明modelFlowModel-要渲染的 FlowModel 实例uidstring-流程模型的唯一标识符fallbackReact.ReactNodenull文档示例默认Skeleton.Button sizesmall /渲染失败/自动流程 pending 时的回退内容showFlowSettingsboolean \| objectfalse是否显示流程设置入口flowSettingsVariantdropdown \| contextMenu \| modal \| drawerdropdown流程设置的交互风格hideRemoveInSettingsbooleanfalse是否在设置中隐藏移除按钮showTitlebooleanfalse是否在边框左上角显示模型标题skipApplyAutoFlowsbooleanfalse是否跳过自动应用流程inputArgsRecordstring, any-传递给useApplyAutoFlows的额外上下文showErrorFallbackbooleantrue是否在最外层包装 FlowErrorFallback 组件settingsMenuLevelnumber-设置菜单层级1仅当前模型2包含子模型extraToolbarItemsToolbarItemConfig[]-额外的工具栏项目关于默认值需要说明的细节源码中fallback的默认值是nullFlowModelRenderer.tsx即自动流程执行期间默认不显示任何占位内容文档示例中使用Skeleton.Button sizesmall /作为推荐的加载占位。showErrorFallback源码默认值为trueFlowModelRenderer.tsx生产环境建议保持开启。源码还额外暴露了useCache?: boolean参数用于控制beforeRender自动流程的缓存开关未显式传入时会读取model.context.useCacheFlowModelRenderer.tsx。showFlowSettings 详细配置当showFlowSettings为对象时支持以下配置showFlowSettings{{ showBackground: true, // 显示背景 showBorder: true, // 显示边框 showDragHandle: true, // 显示拖拽手柄 style: {}, // 自定义工具栏样式 toolbarPosition: inside // 工具栏位置inside | above | below }}源码中该对象的完整类型还包含showDynamicFlowsEditor?: boolean是否显示事件流Dynamic Flows编辑入口默认truestyle?: React.CSSProperties自定义工具栏样式其中top/left/right/bottom会作为 portal overlay 的inset使用toolbarPosition?: inside | above | below工具栏位置默认inside。这些配置最终会被透传给FlowsFloatContextMenu组件FlowModelRenderer.tsx。渲染生命周期整个渲染周期会按顺序调用以下方法model.dispatchEvent(beforeRender)- 渲染前事件model.render()- 执行模型渲染方法model.onMount()- 组件挂载钩子model.onUnmount()- 组件卸载钩子源码印证beforeRender 事件分发useApplyAutoFlows会调用model.dispatchEvent(beforeRender, inputArgs)useApplyAutoFlows.ts。在模型层beforeRender默认顺序执行sequential 使用缓存useCache其它事件默认顺序执行但不默认使用缓存flowModel.tsx。inputArgs即对应 Props 中的inputArgs。render 的响应式包装FlowModel 构造函数会调用setupReactiveRender()flowModel.tsx把原始render()包装为ReactiveWrapperobserver组件它订阅props、stepParams等响应式属性在值变化时自动重渲染同时处理hidden状态的渲染逻辑设置态显示半透明占位非设置态返回null。onMount / onUnmount在ReactiveWrapper的useEffect中调用flowModel.tsx卸载时还会执行resetAutoRunState()清理上次beforeRender的执行参数并向flowEngine.emitter派发model:mounted/model:unmounted事件。RenderFunction 模式若模型类声明renderMode ModelRenderMode.RenderFunction如表格单元格渲染器render()返回的是渲染函数而非 React 节点。FlowModelRendererCore会检测返回类型当typeof rendered function时用React.createElement将其作为组件渲染避免函数作为子节点的警告FlowModelRenderer.tsx。使用示例基本渲染import { FlowModelRenderer } from nocobase/flow-engine; function MyComponent() { const model useFlowModel(); return ( FlowModelRenderer model{model} fallback{div加载中.../div} / ); }useFlowModel从FlowModelProvider上下文中获取当前 FlowModel 实例useFlowModel.tsx在FlowModelProvider之外使用它会抛出错误。带流程设置的渲染// 显示设置但隐藏删除按钮 FlowModelRenderer model{myModel} showFlowSettings{true} hideRemoveInSettings{true} / // 显示设置和标题 FlowModelRenderer model{myModel} showFlowSettings{true} showTitle{true} / // 使用右键菜单模式 FlowModelRenderer model{myModel} showFlowSettings{true} flowSettingsVariantcontextMenu hideRemoveInSettings{true} /flowSettingsVariant的四种取值对应不同的设置组件dropdown默认使用FlowsFloatContextMenu浮动式支持背景/边框/拖拽手柄与自定义工具栏contextMenu使用FlowsContextMenu右键菜单式modal/drawer源码中当前为 TODO 状态会打印not implemented yet警告并直接渲染内容FlowModelRenderer.tsx使用前请留意版本支持情况未知取值会回退到dropdown行为并输出警告。自定义工具栏FlowModelRenderer model{myModel} showFlowSettings{true} extraToolbarItems{[ { key: custom-action, title: 自定义操作, icon: SettingOutlined, onClick: () { console.log(自定义操作); } } ]} /extraToolbarItems为ToolbarItemConfig[]类型仅作用于当前渲染实例由settingsMenuLevel控制是否级联到子模型1仅当前模型2包含子模型。跳过自动流程FlowModelRenderer model{myModel} skipApplyAutoFlows{true} showErrorFallback{false} /注意源码 Props 定义中直接控制自动流程的是useApplyAutoFlows(model, inputArgs, { throwOnError: false, useCache })的调用本身FlowModelRenderer.tsx其执行结果pending / error驱动fallback的显示与错误下沉在不需要自动流程渲染的场景下跳过它可以显著减少beforeRender事件的执行开销。字段模型渲染import { FieldModelRenderer } from nocobase/flow-engine; function FormField({ model, onChange, ...props }) { return ( FieldModelRenderer model{model} onChange{onChange} {...props} / ); }错误处理FlowModelRenderer 内置了完善的错误处理机制自动错误边界默认启用showErrorFallback{true}外层用react-error-boundary的ErrorBoundary包裹自动流程错误useApplyAutoFlows以throwOnError: false捕获beforeRender执行错误并通过setAutoFlowError下沉到 model 实例类型安全的 WeakMap 存储FlowModelRendererCore中的ContentOrError读取该错误并重新抛出由内层错误边界兜住FlowModelRenderer.tsx渲染错误当模型渲染失败时显示回退内容。FlowModelRenderer model{myModel} showErrorFallback{true} fallback{div渲染失败请重试/div} /FlowErrorFallback 提供了什么当错误发生时默认的回退组件是 FlowErrorFallback它提供一个基于 Ant DesignResult的完整错误面板包含渲染失败的标题与错误堆栈可一键复制模型信息uid、类名、props、stepParams通过model.context.api请求logger:collect接口下载 gzip 格式的日志包logs.tar.gzTry again 重试按钮调用resetErrorBoundary。它还导出了FlowErrorFallbackModal通过FlowErrorFallback.Modal访问适用于需要模态展示错误的场景。性能优化跳过自动流程对于不需要自动流程的场景可以跳过以提高性能FlowModelRenderer model{myModel} skipApplyAutoFlows{true} /从源码看即使不显式传skipApplyAutoFlowsuseApplyAutoFlows内部仍会基于beforeRender的缓存机制useCache默认开启复用执行结果避免重复计算同时FlowModel在stepParams变化时会通过invalidateFlowCache(beforeRender)精确失效对应事件的缓存flowModel.tsx并通过_rerunLastAutoRun100ms 防抖重跑上一次beforeRender在及时更新与避免抖动之间取得平衡。响应式更新FlowModelRenderer 使用formily/reactive-react的observer进行响应式更新确保模型状态变化时组件能够自动重新渲染FlowModelRenderer、FlowModelRendererWithAutoFlows、FlowModelRendererCore均以observer包裹FlowModel 构造时通过define将hidden、props、subModels、stepParams等标记为observableflowModel.tsx状态变更即触发订阅组件重渲染若父级频繁重渲染且 props 浅比较未变可使用源码额外导出的MemoFlowModelRendererReact.memo包装版本进一步跳过无谓渲染FlowModelRenderer.tsx它不影响内部的响应式更新。注意事项模型验证确保传入的model具有有效的render方法。源码中if (!model || typeof model.render ! function)会返回null并输出警告FlowModelRenderer.tsx。生命周期管理模型的生命周期钩子onMount/onUnmount会在适当的时机被调用卸载时会重置自动流程状态避免悬挂引用。错误边界建议在生产环境中启用错误边界保持showErrorFallback{true}以提供更好的用户体验同时可借助 FlowErrorFallback 的日志下载能力快速定位问题。性能考虑对于大量模型渲染的场景考虑使用skipApplyAutoFlows选项或利用beforeRender默认缓存与MemoFlowModelRenderer减少无效渲染。事件默认语义beforeRender事件默认顺序执行且带缓存其余事件默认顺序执行但不带缓存需要并行或强制刷新时可显式传入对应选项flowModel.tsx。延伸阅读渲染器实现packages/core/flow-engine/src/components/FlowModelRenderer.tsx受控字段渲染器packages/core/flow-engine/src/components/FieldModelRenderer.tsx模型基类与生命周期packages/core/flow-engine/src/models/flowModel.tsx自动流程 Hookpackages/core/flow-engine/src/hooks/useApplyAutoFlows.ts错误回退组件packages/core/flow-engine/src/components/FlowErrorFallback.tsx渲染器测试用例packages/core/flow-engine/src/components/tests/FlowModelRenderer.test.tsx【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考