syncfusion-react-diagram

Syncfusion React Diagram

Syncfusion React Diagram 组件可用于构建丰富的交互式图表，包括流程图、组织结构图、BPMN 流程图、UML 图、思维导图和网络图。它使用 SVG 渲染，并支持通过节点、连接器、端口、注释、布局和数据绑定进行广泛自定义。

目录

• 何时使用此技能
• 组件概述
• 文档与导航指南
  • 开始使用
  • 节点
  • 连接器
  • 标签和注释
  • 端口
  • 形状和样式
  • BPMN 图
  • UML 图
  • ER 图
  • 布局
  • 泳道
  • 组和容器
  • 符号面板
  • 数据绑定
  • 交互和工具
  • 序列化和导出
  • 图表设置
• 快速入门示例
• 常见模式
• 模块注入参考
• 关键属性

何时使用此技能

用户需要以下功能时，请使用此技能：

• 构建流程图，展示流程、决策树或工作流
• 根据层级或扁平数据源创建组织结构图
• 建模 BPMN 图，包含活动、事件、网关和流程
• 绘制 UML 图，包括类图和时序图
• 根据数据可视化思维导图或径向布局
• 设计网络图或实体图，包含节点和关系连接器
• 实现泳道图，包含泳道和阶段
• 将形状从符号面板拖放到画布
• 绑定数据以自动生成图表结构
• 将图表状态序列化为 JSON 并还原
• 将图表内容导出为图像/SVG 或进行打印

重要：必须验证 API

必须验证 API：生成代码示例前，务必阅读参考文件（references/*.md），核实 API 类名、属性和签名。不要假设或推断类名。

组件概述

Diagram 组件围绕以下元素构建：

• 节点 — 放置在画布上的图形（矩形、圆形、流程图形状、自定义形状）
• 连接器 — 连接节点或独立点的线条/箭头
• 注释 — 附加到节点或连接器上的文本标签
• 端口 — 节点上用于精确锚定连接器的命名连接点
• 布局 — 自动排列算法（层级、组织结构图、思维导图、径向、流程图）
• 符号面板 — 可拖动形状符号的侧边栏
• 模块系统 — 可选启用的功能模块（Inject 指令），用于精简打包体积

所有图表元素均使用 SVG 渲染，以呈现清晰且不受分辨率影响的图形。

文档与导航指南

开始使用

📄 阅读： references/getting-started.md

阅读时机：

• 首次设置 Diagram 组件
• 安装软件包、导入 CSS 和配置主题
• 创建最精简的 DiagramComponent
• 了解 Inject 模块系统
• 集成 Next.js 或 Preact

涵盖内容：

• npm 安装和依赖项
• Vite/CRA 项目设置
• CSS 主题导入路径
• 使用 nodes 和 connectors 的基础 DiagramComponent
• 使用 <Inject services={[...]} /> 注入模块
• Next.js 和 Preact 使用说明

---

节点

📄 阅读： references/nodes.md

阅读时机：

• 添加、定位和调整节点大小
• 自定义节点外观（填充、描边、阴影）
• 使用节点形状（Flow、Basic、Path、Image、HTML）
• 处理节点事件（点击、拖动、调整大小）
• 在运行时展开/折叠节点
• 通过 getNodeDefaults 设置默认节点属性

涵盖内容：

• 通过 nodes 集合创建节点
• 使用 offsetX/offsetY、width/height 定位
• 在运行时添加/移除节点（diagram.add、diagram.remove）
• 样式属性（填充、strokeColor、不透明度、渐变）
• 用于统一样式的 getNodeDefaults 模式
• 使用 expandIcon/collapseIcon 展开/折叠节点
• 节点交互事件

---

连接器

📄 阅读： references/connectors.md

阅读时机：

• 在节点之间或独立点之间绘制线条/箭头
• 选择连接器类型（Straight、Orthogonal、Bezier）
• 配置连接器线段和路由
• 自定义装饰器（箭头）形状
• 设置 sourceID/targetID 以连接节点
• 设置 getConnectorDefaults 以统一样式

涵盖内容：

• 连接器类型：Straight、Orthogonal、Bezier
• 使用 sourcePoint/targetPoint 创建独立连接器
• 使用 sourceID/targetID 连接节点
• 多线段配置
• Bezier 控制点和线段编辑方向
• 箭头/装饰器自定义
• 连接器事件和交互
• getConnectorDefaults 模式

---

标签和注释

📄 阅读： references/labels-and-annotations.md

阅读时机：

• 为节点或连接器添加文本标签
• 设置注释文本样式（字体、颜色、粗体、对齐方式）
• 使标签可拖动或可编辑
• 相对于节点/连接器定位标签
• 处理特定于标签的事件

涵盖内容：

• 节点和连接器上的 annotations 数组
• 标签的 content、style、offset、alignment
• 节点标签与连接器标签
• 标签交互（双击编辑、拖动）
• 标签外观（背景、边框、内边距）
• 标签事件

---

端口

📄 阅读： references/ports.md

阅读时机：

• 在节点上创建命名连接点
• 控制连接器与节点的连接位置
• 设置端口样式和位置
• 限制连接器只能连接到特定端口
• 处理端口交互事件

涵盖内容：

• 节点上的端口类型和 ports 数组
• 端口定位（offset、alignment）
• 端口外观（形状、填充、描边）
• 通过 sourcePortID/targetPortID 将连接器连接到特定端口
• 端口交互和可见性选项
• 端口事件

---

形状和样式

📄 阅读： references/shapes-and-styles.md

阅读时机：

• 选择合适的形状类型（Flow、Basic、Path、Image、HTML、Native SVG）
• 应用填充颜色、渐变和描边样式
• 使用 CSS 或主题自定义节点外观
• 了解形状属性结构

涵盖内容：

• shape.type 选项：Flow、Basic、Path、Image、HTML、Native
• 流程图形状值（Terminator、Process、Decision 等）
• 基本形状值（Rectangle、Ellipse、Diamond 等）
• 样式属性：fill、strokeColor、strokeWidth、strokeDashArray、opacity
• 线性和径向渐变
• 阴影效果
• 基于 CSS 类的样式

---

BPMN 图表

📄 阅读： references/bpmn-diagrams.md

适合阅读的场景：

• 使用 BPMN 表示法对业务流程进行建模
• 使用 BPMN 专属图形（活动、事件、网关）
• 绘制顺序流、消息流和关联
• 添加数据对象、数据源、文本注释和组

涵盖内容：

• 注入 BpmnDiagrams 模块
• BPMN 图形类型：shape.type = 'Bpmn'
• 活动：任务类型、子流程、展开的子流程
• 事件：开始、结束、中间事件及其触发器
• 网关：排他、并行、包容、复杂
• 流：顺序流、消息流、关联
• 数据对象和数据源
• BPMN 组和文本注释

---

UML 图表

📄 阅读： references/uml-diagrams.md

适合阅读的场景：

• 创建包含属性和方法的 UML 类图
• 对关系进行建模（关联、泛化、依赖）
• 创建包含生命线和消息的 UML 时序图
• 使用分类器（类、接口、枚举、协作）

涵盖内容：

• UML 类图图形（shape.type = 'UmlClassifier'）
• 分类器类型：类、接口、枚举、协作
• 属性、操作和成员语法
• UML 关系连接器类型
• UML 时序图（shape.type = 'UmlActivity'）
• 生命线、消息和片段

---

ER 图表

📄 阅读： references/entity-relationship-diagrams.md

适合阅读的场景：

• 创建实体关系图以呈现数据库结构
• 创建代表数据库表及其字段的 ER 实体节点
• 定义字段属性（主键、外键、数据类型、约束）
• 在运行时添加或移除实体字段
• 使用 ER 关系连接器和多重性连接实体
• 为 ER 实体标题、字段行和交替行颜色设置样式
• 通过事件跟踪实体字段变更

涵盖内容：

• 注入 ErDiagrams 模块（Diagram.Inject(ErDiagrams)）
• ER 实体节点：shape.type = 'Er' 和 ErShapeModel
• 标题配置：annotation、height、style
• 字段配置：id、name、dataType、isPrimaryKey、isForeignKey、constraints
• addErField / removeErField 运行时方法
• fieldDefaults：alternateRowColors、height
• 字段级和节点级样式覆盖
• 用于跟踪字段变更的 erEntityChanged 事件
• 使用 ErConnectorShapeModel 的 ER 关系连接器
• 鸦足表示法多重性：One、Many、ZeroOrOne、OneOrMany、ZeroOrMany、OneAndOnlyOne

---

布局

📄 阅读： references/layouts.md

适合阅读的场景：

• 自动以树形、层级或放射状模式排列节点
• 根据父子数据创建组织结构图
• 根据数据源构建思维导图
• 配置包含决策/流程图形的流程图布局
• 自定义布局间距、方向和对齐方式

涵盖内容：

• HierarchicalTree — 自上而下/从左到右的树形布局
• OrganizationalChart — 经典组织结构图，包含 getNodeDefaults / getConnectorDefaults
• MindMap — 分支式思维导图布局
• RadialTree — 圆形放射状布局
• Flowchart 布局（自动排列流程）
• 用于多父级层级结构的 ComplexHierarchicalTree
• layout 属性：type、orientation、margin、horizontalSpacing、verticalSpacing
• LayoutAnimation 模块
• 布局事件

---

泳道

📄 阅读： references/swimlanes.md

适用场景：

• 创建多泳道流程图
• 添加阶段以表示时间线或不同阶段
• 配置泳道标题和方向
• 将子节点放置在泳道内
• 使用符号面板中的泳道形状

涵盖内容：

• 泳道 shape.type = 'SwimLane'
• 泳道和阶段配置
• 标题文本、大小和方向
• 泳道内的子节点
• 泳道面板集成
• 泳道交互（添加/移除泳道）

---

组和容器

📄 阅读： references/groups-and-containers.md

适用场景：

• 将多个节点编组，以便整体移动/选择
• 在运行时向组添加/移除子节点
• 使用容器节点为子节点提供可视边界
• 配置内边距和自动适应子节点行为

涵盖内容：

• 组节点 shape.type = 'Group' 和 children 数组
• 通过图表方法对节点进行编组/取消编组
• 在运行时添加子节点
• 容器节点配置
• 容器的内边距和自动适应行为

---

符号面板

📄 阅读： references/symbol-palette.md

适用场景：

• 在图表应用中添加可拖放的形状侧边栏
• 定义自定义符号集（面板）
• 自定义面板图标大小、搜索行为和折叠面板
• 处理 symbolDragEnter/symbolDrop 事件

涵盖内容：

• SymbolPaletteComponent 与 DiagramComponent 一同设置
• 使用符号数组定义 palettes
• 使用 getSymbolInfo 自定义显示
• 面板折叠：展开/折叠分组
• 搜索功能
• 符号预览大小配置
• 面板事件

---

数据绑定

📄 阅读： references/data-binding.md

适用场景：

• 根据 JSON 或远程数据自动生成图表
• 为层级结构映射 id 和 parentId 字段
• 使用 DataManager 处理远程或经过筛选的数据
• 根据数据属性自定义节点外观（setNodeTemplate）
• 连接到 PostgreSQL 或外部数据源

涵盖内容：

• dataSourceSettings 属性
• id、parentId 字段映射
• 使用本地数组或远程 URL 的 DataManager
• 使用 getNodeDefaults 和 setNodeTemplate 实现数据驱动的样式
• PostgreSQL 数据源集成
• 根据扁平 JSON 数据渲染组织结构图

---

交互和工具

📄 阅读： references/interaction-and-tools.md

适用场景：

• 启用/禁用节点和连接器交互（拖动、调整大小、选择）
• 切换图表工具模式（指针、绘制、平移）
• 配置图表约束
• 添加自定义键盘命令或工具栏操作
• 实现撤销/重做
• 设置上下文菜单或用户控件

涵盖内容：

• DiagramConstraints、NodeConstraints、ConnectorConstraints
• tool 属性：DiagramTools.Default、ZoomPan、DrawOnce
• 选择、拖动、调整大小、旋转交互
• 用于键盘快捷键的 commands
• 撤销/重做（UndoRedo 模块）
• 上下文菜单（DiagramContextMenu 模块）
• 用于节点自定义操作按钮的用户控件
• Snapping 模块和对齐设置

---

序列化和导出

📄 阅读： references/serialization-and-export.md

适用场景：

• 将图表状态保存为 JSON 并进行恢复
• 将图表导出为 PNG、JPEG 或 SVG
• 打印图表内容
• 导入 Visio（.vsdx）文件
• 从 EJ1 图表格式迁移

涵盖内容：

• diagram.saveDiagram() 和 diagram.loadDiagram(json)
• 注入 PrintAndExport 模块
• 导出设置：格式、区域、边距、背景
• 打印对话框和选项
• Visio 文件导入（visio.md）
• EJ1 序列化兼容性（Ej1Serialization 模块）

---

图表设置

📄 阅读： references/diagram-settings.md

阅读时机：

• 管理图表图层（可见性、锁定、排序）
• 为大型图表启用虚拟化以提升性能
• 配置网格线、吸附和标尺
• 设置页面大小、方向和边距
• 配置滚动行为和限制
• 为图表元素添加工具提示
• 使用 Overview 组件进行缩略图导航
• 启用本地化或 RTL 支持
• 了解无障碍功能

涵盖内容：

• 图层：添加、锁定、设置可见性、活动图层
• 用于大型图表的 Virtualization 模块
• 网格线：点、线、吸附设置
• 标尺配置
• scrollSettings：scrollLimit、minZoom、maxZoom
• pageSettings：大小、方向、背景、multiplePage
• 节点和连接器上的工具提示
• OverviewComponent 缩略图设置
• 本地化和 RTL
• ARIA 和键盘无障碍支持

---

快速入门示例

最简流程图

import { DiagramComponent, NodeModel, ConnectorModel, Inject, UndoRedo } from '@syncfusion/ej2-react-diagrams';

const nodes: NodeModel[] = [
  { id: 'start', offsetX: 300, offsetY: 80, width: 140, height: 50,
    shape: { type: 'Flow', shape: 'Terminator' }, annotations: [{ content: 'Start' }] },
  { id: 'process', offsetX: 300, offsetY: 180, width: 140, height: 50,
    shape: { type: 'Flow', shape: 'Process' }, annotations: [{ content: 'Process' }] },
  { id: 'end', offsetX: 300, offsetY: 290, width: 140, height: 50,
    shape: { type: 'Flow', shape: 'Terminator' }, annotations: [{ content: 'End' }] },
];
const connectors: ConnectorModel[] = [
  { id: 'c1', sourceID: 'start', targetID: 'process' },
  { id: 'c2', sourceID: 'process', targetID: 'end' },
];

export default function App() {
  return (
    <DiagramComponent id="diagram" width={'100%'} height={'500px'}
      nodes={nodes} connectors={connectors}
      getConnectorDefaults={(obj) => { obj.type = 'Orthogonal'; return obj; }}>
      <Inject services={[UndoRedo]} />
    </DiagramComponent>
  );
}

CSS 导入：@import '@syncfusion/ej2-react-diagrams/styles/material.css';，以及 ej2-base、ej2-popups、ej2-splitbuttons、ej2-navigations 的同级 CSS。

---

常见模式

模式 1：从数据源创建组织结构图

import { DiagramComponent, HierarchicalTree, DataBinding, Inject } from '@syncfusion/ej2-react-diagrams';
import { DataManager } from '@syncfusion/ej2-data';

const data = [
  { Name: 'CEO' },
  { Name: 'CTO', ReportingPerson: 'CEO' },
  { Name: 'Dev Lead', ReportingPerson: 'CTO' },
];

export default function App() {
  return (
    <DiagramComponent id="diagram" width={'100%'} height={'500px'}
      dataSourceSettings={{ id: 'Name', parentId: 'ReportingPerson', dataManager: new DataManager(data) }}
      layout={{ type: 'OrganizationalChart' }}
      getNodeDefaults={(node) => { node.width = 120; node.height = 40; return node; }}
      getConnectorDefaults={(obj) => { obj.type = 'Orthogonal'; return obj; }}>
      <Inject services={[DataBinding, HierarchicalTree]} />
    </DiagramComponent>
  );
}

模式 2：保存和加载图表状态

使用 diagramInstance.saveDiagram() 序列化为 JSON 字符串；使用 diagramInstance.loadDiagram(json) 恢复。注入 UndoRedo 以支持历史记录。完整示例请参阅 references/serialization-and-export.md。

模式 3：带符号面板的图表

将 SymbolPaletteComponent 与 DiagramComponent 一同渲染。使用形状数组定义面板，设置 symbolHeight/symbolWidth，用户即可将形状拖到画布上。完整示例请参阅 references/symbol-palette.md。

---

模块注入参考

只注入图表所用的模块：<Inject services={[HierarchicalTree, DataBinding, UndoRedo]} />

模块	用途
HierarchicalTree	树形和组织结构图布局
MindMap	思维导图布局
RadialTree	放射状/圆形布局
ComplexHierarchicalTree	多父级层级结构
DataBinding	数据源集成
UndoRedo	撤销/重做历史记录
Snapping	网格吸附
PrintAndExport	导出和打印
BpmnDiagrams	BPMN 形状
ErDiagrams	ER 图形状和关系
LayoutAnimation	动画布局
DiagramContextMenu	右键上下文菜单
ConnectorBridging	桥接重叠的连接器
ConnectorEditing	编辑连接器线段
Ej1Serialization	加载 EJ1 图表 JSON

---

关键属性

属性	类型	说明
nodes	NodeModel[]	节点定义数组
connectors	ConnectorModel[]	连接器定义数组
layout	LayoutModel	自动布局配置
dataSourceSettings	DataSourceModel	自动生成图表的数据源
getNodeDefaults	(node) => NodeModel	所有节点的默认属性
getConnectorDefaults	(obj) => ConnectorModel	所有连接器的默认属性
setNodeTemplate	(node) => DiagramElement	节点的自定义模板渲染
tool	DiagramTools	活动交互工具模式
snapSettings	SnapSettingsModel	网格和吸附配置
scrollSettings	ScrollSettingsModel	滚动限制和缩放范围
pageSettings	PageSettingsModel	页面大小、方向、背景
constraints	DiagramConstraints	启用/禁用图表级交互
width	string	图表画布宽度（例如，'100%'）
height	string	图表画布高度（例如，'600px'）

相关组件

• 图表 - 数据驱动的图表和图形
• 看板 - 看板可视化
• 数据网格 - 表格数据展示