syncfusion-blazor-diagram

实现 Syncfusion Blazor Diagram

使用 Syncfusion Blazor Diagram 组件构建交互式图表的综合技能——流程图、组织结构图、思维导图、BPMN 流程图、UML 时序图、网络图等。

何时使用此技能

在以下情况下使用此技能：

• 在 Blazor 中创建流程图、组织结构图、思维导图或网络图
• 使用 SfDiagramComponent、节点、连接器或形状
• 配置自动布局（分层、径向、思维导图、组织结构图、流程图）
• 使用 BPMN 形状实现 BPMN 流程图
• 构建用于流程建模的泳道图
• 添加用于拖放式图表构建的符号面板
• 从集合或远程源绑定图表数据
• 实现图表交互（选择、拖动、调整大小、缩放、平移）
• 将图表导出为 PNG/JPEG/SVG 或打印图表
• 序列化并恢复图表状态（保存/加载）
• 启用协作式实时编辑
• 添加 UML 时序图
• 处理图表事件、注释和端口

重要：必须验证 API

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

快速入门

@using Syncfusion.Blazor.Diagram

<SfDiagramComponent Width="100%" Height="600px" Nodes="@nodes" Connectors="@connectors" />

@code {
    DiagramObjectCollection<Node> nodes = new DiagramObjectCollection<Node>
    {
        new Node
        {
            ID = "node1", OffsetX = 150, OffsetY = 150,
            Width = 100, Height = 50,
            Style = new ShapeStyle { Fill = "#6BA5D7", StrokeColor = "white" },
            Annotations = new DiagramObjectCollection<ShapeAnnotation>
            {
                new ShapeAnnotation { Content = "Start" }
            }
        }
    };
    DiagramObjectCollection<Connector> connectors = new DiagramObjectCollection<Connector>
    {
        new Connector { ID = "conn1", SourceID = "node1", TargetID = "node2" }
    };
}

常见模式

目标	参考
首次设置图表	references/getting-started.md
添加/配置节点	references/nodes.md
添加/配置连接器	references/connectors.md
使用内置形状	references/shapes.md
添加文本标签	references/annotations.md
定义连接点	references/ports.md
组织结构图/自动布局	references/layout.md
泳道图	references/swimlane.md
BPMN 流程图	references/bpmn.md
拖放式面板	references/symbol-palette.md
将数据绑定到图表	references/data-binding.md
选择、拖动、缩放	references/interaction.md
处理图表事件	references/events.md
保存和加载图表	references/serialization.md
导出/打印	references/export-print.md
CSS/主题样式	references/styling.md
UML 时序图	references/uml-sequence.md
实时协作	references/collaborative-editing.md
上下文菜单、工具提示、标尺、本地化	references/advanced-features.md
缩略概览/鸟瞰导航	references/overview-component.md

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

• NuGet 包安装（Syncfusion.Blazor.Diagram）
• 服务注册和命名空间导入
• Blazor Server、WebAssembly、MAUI 的配置
• CSS/主题配置
• 最简可运行图表示例

节点

📄 阅读： references/nodes.md

• 创建和配置节点
• 节点类型：基本、流程形状、路径、图像、HTML、原生
• 节点定位、尺寸、z 顺序
• 节点样式（填充、描边、不透明度）
• 展开/折叠子项
• 节点事件和交互

连接器

📄 阅读： references/connectors.md

• 在节点之间或独立创建连接器
• 线段类型：直线、正交线、贝塞尔曲线
• 每个连接器支持多个线段
• 箭头、线条样式和装饰
• 连接器交互（弯折、拖动端点）
• 连接器事件

形状

📄 阅读： references/shapes.md

• 内置基本形状（矩形、椭圆、三角形等）
• 流程形状（流程、决策、终止符等）
• 路径形状（自定义 SVG 路径）
• 图像和 HTML 内容形状
• 原生 SVG 形状
• 选择合适的形状类型

注释

📄 阅读： references/annotations.md

• 为节点和连接器添加文本标签
• 注释的位置和对齐方式
• 字体、颜色和样式自定义
• 内联编辑注释
• 每个元素支持多个注释
• 注释交互事件
• 交互限制：AnnotationConstraints 标志、DragLimit（PathAnnotation）
• 使用 Hyperlink（Url、Content、OpenMode）创建超链接
• 事件：SelectionChanging/Changed、PositionChanging/Changed、SizeChanging/Changed、RotationChanging/Changed、TextChanging/Changed

端口

📄 阅读： references/ports.md

• 连接端口（节点上的固定连接点）
• 动态端口（运行时创建）
• 端口定位（相对和绝对）
• 端口外观和可见性
• 限制连接只能使用特定端口

布局

📄 阅读： references/layout.md

• 自动布局概览及各类型的适用场景
• 分层树形布局（从上到下、从左到右）
• 组织结构图布局
• 思维导图布局
• 放射状树形布局
• 流程图布局
• 力导向树形布局
• 复杂分层布局
• 布局间距、边距和方向设置
• 布局事件和回调
• await DoLayoutAsync() — 添加或移除节点后，在运行时刷新布局

泳道

📄 阅读： references/swimlane.md

• 创建泳道图
• 添加泳道并配置泳道属性
• 配置阶段（垂直/水平阶段）
• 集成泳道符号面板
• 泳道交互

<SfDiagramComponent Height="600px" Swimlanes="@swimlanes" />

@code {
    DiagramObjectCollection<Swimlane> swimlanes = new();

    protected override void OnInitialized()
    {
        swimlanes.Add(new Swimlane
        {
            ID = "swimlane1",
            OffsetX = 400, OffsetY = 300,
            Width = 600, Height = 200,
            Lanes = new DiagramObjectCollection<Lane>()
            {
                new Lane(){
                Height = 100,
                Header = new SwimlaneHeader(){
                    Width = 30,
                    Annotation = new ShapeAnnotation(){ Content = "Consumer" }
                },
                Children = new DiagramObjectCollection<Node>()
                {
                    new Node(){Height = 50, Width = 50, LaneOffsetX = 250, LaneOffsetY = 30},
                }
                },
            }
        });
    }
}

BPMN

📄 阅读： references/bpmn.md

• BPMN 形状类型（事件、活动、网关、数据）
• BPMN 事件类型（开始、结束、中间、边界）
• BPMN 活动类型（任务、子流程、调用活动）
• BPMN 网关类型（排他、并行、包容等）
• BPMN 连接器（顺序流、消息流、关联）
• 数据对象和数据存储
• 展开的子流程
• BPMN 文本注释

// Exclusive gateway (XOR)
nodes.Add(new Node
{
    ID = "gateway1", OffsetX = 300, OffsetY = 200, Width = 50, Height = 50,
    Shape = new BpmnGateway
    {
        GatewayType = BpmnGatewayType.Exclusive
    }
});

符号面板

📄 阅读： references/symbol-palette.md

• 设置 SfSymbolPaletteComponent
• 定义面板组和符号
• 自定义符号和模板
• 从面板拖放到图表
• 面板搜索和自定义

数据绑定

📄 阅读： references/data-binding.md

• 从扁平列表或 IEnumerable 绑定图表
• 分层数据绑定（父子关系）
• 集成远程数据源
• 运行时 CRUD：await ReadDataAsync(query?)、await InsertDataAsync(data)、await UpdateDataAsync(keyField, data)、await DeleteDataAsync(keyField, value)
• await RefreshDataSourceAsync() — 重新加载所有数据并重建布局
• 将数据字段映射到节点/连接器属性

交互与命令

📄 阅读： references/interaction.md

• 选择：Select(collection, multipleSelection?)、SelectAll()、UnSelect(obj)、ClearSelection()
• 拖动、调整大小和旋转元素（用户交互与编程操作）
• 编程变换：Drag(obj, tx, ty)、Rotate(obj, angle, pivot?)、Scale(obj, sx, sy, pivot)
• 缩放和平移：鼠标滚轮、工具栏、Zoom(factor, focusPoint)、ResetZoom()、Pan(hOffset, vOffset, focusPoint?)
• BringIntoView(DiagramRect) — 滚动视口以显示某个区域
• BringIntoCenter(DiagramRect) — 滚动视口以将某个区域置于中心
• FitToPage(FitOptions?) — 使内容适应视口（同步；FitMode.Width/Height/Both、DiagramRegion.Content/PageSettings）
• Nudge(Direction, int?) — 按像素移动所选元素；默认 1px；Direction.Top/Bottom/Left/Right
• Z 顺序：BringToFront()、BringForward()、SendBackward()、SendToBack() — 必须先调用 Select()
• 剪贴板：Copy()、Cut()、Paste(collection?)、Delete(collection?)
• 分组/取消分组：Group()、Ungroup()、AddChildAsync(group, child)、RemoveChild(group, child)
• 行内文本编辑：StartTextEdit(obj, annotationId?)
• 键盘快捷键（内置表格）和 CommandManager（通过子组件自定义/覆盖快捷键）
• CommandManager 使用 KeyboardCommand + KeyGesture（DiagramKeys + ModifierKeys）+ CommandKeyArgs
• 与网格或对象对齐
• 对齐、间距和尺寸命令（SetAlign、SetDistribute、SetSameSize — 均为同步操作）
• 用户句柄（选中时显示的自定义操作按钮）
• 撤销/重做：Undo()、Redo()（同步）；使用 StartGroupAction() / EndGroupAction() 将多个步骤合并为一次撤销操作
• 历史记录：AddHistoryEntry(entry)、ClearHistory()
• 实用工具：GetObject(id)、GetPageBounds(x?, y?)、Clear()（移除所有元素）
• 批量更新：BeginUpdate() + await EndUpdateAsync() — 将多项更改合并为一次渲染
• 添加多个元素：await AddDiagramElementsAsync(DiagramObjectCollection<NodeBase>)

事件

📄 阅读： references/events.md

• 图表级事件（Created、Click、Drop）
• 节点事件（NodeCreating、PositionChanged、SizeChanged）
• 连接线事件（ConnectionChanged、SegmentChanged）
• 选择事件（SelectionChanged）
• 历史记录变更事件（用于撤销/重做的 HistoryChanged）
• 事件参数类型和用法模式

序列化

📄 阅读： references/serialization.md

• 将图表状态保存为 JSON 字符串
• 从已保存的 JSON 加载图表
• 自定义序列化属性
• 局部图表保存与恢复模式

导出与打印

📄 阅读： references/export-print.md

• 导出为 PNG、JPEG、SVG 格式
• 导出区域选项（图表、页面、内容）
• 缩放和边距设置
• 打印配置
• 自定义页面大小和方向
• 打印时将图表适配到单页

样式

📄 阅读： references/styling.md

• CSS 类自定义（CssClass 属性）
• 内置主题（Material、Bootstrap、Fluent、Tailwind）
• 节点和连接线样式属性
• 选择和悬停样式
• Theme Studio 自定义
• CSS 变量覆盖

UML 时序图

📄 阅读： references/uml-sequence.md

• UML 时序图设置
• 生命线和激活框
• 消息类型（同步、异步、返回、创建、销毁）
• UML 交互图形和连接线
• await UpdateFromModelAsync() — 编程修改模型后刷新图表

UML 类图

📄 阅读： references/uml-class-diagram.md

• 创建类、接口和枚举节点，并设置属性、方法和成员
• 可见性范围、方法参数、分隔行
• 设置标题、分区标题（UmlSectionHeaderSettings）和行级 TextStyle 的样式
• 六种关系类型：关联、聚合、组合、继承、依赖、实现
• 单向／双向关联流；多重性标签
• 在运行时添加和移除成员（Add、RemoveAt、Remove）
• CollectionChanging／CollectionChanged 事件；内联文本编辑（F2、StartTextEdit）
• 集成 Symbol Palette，以便拖放 UML 图形

协同编辑

📄 阅读： references/collaborative-editing.md

• 设置实时协同图表编辑
• 配置 SignalR hub
• 集成 Blazor Server 和 WASM 应用
• 处理实时同步和冲突解决
• 增量同步：GetDiagramUpdates(HistoryChangedEventArgs) + await SetDiagramUpdatesAsync(updates) — 高效传播更改

概览组件

📄 阅读： references/overview-component.md

• 添加 SfDiagramOverviewComponent 作为缩略图面板
• 通过 SourceID／ID 将概览关联到主图表
• 使用 Width 和 Height 控制面板大小
• 缩放和平移交互（拖动、调整大小、单击、绘制区域）
• 使用 DiagramOverviewConstraints 启用或禁用交互
• 必需的 @using Syncfusion.Blazor.Diagram.Overview 命名空间。

@using Syncfusion.Blazor.Diagram
@using Syncfusion.Blazor.Diagram.Overview
@using System.Collections.ObjectModel

<SfDiagramComponent ID="element"
                    Width="100%"
                    Height="500px">
</SfDiagramComponent>


<SfDiagramOverviewComponent Height="150px" SourceID="element" />

高级功能

📄 阅读： references/advanced-features.md

• 上下文菜单（内置和自定义项）
• 节点、连接器、端口和用户句柄的工具提示
• 以编程方式显示工具提示：await ShowTooltipAsync(obj) / await HideTooltipAsync(obj) — 需要设置 OpensOn = "Custom"
• 网格线和标尺
• 滚动设置和页面设置
• 容器和分组节点
• 翻转（水平／垂直）
• 约束（限制每个元素的行为）
• 本地化（静态文本翻译）
• 无障碍功能（WCAG 2.1、键盘导航）
• 从经典图表迁移到原生图表

常见错误

注释编辑

⚠️ ShapeAnnotation 或 PathAnnotation 上不存在 AllowEditing。
默认情况下已启用内联编辑 — 无需设置任何属性。
要禁用编辑，请设置 Constraints = AnnotationConstraints.ReadOnly：

// ❌ 错误 — CS0117：不存在 AllowEditing
new ShapeAnnotation { Content = "Label", AllowEditing = false }

// ✅ 正确 — 使用 AnnotationConstraints.ReadOnly 禁用编辑
new ShapeAnnotation { Content = "Label", Constraints = AnnotationConstraints.ReadOnly }

EndUpdateAsync 方法

⚠️ 始终使用 EndUpdateAsync()（异步） — EndUpdate()（同步、非异步）并不存在，会导致编译错误。
同时更改多个属性时，请使用 BeginUpdate()／EndUpdateAsync() — 必须使用 await：

// ❌ 错误 — 不存在 EndUpdate()
diagram.BeginUpdate();
// ... changes ...
diagram.EndUpdate();

// ✅ 正确 — EndUpdateAsync 是异步方法
diagram.BeginUpdate();
// ... changes ...
await diagram.EndUpdateAsync();

Click 事件

**⚠️ ClickEventArgs 名称冲突：**如果页面还使用了 @using Syncfusion.Blazor.Navigations（或 Buttons），
ClickEventArgs 会变得含糊不清。请始终使用限定名称：

// ✅ 在处理程序签名中使用完全限定类型
private void OnClick(Syncfusion.Blazor.Diagram.ClickEventArgs args) { }

⚠️ args.Count 不是 int 字段——它是一个返回 int 的方法。
请勿直接在行内使用 == 比较它，务必先保存结果：

// ❌ 错误 — CS0019：运算符“==”不能应用于“方法组”和“int”类型的操作数
if (args.Count == 2)

// ✅ 正确 — 保存结果后再比较
int clickCount = args.Count;
if (clickCount == 2) { /* 双击 */ }

SizeChanged 事件

⚠️ SizeChangedEventArgs.Element 的类型是 DiagramSelectionSettings，而不是 Node。
使用模式匹配 args.Element is Node n 总会失败，并产生 CS8121。
请将其转换为 DiagramSelectionSettings，并读取 .Nodes[0] 以获取大小发生变化的节点：

// ❌ 错误 — CS8121：DiagramSelectionSettings 无法与 Node 匹配
if (args.Element is Node n) { }

// ✅ 正确 — Element 是 DiagramSelectionSettings
if (args.Element is DiagramSelectionSettings sel && sel.Nodes.Count > 0)
{
    var node = sel.Nodes[0];
    double w = args.NewValue.Width;
    double h = args.NewValue.Height;
}

⚠️ args.NewValue.Width 和 args.NewValue.Height 是普通的 double，不是 double?。
对它们使用 ?? 会导致 CS0019。请直接赋值：

// ❌ 错误 — CS0019
double w = args.NewValue.Width ?? 0;

// ✅ 正确
double w = args.NewValue.Width;

Selection Changed 事件

**⚠️ SelectionChangedEventArgs 名称冲突：**如果页面还使用了 @using Syncfusion.Blazor.Buttons
（或其他 Syncfusion 包），SelectionChangedEventArgs 会变得含糊不清。请始终使用限定名称：

// ✅ 完全限定名称
private void OnSelectionChanged(Syncfusion.Blazor.Diagram.SelectionChangedEventArgs args) { }

⚠️ args.NewValue 是一个 DiagramSelectionSettings 对象——不是 Node，也不是集合：

• 使用模式匹配 args.NewValue is Node 总会失败，并产生 CS8121
• 将 args.NewValue 作为集合迭代会失败——它是单个设置对象
• 唯一正确的做法是读取 _diagram.SelectionSettings.Nodes / .Connectors：

// ❌ 错误 — CS8121：DiagramSelectionSettings 无法与 Node 匹配
if (args.NewValue is Node n) { }

// ❌ 错误 — DiagramSelectionSettings 不是 IEnumerable
foreach (var item in args.NewValue) { }

// ✅ 正确 — 使用图表引用上的 SelectionSettings
foreach (var node in _diagram.SelectionSettings.Nodes)
    Console.WriteLine(node.ID);
foreach (var conn in _diagram.SelectionSettings.Connectors)
    Console.WriteLine(conn.ID);

Text Changed 事件

⚠️ TextChangedEventArgs 不存在——使用它会导致 CS0246。
正确的事件参数类型是 TextChangeEventArgs（没有 d）：

// ❌ 错误 — CS0246：找不到 TextChangedEventArgs
private void OnTextChanged(TextChangedEventArgs args) { }

// ✅ 正确
private void OnTextChanged(TextChangeEventArgs args) { }

拖动开始事件

⚠️ DragStartEventArgs 存在歧义：如果同时引用了 Syncfusion.Blazor.Popups（或其他公开 DragStartEventArgs 的程序包），就会产生歧义。
请始终使用完整名称 Syncfusion.Blazor.Diagram.DragStartEventArgs：

// ❌ 错误 — CS0104：Diagram 和 Popups 之间存在不明确的引用
private void OnDragStart(DragStartEventArgs args) { }

// ✅ 正确 — 使用完整名称
private void OnDragStart(Syncfusion.Blazor.Diagram.DragStartEventArgs args) { }

⚠️ Syncfusion.Blazor.Diagram 中不存在 DragEnterEventArgs。
SfDiagramComponent 上没有接收 DragEnterEventArgs 的 DragEnter 事件。
SfDiagramComponent 上可用的拖动事件有：DragStart、Dragging、DragLeave、DragDrop——这些事件仅用于 SymbolPalette 拖放。
要跟踪节点正在移动（内部拖动）的情况，请使用 PositionChanged：

// ❌ 错误 — 不存在 DragEnterEventArgs
private void OnDragEnter(DragEnterEventArgs args) { }

// ❌ 错误 — SfDiagramComponent 上不存在 OnPositionChange
<SfDiagramComponent OnPositionChange="OnPositionChange" />

// ✅ 正确 — 使用 PositionChanged
<SfDiagramComponent PositionChanged="OnPositionChanged" />

private void OnPositionChanged(PositionChangedEventArgs args)
{
    if (args.Element is Node n)
        Console.WriteLine($"Node {n.ID} moved to ({n.OffsetX}, {n.OffsetY})");
}

捕捉距离

⚠️ SnapSettings 上不存在 SnapObjectDistance——使用它会导致 InvalidOperationException: does not have a property matching the name 'SnapObjectDistance'。
正确的属性名是 SnapDistance：

@* ❌ 错误 — 不存在 SnapObjectDistance *@
<SnapSettings SnapObjectDistance="5" />

@* ✅ 正确 *@
<SnapSettings Constraints="SnapConstraints.SnapToObject" SnapDistance="5" />

样式设置

⚠️ SfDiagramComponent 上不存在 CssClass——使用它会导致
InvalidOperationException: Object of type 'SfDiagramComponent' does not have a property matching the name 'CssClass'。
请将组件包装在带有作用域类的 <div> 中：

@* ❌ 错误 — SfDiagramComponent 上不存在 CssClass *@
<SfDiagramComponent CssClass="my-diagram" />

@* ✅ 正确 — 使用包装 div *@
<div class="my-diagram">
    <SfDiagramComponent ... />
</div>

阶段偏移属性

⚠️ 不存在 Phase.Offset——使用它会导致编译错误。
请使用 Phase.Width 设置泳道中阶段的大小：

// ❌ 错误 — Phase 上不存在 Offset
new Phase { ID = "ph1", Offset = 220 }

// ✅ 正确 — 使用 Width
new Phase { ID = "ph1", Width = 220 }

泳道约束属性

⚠️ 不存在 Lane.Constraints，也不存在 LaneConstraints 枚举。
无法通过 Constraints 属性为单个泳道设置约束。
要限制泳道级别的交互，请在 Swimlane 对象本身上使用 SwimlaneConstraints：

// ❌ 错误 — 不存在 Lane.Constraints 和 LaneConstraints
lane.Constraints = LaneConstraints.Default & ~LaneConstraints.ResizeEntries;

// ✅ 正确 — 在 Swimlane 对象上设置约束
swimlane.Constraints = SwimlaneConstraints.Default & ~SwimlaneConstraints.Interaction;

FitMode.Page 值

⚠️ 不存在 FitMode.Page——使用它会导致 CS0117。
FitMode 的正确值是 FitMode.Width 和 FitMode.Height：

// ❌ 错误 — 不存在 FitMode.Page
new FitOptions { Mode = FitMode.Page }

// ✅ 正确 — 使用 FitMode.Width 或 FitMode.Height
new FitOptions { Mode = FitMode.Width, Region = DiagramRegion.Content }

LoadDiagram 方法

⚠️ SfDiagramComponent.LoadDiagram() 不存在——使用它会导致编译错误。
请改用异步版本 LoadDiagramAsync()：

// ❌ 错误 — LoadDiagram() 不存在
diagram.LoadDiagram(savedJson);

// ✅ 正确 — 使用 LoadDiagramAsync
await diagram.LoadDiagramAsync(savedJson);

FitToPageAsync 方法

⚠️ SfDiagramComponent.FitToPageAsync() 不存在——使用它会导致编译错误。
请改用非异步重载 FitToPage()：

// ❌ 错误 — FitToPageAsync 不存在
await diagram.FitToPageAsync(new FitOptions { Mode = FitMode.Width });

// ✅ 正确 — 使用 FitToPage（同步）
diagram.FitToPage(new FitOptions { Mode = FitMode.Width, Region = DiagramRegion.Content });

BasicShapes 枚举

⚠️ BasicShapes 不存在——请改用 NodeBasicShapes：

// ❌ 错误
new BasicShape { Shape = BasicShapes.Rectangle }

// ✅ 正确
new BasicShape { Shape = NodeBasicShapes.Rectangle }

DiagramThickness 构造函数

⚠️ DiagramThickness 没有接受 4 个参数的构造函数——使用它会导致 CS1729: does not contain a constructor that takes 4 arguments。
请改用带命名属性的对象初始化器语法：

// ❌ 错误 — CS1729：没有接受 4 个参数的构造函数
new DiagramThickness(20, 50, 20, 20)

// ✅ 正确 — 使用带命名属性的对象初始化器
new DiagramThickness { Left = 20, Top = 50, Right = 20, Bottom = 20 }

// ✅ 正确 — 仅设置所需的边
new DiagramThickness { Top = 50 }

PathAnnotation DragLimit 类型

⚠️ PathAnnotation.DragLimit 的类型是 DiagramThickness，不是 Margin。
使用 new Margin { ... } 会导致类型不匹配编译错误（CS0029）。
DragLimit 始终应使用 new DiagramThickness { ... }：

// ❌ 错误 — CS0029：无法将 Margin 赋给 DiagramThickness
new PathAnnotation
{
    Constraints = AnnotationConstraints.Interaction,
    DragLimit   = new Margin { Left = 40, Right = 40, Top = 20, Bottom = 20 }
}

// ✅ 正确 — 使用带对象初始化器的 DiagramThickness
new PathAnnotation
{
    Constraints = AnnotationConstraints.Interaction,
    DragLimit   = new DiagramThickness { Left = 40, Right = 40, Top = 20, Bottom = 20 }
}

ScrollSettings EnableAutoScroll 属性

⚠️ ScrollSettings 上不存在 CanAutoScroll——使用它会导致 InvalidOperationException: does not have a property matching the name 'CanAutoScroll'。
正确的属性名称是 EnableAutoScroll：

@* ❌ 错误 — CanAutoScroll 不存在 *@
<ScrollSettings CanAutoScroll="true" />

@* ✅ 正确 *@
<ScrollSettings EnableAutoScroll="true" />

Zoom、Undo 和 Redo 方法

⚠️ ZoomAsync()、UndoAsync() 和 RedoAsync() 不存在——使用它们会导致编译错误。
请改用非异步重载 Zoom()、Undo() 和 Redo()：

// ❌ 错误 — ZoomAsync、UndoAsync、RedoAsync 不存在
await _diagram.ZoomAsync(1.2, new DiagramPoint { X = 300, Y = 300 });
await _diagram.UndoAsync();
await _diagram.RedoAsync();

// ✅ 正确 — 使用非异步重载
_diagram.Zoom(1.2, new DiagramPoint { X = 300, Y = 300 });
_diagram.Undo();
_diagram.Redo();

概览组件命名空间

⚠️ SfDiagramOverviewComponent 需要额外添加一个 @using — 它位于 Syncfusion.Blazor.Diagram.Overview 中，而不在 Syncfusion.Blazor.Diagram 中。忘记添加会导致 CS0246：

@* ❌ 错误 — 未添加 Overview 命名空间时找不到 SfDiagramOverviewComponent *@
@using Syncfusion.Blazor.Diagram

@* ✅ 正确 — 需要这两个命名空间 *@
@using Syncfusion.Blazor.Diagram
@using Syncfusion.Blazor.Diagram.Overview

⚠️ SourceID 必须与 SfDiagramComponent 上设置的 ID 完全匹配 — ID 不会自动生成；必须显式设置。两者不匹配（包括大小写）会导致概览为空：

@* ❌ 错误 — 未在图表上设置 ID；SourceID 没有可关联的对象 *@
<SfDiagramComponent Width="100%" Height="500px" Nodes="@_nodes" />
<SfDiagramOverviewComponent SourceID="myDiagram" Height="150px" />

@* ✅ 正确 — 已在图表上设置 ID，且 SourceID 与之完全匹配 *@
<SfDiagramComponent ID="myDiagram" Width="100%" Height="500px" Nodes="@_nodes" />
<SfDiagramOverviewComponent SourceID="myDiagram" Height="150px" />

⚠️ 不要将 SfDiagramOverviewComponent 嵌套在 SfDiagramComponent 中 — 概览是一个同级组件，渲染在图表标记之外。