• 简体中文

      • 渲染 FlowModel

      FlowModelRenderer 是用于渲染 FlowModel 的核心 React 组件，它负责将 FlowModel 实例转换为可视化的 React 组件。

      基本使用

      FlowModelRenderer

      import { FlowModelRenderer } from '@nocobase/flow-engine';

// 基本使用
<FlowModelRenderer model={myModel} />
      /**
 * 示例代码展示如何使用 NocoBase 的插件和模型功能。
 * - 定义了一个简单的 HelloModel，用于渲染一个 "Hello, NocoBase!" 的 UI 块。
 * - 创建了一个插件 PluginHelloModel，注册模型并将其渲染到路由中。
 * - 最后通过 Application 实例加载插件并启动应用。
 */
import { Application, Plugin } from '@nocobase/client-v2';
import { FlowModelRenderer } from '@nocobase/flow-engine';


/**
 * PluginHelloModel 是一个插件类，用于注册 HelloModel 并将其添加到路由中。
 * - load 方法会在插件加载时执行。
 * - 注册模型到 flowEngine，并创建一个模型实例。
 * - 将模型实例渲染到根路径 '/' 的路由中。
 */
class PluginHelloModel extends Plugin {
  async load() {
    // 注册 HelloModel 到 flowEngine
    this.flowEngine.registerModelLoaders({ 
      HelloModel: {
        // 动态导入，首次真正用到这个 model 时才会加载对应模块
        loader: () => import('@docs/cn/flow-engine/_demos/HelloModel'),
      },
     });

    // 创建 HelloModel 的实例（仅用于示例）
    const model = await this.flowEngine.createModelAsync({
      use: 'HelloModel',
    });

    // 添加路由，将模型渲染到根路径（仅用于示例）
    this.router.add('root', {
      path: '/',
      element: <FlowModelRenderer model={model} />,
    });
  }
}

// 创建应用实例，注册插件（仅用于示例）
const app = new Application({
  router: { type: 'memory', initialEntries: ['/'] },
  plugins: [PluginHelloModel],
});

export default app.getRootComponent();

      FieldModelRenderer

      对于受控的字段 Model，使用 FieldModelRenderer 渲染：

      import { FieldModelRenderer } from '@nocobase/flow-engine';

// 受控字段渲染
<FieldModelRenderer model={fieldModel} />

      Props 参数

      FlowModelRendererProps

      参数类型默认值说明
      modelFlowModel-要渲染的 FlowModel 实例
      uidstring-流程模型的唯一标识符
      fallbackReact.ReactNode<Skeleton.Button size="small" />渲染失败时的回退内容
      showFlowSettingsboolean | objectfalse是否显示流程设置入口
      flowSettingsVariant'dropdown' | 'contextMenu' | 'modal' | 'drawer''dropdown'流程设置的交互风格
      hideRemoveInSettingsbooleanfalse是否在设置中隐藏移除按钮
      showTitlebooleanfalse是否在边框左上角显示模型标题
      skipApplyAutoFlowsbooleanfalse是否跳过自动应用流程
      inputArgsRecord<string, any>-传递给 useApplyAutoFlows 的额外上下文
      showErrorFallbackbooleantrue是否在最外层包装 FlowErrorFallback 组件
      settingsMenuLevelnumber-设置菜单层级：1=仅当前模型，2=包含子模型
      extraToolbarItemsToolbarItemConfig[]-额外的工具栏项目

      showFlowSettings 详细配置

      当 showFlowSettings 为对象时，支持以下配置：

      showFlowSettings={{
  showBackground: true,    // 显示背景
  showBorder: true,        // 显示边框
  showDragHandle: true,    // 显示拖拽手柄
  style: {},              // 自定义工具栏样式
  toolbarPosition: 'inside' // 工具栏位置：'inside' | 'above' | 'below'
}}

      渲染生命周期

      整个渲染周期会按顺序调用以下方法：

      1. model.dispatchEvent('beforeRender') - 渲染前事件
      2. model.render() - 执行模型渲染方法
      3. model.onMount() - 组件挂载钩子
      4. model.onUnmount() - 组件卸载钩子

      使用示例

      基本渲染

      import { FlowModelRenderer } from '@nocobase/flow-engine';

function MyComponent() {
  const model = useFlowModel();
  
  return (
    <FlowModelRenderer 
      model={model}
      fallback={<div>加载中...</div>}
    />
  );
}

      带流程设置的渲染

      // 显示设置但隐藏删除按钮
<FlowModelRenderer
  model={myModel}
  showFlowSettings={true}
  hideRemoveInSettings={true}
/>

// 显示设置和标题
<FlowModelRenderer
  model={myModel}
  showFlowSettings={true}
  showTitle={true}
/>

// 使用右键菜单模式
<FlowModelRenderer
  model={myModel}
  showFlowSettings={true}
  flowSettingsVariant="contextMenu"
  hideRemoveInSettings={true}
/>

      自定义工具栏

      <FlowModelRenderer
  model={myModel}
  showFlowSettings={true}
  extraToolbarItems={[
    {
      key: 'custom-action',
      title: '自定义操作',
      icon: 'SettingOutlined',
      onClick: () => {
        console.log('自定义操作');
      }
    }
  ]}
/>

      跳过自动流程

      <FlowModelRenderer
  model={myModel}
  skipApplyAutoFlows={true}
  showErrorFallback={false}
/>

      字段模型渲染

      import { FieldModelRenderer } from '@nocobase/flow-engine';

function FormField({ model, onChange, ...props }) {
  return (
    <FieldModelRenderer
      model={model}
      onChange={onChange}
      {...props}
    />
  );
}

      错误处理

      FlowModelRenderer 内置了完善的错误处理机制：

      • 自动错误边界：默认启用 showErrorFallback={true}
      • 自动流程错误：捕获并处理自动流程执行中的错误
      • 渲染错误：当模型渲染失败时显示回退内容
      <FlowModelRenderer
  model={myModel}
  showErrorFallback={true}
  fallback={<div>渲染失败，请重试</div>}
/>

      性能优化

      跳过自动流程

      对于不需要自动流程的场景，可以跳过以提高性能：

      <FlowModelRenderer
  model={myModel}
  skipApplyAutoFlows={true}
/>

      响应式更新

      FlowModelRenderer 使用 @formily/reactive-react 的 observer 进行响应式更新，确保模型状态变化时组件能够自动重新渲染。

      注意事项

      1. 模型验证：确保传入的 model 具有有效的 render 方法
      2. 生命周期管理：模型的生命周期钩子会在适当的时机被调用
      3. 错误边界：建议在生产环境中启用错误边界以提供更好的用户体验
      4. 性能考虑：对于大量模型渲染的场景，考虑使用 skipApplyAutoFlows 选项