syncfusion-angular-diagram

实现 Syncfusion Angular Diagram

何时使用此技能

在需要以下操作时使用此技能：

• 创建可视化图表（流程图、组织结构图、BPMN、UML）
• 构建交互式图表，包含节点和连接器
• 应用布局（层次结构、组织结构图、思维导图、径向、流程图）
• 设计 BPMN 或 UML 业务流程图
• 添加交互功能（拖动、调整大小、选择、撤销/重做）
• 将图表导出或序列化为 JSON/图像

重要：必须验证 API

必须验证 API：生成代码示例前，请务必阅读参考文件（references/*.md），核实 API 类名、属性和签名。不要假定或推断类名。 ⚠️ 编写任何代码前，请先查看下方的常见错误部分，以避免使用已知无效的 API 和属性。

组件概览

Syncfusion Angular Diagram 组件提供可视化画布，用于创建和编辑图表：

核心概念

1. 节点 - 矩形、圆形、流程图形状、自定义形状
2. 连接器 - 连接节点的线条（直线、正交、贝塞尔）
3. 标签 - 节点和连接器上的文本注释
4. 端口 - 节点边界上的连接点
5. 泳道 - 流程图中的水平/垂直泳道
6. 布局 - 自动定位（层次结构、组织结构图、思维导图等）
7. BPMN 形状 - 业务流程图标准化形状
8. UML 图表 - 类图和时序图表示法
9. 符号面板 - 可拖动的符号库
10. 数据绑定 - 根据 JSON 数据渲染图表

主要功能

• **交互式编辑：**拖动、调整大小、旋转节点和连接器
• **自动布局：**层次结构、组织结构图、思维导图、径向、流程图布局
• **BPMN 和 UML：**用于标准图表的内置形状库
• **序列化：**以 JSON 格式保存/加载图表
• **导出：**导出 PNG、SVG、PDF 图像并打印
• **撤销/重做：**完整的历史记录支持
• **虚拟化：**高效渲染大型图表
• **无障碍支持：**符合 WCAG 2.1 标准，支持键盘导航

文档与导航指南

从入门指南开始，然后跳转到所需的特定功能：

图表构建基础

📄 阅读：references/getting-started.md

• 安装和依赖项
• 主题设置（material、bootstrap、fabric）
• CSS/SCSS 导入
• DiagramComponent 基本用法
• 模块注入模式
• 独立组件设置

📄 阅读：references/nodes.md

• 创建节点并将其添加到图表
• 偏移和定位（offsetX、offsetY）
• 节点尺寸（width、height）
• 内置形状（Flow、Basic、Path）
• 自定义样式（fill、stroke、opacity）
• 节点模板和外观
• 展开/折叠节点组
• 节点事件（点击、选择、拖动）
• 用于设置默认样式的 getNodeDefaults 模式

📄 阅读：references/connectors.md

• 三种连接器类型：直线、正交、贝塞尔
• 线段配置和路径查找
• 使用 sourceID 和 targetID 连接节点
• 连接器中的多个线段
• 贝塞尔控制点和方向
• 连接器自定义（stroke、fill、虚线）
• 连接器事件和交互
• 用于设置默认样式的 getConnectorDefaults 模式

标签、端口与样式

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

• 为节点和连接器添加注释
• 标签外观（字体、颜色、粗体、斜体、对齐方式）
• 在连接器上定位标签（起点、终点、中心）
• 节点标签与连接器标签
• 标签交互（编辑模式、拖动、调整大小）
• 标签事件（编辑、聚焦、失焦）
• 使用 markdown 或 HTML 设置格式

📄 阅读： references/ports.md

• 端口类型及其在节点上的位置
• 自定义外观（形状、填充、尺寸）
• 将连接器连接到特定端口
• 连接可见性与约束
• 端口交互与可见性
• getPortDefaults 模式

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

• 内置形状类型：Flow、Basic、Path、Image、HTML、Native SVG
• 流程图形状（流程、决策、开始、结束等）
• 样式属性（填充、描边、strokeWidth、dashArray、阴影）
• CSS 类与主题自定义
• 渐变和图案填充

高级图表

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

• 实体关系图设计与数据库架构可视化
• 使用 ErShapeModel 配置实体关系图实体节点
• 实体标题、字段与约束（主键、外键、唯一、非空）
• 运行时字段管理（添加、移除、修改）
• 实体样式与交替行颜色
• 实体关系与使用 Crow's Foot 多重性的连接器
• 完整的数据库架构示例（Customer-Order-Product）

📄 阅读： references/bpmn-diagrams.md

• BPMN 模块注入与设置
• BPMN 形状概览与标准符号
• 活动（任务、子流程、展开的子流程、循环）
• 事件（开始、结束、中间捕获/抛出）
• 网关（排他、并行、包容、复杂）
• 流（顺序流、消息流、关联）
• 数据对象与数据源
• 组与文本注释
• BPMN 专用样式与标签

📄 阅读： references/uml-diagrams.md

• UML 类图形状
• 分类器形状（类、接口、枚举、包、组件）
• 类属性、方法、可见性修饰符
• UML 关系（关联、泛化、聚合、组合）
• 包含参与者、消息和激活框的 UML 序列图
• 具有 6 种构造型的序列参与者（Actor、Boundary、Control、Entity、Database、Default）
• 具有 6 种类型的序列消息（Synchronous、Asynchronous、Reply、Create、Delete、Self）
• 激活框与销毁标记
• 用于表示参与者终止的销毁标记
• 完整的登录流程与交互序列示例

布局与结构

📄 阅读： references/layouts.md

• 层级树布局，支持从上到下、从下到上、从左到右、从右到左
• 组织结构图布局
• 思维导图布局（子树、分支）
• 径向树布局
• 带泳道的流程图布局
• 带扩展节点的复杂层级树
• 自动布局配置
• 布局自定义（方向、间距、边距）
• 布局事件与完成状态

📄 阅读： references/swimlanes.md

• 泳道结构概览（标题、子项、阶段）
• 在泳道中创建泳道和阶段
• 泳道子项的位置与约束
• 泳道标题与标签
• 泳道调色板集成
• 泳道交互（调整大小、移动、添加/移除子项）

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

• 将节点组合在一起
• 组操作（添加/移除子项、展开/折叠）
• 带内边距和布局的容器节点
• 容器内子项的位置
• 容器约束

交互与工具

📄 阅读： references/symbol-palette.md

• SymbolPaletteComponent 的设置与集成
• 定义调色板符号和类别
• 将符号拖放到图表中
• 自定义符号调色板（图标、搜索、类别、大小）
• 符号调色板事件
• 创建自定义符号库

📄 阅读： references/data-binding.md

• 配置 DataManager 和 dataSourceSettings
• 将数据映射到节点（id、parentId、nodeTemplate）
• 根据 JSON 数据呈现组织结构图
• 集成 PostgreSQL 数据源
• 使用 setNodeTemplate 设置数据驱动的节点样式
• 动态更新和刷新数据

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

• 节点选择、拖动和调整大小交互
• 工具模式（指针、绘制、平移、平移选择）
• 约束（节点约束、连接器约束、图表约束）
• 命令（键盘快捷键、自定义命令）
• 撤销和重做功能
• 上下文菜单（右键菜单）
• 用户句柄（自定义连接句柄）

序列化与导出

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

• saveDiagram 和 loadDiagram（JSON 序列化）
• Mermaid 语法支持（saveDiagramAsMermaid、loadDiagramFromMermaid）
• 使用 isModified 属性检测未保存的更改
• 导出为图像格式（PNG、SVG、PDF）
• 打印图表功能
• Visio 文件导入（.vsdx）
• EJ1 API 迁移序列化
• 自定义序列化处理

配置与设置

📄 阅读： references/diagram-settings.md

• 图层（添加、锁定、可见性、排序）
• 虚拟化（大型图表的性能优化）
• 网格线（吸附、点/线、步长）
• 标尺（水平和垂直测量标尺）
• 滚动设置（自动滚动、平移）
• 页面设置（大小、方向、边距、适应页面）
• 工具提示配置
• 用于导航的概览面板
• 本地化和语言支持
• 无障碍功能（WCAG、ARIA 标签、键盘导航）

---

快速入门示例

以下是一个可供入门的最小图表示例：

import { Component, Inject } from '@angular/core';
import { DiagramComponent, DiagramModule } from '@syncfusion/ej2-angular-diagrams';

@Component({
  selector: 'app-diagram',
  template: `
    <ejs-diagram #diagram 
      width="100%" 
      height="600px"
      [nodes]="nodes"
      [connectors]="connectors">
    </ejs-diagram>
  `,
  standalone: true,
  imports: [DiagramModule]
})
export class DiagramComponent {
  nodes = [
    {
      id: 'start',
      width: 80,
      height: 80,
      offsetX: 150,
      offsetY: 150,
      shape: { type: 'Flow', shape: 'Terminator' },
      annotations: [{ content: 'START' }]
    },
    {
      id: 'process',
      width: 100,
      height: 80,
      offsetX: 350,
      offsetY: 150,
      shape: { type: 'Flow', shape: 'Process' },
      annotations: [{ content: 'Process' }]
    },
    {
      id: 'end',
      width: 80,
      height: 80,
      offsetX: 550,
      offsetY: 150,
      shape: { type: 'Flow', shape: 'Terminator' },
      annotations: [{ content: 'END' }]
    }
  ];

  connectors = [
    { id: 'connector1', sourceID: 'start', targetID: 'process' },
    { id: 'connector2', sourceID: 'process', targetID: 'end' }
  ];
}

如需详细设置，请阅读 入门指南。

---

模块注入模式

Syncfusion Diagram 使用 Inject 指令注册功能：

import { Component, Inject } from '@angular/core';
import { BpmnDiagrams, Swimlane, SymbolPalette } from '@syncfusion/ej2-angular-diagrams';
Diagram.Inject(BpmnDiagrams, SymbolPalette)

务必注入所用的功能。 这样可以缩小打包体积，并明确依赖关系。

---

常见模式

1. 获取节点/连接器默认值

getNodeDefaults(node: NodeModel): NodeModel {
  return {
    shape: { type: 'Flow', shape: 'Process' },
    style: { fill: '#90EE90', stroke: '#228B22' }
  };
}

2. 将数据绑定到节点

dataSourceSettings: {
  id: 'id',
  parentId: 'parentId',
  dataSource: yourDataArray
}

3. 处理选择

diagram.selectionChange((args) => {
  console.log('Selected:', args.newItems);
});

4. 导出图表

diagram.exportDiagram({format: 'PNG', fileName: 'diagram'});

5. 序列化图表

const diagramData = diagram.saveDiagram();
localStorage.setItem('diagram', JSON.stringify(diagramData));

---

常见错误

❌ 形状类型错误

错误写法：

// ❌ WRONG - Shape type should be 'Flow', not 'FlowShape'
shape: { type: 'FlowShape', shape: 'Process' }

正确写法：

// ✅ CORRECT - Use 'Flow' for flowchart shapes
shape: { type: 'Flow', shape: 'Process' }

// ✅ CORRECT - Use 'Bpmn' for BPMN shapes
shape: { type: 'Bpmn', shape: 'Task' }

// ✅ CORRECT - Use 'Basic' for basic geometries
shape: { type: 'Basic', shape: 'Rectangle' }

参考： references/shapes-and-styles.md

❌ Diagram.Inject() 中的模块无效

错误写法：

// ❌ Swimlane is NOT an injectable module
Diagram.Inject(BpmnDiagrams, Swimlane);

正确写法：

// ✅ Only inject verified documented modules
Diagram.Inject(BpmnDiagrams);

📄 请在以下文件中确认可注入的模块：references/bpmn-diagrams.md， references/swimlanes.md

---

❌ Annotation 样式中不存在 whiteSpace

错误写法：

// ❌ whiteSpace is NOT a valid TextStyleModel property
annotations: [{
  content: 'Multi\nLine',
  style: { fontSize: 11, whiteSpace: 'pre-wrap' }  // ❌
}]

正确写法：

// ✅ Use \n in content — valid style props:
// fontSize, color, bold, italic, fontFamily,
// opacity, strokeColor, strokeWidth, fill
annotations: [{
  content: 'Multi\nLine',
  style: { fontSize: 11, color: '#000', bold: true }
}]

📄 请在以下文件中确认 Annotation 样式属性： references/labels-and-annotations.md

---

❌ DiagramComponent 上不存在 updateNode()

错误写法：

// ❌ updateNode() does not exist in EJ2 Diagram API
this.diagram.updateNode('nodeId', { style: { fill: '#ff0000' } });

正确写法：

// ✅ getObject() → mutate property → dataBind()
const node = this.diagram.getObject('nodeId') as NodeModel;
if (node) {
  node.style!.fill = '#ff0000';
  this.diagram.dataBind(); // ← always required after mutation
}

📄 请在以下文件中确认运行时 API：references/nodes.md

❌ 数据绑定配置

错误写法：

// ❌ WRONG - Missing proper data source setup
nodes = this.employeeData; // Direct array assignment

正确写法：

// ✅ CORRECT - Use dataSourceSettings with proper mapping
dataSourceSettings: {
  id: 'EmployeeID',
  parentId: 'ReportingManagerID',
  dataSource: this.employeeData
}

// Then configure setNodeTemplate for rendering:
setNodeTemplate(obj: NodeModel): void {
  // obj contains the data row
  obj.width = 100;
  obj.height = 60;
  obj.annotations = [{
    content: obj.data.EmployeeName
  }];
}

参考： references/data-binding.md

❌ 独立组件设置

错误写法：

// ❌ WRONG - Using traditional decorator without standalone
@Component({
  selector: 'app-diagram',
  templateUrl: './component.html',
  imports: [DiagramModule]
  // Missing: standalone: true
})

正确写法：

// ✅ CORRECT - Mark as standalone component
@Component({
  selector: 'app-diagram',
  templateUrl: './component.html',
  standalone: true,     // ← Add this
  imports: [CommonModule, DiagramModule], 
})

参考： references/getting-started.md

⚠️ 性能提示

• 虚拟化： 对于包含 1000 个以上节点的图表，请在 references/diagram-settings.md 中启用虚拟化
• 布局性能： 为复杂层次结构预先计算位置
• 连接器更新： 使用 connectorChanges，而不是重新创建连接器
• 导出大型图表： 导出大于 50MB 的 PDF 时，请采用增量方式

---

后续步骤

• 选择图表类型：流程图、BPMN、UML、组织架构图等
• 阅读上方相关的参考文件
• 查看 Syncfusion Diagram 文档 了解 API 详情
• 在其示例代码库中探索示例