syncfusion-blazor-smith-charts

实现史密斯圆图

NuGet： Syncfusion.Blazor.Charts + Syncfusion.Blazor.Themes（或使用单独的程序包 Syncfusion.Blazor.SmithChart） 命名空间： Syncfusion.Blazor.Charts

Syncfusion Blazor 史密斯圆图（SfSmithChart）是一种专用图表组件，用于可视化传输线阻抗、射频电路参数和天线调谐数据。它在圆形网格上显示复阻抗或导纳，是射频／微波工程应用中的重要工具。该组件位于 Syncfusion.Blazor.Charts 命名空间中，提供史密斯圆图 API，涵盖系列、坐标轴、图例、标题、副标题、工具提示、导出／打印和渲染事件。

何时使用此技能

用户有以下需求时，请使用此技能：

• 可视化阻抗匹配，适用于传输线和射频电路
• 在史密斯圆图上绘制反射系数（S 参数）
• 分析天线调谐和谐振特性
• 显示多条传输线或多种电路配置
• 自定义圆形和径向坐标轴，用于阻抗／导纳可视化
• 添加标记和数据标签，突出显示关键阻抗点
• 启用图例，以区分多个系列
• 显示工具提示，呈现电阻和电抗值
• 将史密斯圆图导出为图像格式，或打印以供存档
• 处理射频工程数据，使用电阻和电抗坐标

组件概览

史密斯圆图组件会在圆形坐标系中将数据点渲染为由线连接的系列。主要功能包括：

• 双坐标轴系统： 水平坐标轴（直线）和径向坐标轴（圆形路径）
• 系列可视化： 绘制多条传输线或多种电路配置
• 标记和数据标签： 使用可自定义的形状和标签突出显示特定阻抗点
• 智能标签： 自动调整标签位置，避免与连接线重叠
• 图例支持： 显示系列名称，并可切换其可见性
• 交互式工具提示： 悬停时显示电阻／电抗值
• 导出和打印： 将图表保存为 PNG、JPEG、SVG 或 PDF
• 自定义： 完全控制颜色、字体、边框和样式
• 响应式设计： 根据容器尺寸自适应

组件： SfSmithChart（Syncfusion.Blazor.Charts 命名空间）

核心 API：

• SfSmithChart，用于主图表
• RenderType，用于选择阻抗或导纳渲染模式
• SmithChartEvents，用于绑定事件
• SmithChartSeriesCollection 和 SmithChartSeries，用于数据绑定
• SmithChartHorizontalAxis 和 SmithChartRadialAxis，用于配置坐标轴
• SmithChartLegendSettings，用于设置图例位置和格式
• SmithChartTitle 和 SmithChartSubtitle，用于设置图表标题
• SmithChartSeriesMarker、SmithChartSeriesDatalabel、SmithChartSeriesDataLabelBorder 和 SmithChartSeriesTooltip，用于标注数据点
• SmithChartBorder 和 SmithChartMargin，用于布局和容器样式设置

常见枚举类型：

• RenderType
• SmithChartAlignment
• SmithChartLabelIntersectAction
• AxisLabelPosition
• LegendPosition
• Shape
• ExportType

文档与导航指南

API 参考

📄 阅读： references/api-reference.md

此文档是权威的史密斯圆图 API 摘要，涵盖：

• SfSmithChart 属性和方法
• 史密斯圆图事件及事件参数
• 嵌套组件、类和枚举

入门指南

📄 阅读： references/getting-started.md

从这里开始了解安装和初始设置：

• 安装 Syncfusion.Blazor.SmithChart NuGet 程序包
• 设置 Blazor Server、WebAssembly 或 Web App 项目
• 注册服务和主题引用
• 使用基本数据绑定创建第一个史密斯圆图
• 排查常见设置问题

系列与数据绑定

📄 阅读： references/series-and-data-binding.md

了解如何绑定数据和配置系列：

• 使用 Resistance 和 Reactance 属性组织数据
• 配置 SmithChartSeries 的 Fill、Opacity、Width、Visible
• 添加多个系列进行比较
• 自定义各个系列的外观
• 处理复杂的传输线数据

坐标轴配置

📄 阅读： references/axes-configuration.md

配置水平轴和径向轴：

• 了解水平轴（直线）与径向轴（圆形）的区别
• 自定义轴标签（位置、字体、交点处理）
• 设置轴线和网格的样式
• 控制标签的可见性和位置（Inside/Outside）
• 自定义字体（FontFamily、FontWeight、FontStyle、Size、Color）

标记和数据标签

📄 阅读： references/markers-and-data-labels.md

为系列中的数据点添加可视标记和数据标签：

• 启用并自定义标记形状（Circle、Rectangle、Triangle）
• 配置标记大小、颜色、不透明度和边框
• 显示电阻值/电抗值数据标签
• 使用带连接线的智能标签避免重叠
• 创建自定义数据标签模板

图例配置

📄 阅读： references/legend-configuration.md

显示并自定义用于识别系列的图例：

• 设置图例位置（Top、Bottom、Left、Right、Custom）
• 自定义图例形状、颜色和边框
• 配置图例对齐方式和尺寸
• 使用自定义样式添加图例标题
• 启用切换可见性以显示/隐藏系列
• 按行和列排列图例

工具提示

📄 阅读： references/tooltips.md

启用交互式工具提示以探索数据：

• 悬停时显示电阻值和电抗值
• 自定义工具提示外观（填充颜色、不透明度、边框）
• 创建自定义工具提示模板
• 在模板中访问 SmithChartPoint 数据

图表尺寸和标题

📄 阅读： references/chart-dimensions-and-titles.md

配置图表尺寸、标题和布局：

• 设置图表宽度和高度（固定或自适应）
• 添加图表标题和副标题并设置样式
• 配置边距和内边距
• 自定义背景颜色
• 创建自适应 Smith 图表

导出、打印、事件和无障碍访问

📄 阅读： references/export-print-events-accessibility.md

导出图表、处理事件并确保无障碍访问：

• 导出为 PNG、JPEG、SVG 和 PDF 格式
• 打印 Smith 图表以用于文档
• 处理组件事件（Loaded、SeriesRender、AxisLabelRendering、LegendRendering、TitleRendering、SubtitleRendering、TextRendering、TooltipRender、OnPrintComplete、OnExportComplete、SizeChanged）
• 实现符合 WCAG 标准的无障碍图表
• 支持键盘导航和屏幕阅读器
• 测试无障碍合规性

快速入门示例

下面是一个显示传输线的基本 Smith 图表：

@page "/smith-chart-basic"
@using Syncfusion.Blazor.Charts

<h3>Transmission Line Impedance</h3>

<SfSmithChart>
    <SmithChartSeriesCollection>
        <SmithChartSeries Name="Transmission Line 1" 
                          DataSource="@TransmissionData" 
                          Reactance="Reactance" 
                          Resistance="Resistance">
            <SmithChartSeriesMarker Visible="true"></SmithChartSeriesMarker>
        </SmithChartSeries>
    </SmithChartSeriesCollection>
</SfSmithChart>

@code {
    public class SmithChartData
    {
        public double? Resistance { get; set; }
        public double? Reactance { get; set; }
    }
    
    public List<SmithChartData> TransmissionData = new List<SmithChartData>
    {
        new SmithChartData { Resistance = 10, Reactance = 25 },
        new SmithChartData { Resistance = 6, Reactance = 4.5 },
        new SmithChartData { Resistance = 3.5, Reactance = 1.6 },
        new SmithChartData { Resistance = 2, Reactance = 1.2 },
        new SmithChartData { Resistance = 1, Reactance = 0.8 },
        new SmithChartData { Resistance = 0, Reactance = 0.2 }
    };
}

常见用例

RF 阻抗匹配分析

@using Syncfusion.Blazor.Charts

<SfSmithChart Height="600px" Width="100%">
    <SmithChartTitle Text="Antenna Impedance Matching"></SmithChartTitle>
    <SmithChartLegendSettings Visible="true" Position="@Syncfusion.Blazor.Charts.LegendPosition.Bottom">
    </SmithChartLegendSettings>
    <SmithChartSeriesCollection>
        <SmithChartSeries Name="Before Matching" 
                          DataSource="@BeforeData" 
                          Reactance="Reactance" 
                          Resistance="Resistance"
                          Fill="#FF6B6B">
            <SmithChartSeriesMarker Visible="true" Shape="@Syncfusion.Blazor.Charts.Shape.Circle"></SmithChartSeriesMarker>
            <SmithChartSeriesTooltip Visible="true"></SmithChartSeriesTooltip>
        </SmithChartSeries>
        <SmithChartSeries Name="After Matching" 
                          DataSource="@AfterData" 
                          Reactance="Reactance" 
                          Resistance="Resistance"
                          Fill="#4ECDC4">
            <SmithChartSeriesMarker Visible="true" Shape="@Syncfusion.Blazor.Charts.Shape.Diamond"></SmithChartSeriesMarker>
            <SmithChartSeriesTooltip Visible="true"></SmithChartSeriesTooltip>
        </SmithChartSeries>
    </SmithChartSeriesCollection>
</SfSmithChart>

@code {
    public class SmithChartData
    {
        public double? Resistance { get; set; }
        public double? Reactance { get; set; }
    }

    public List<SmithChartData> BeforeData = new List<SmithChartData>
    {
        new SmithChartData { Resistance = 10,  Reactance = 25 },
        new SmithChartData { Resistance = 6,   Reactance = 4.5 },
        new SmithChartData { Resistance = 3.5, Reactance = 1.6 },
        new SmithChartData { Resistance = 2,   Reactance = 1.2 },
        new SmithChartData { Resistance = 1,   Reactance = 0.8 },
        new SmithChartData { Resistance = 0,   Reactance = 0.2 }
    };

    public List<SmithChartData> AfterData = new List<SmithChartData>
    {
        new SmithChartData { Resistance = 2.5, Reactance = 1.2 },
        new SmithChartData { Resistance = 2, Reactance = 0.8 },
        new SmithChartData { Resistance = 1.6, Reactance = 0.5 },
        new SmithChartData { Resistance = 1.3, Reactance = 0.3 },
        new SmithChartData { Resistance = 1.1, Reactance = 0.1 },
        new SmithChartData { Resistance = 1, Reactance = 0 }
    };
}

多频率响应分析

@using Syncfusion.Blazor.Charts

<SfSmithChart>
    <SmithChartTitle Text="Frequency Sweep: 100MHz - 1GHz"></SmithChartTitle>
    <SmithChartLegendSettings Visible="true" Position="@Syncfusion.Blazor.Charts.LegendPosition.Right">
    </SmithChartLegendSettings>
    <SmithChartSeriesCollection>
        <SmithChartSeries Name="100MHz" DataSource="@Freq100Data" 
                          Reactance="Reactance" Resistance="Resistance" Width="2">
        </SmithChartSeries>
        <SmithChartSeries Name="500MHz" DataSource="@Freq500Data" 
                          Reactance="Reactance" Resistance="Resistance" Width="2">
        </SmithChartSeries>
        <SmithChartSeries Name="1GHz" DataSource="@Freq1000Data" 
                          Reactance="Reactance" Resistance="Resistance" Width="2">
        </SmithChartSeries>
    </SmithChartSeriesCollection>
</SfSmithChart>

@code {
    public class SmithChartData
    {
        public double? Resistance { get; set; }
        public double? Reactance { get; set; }
    }

    public List<SmithChartData> Freq100Data = new List<SmithChartData>
    {
        new SmithChartData { Resistance = 10,  Reactance = 20 },
        new SmithChartData { Resistance = 8,   Reactance = 12 },
        new SmithChartData { Resistance = 6,   Reactance = 6 },
        new SmithChartData { Resistance = 4,   Reactance = 3 },
        new SmithChartData { Resistance = 2,   Reactance = 1.5 },
        new SmithChartData { Resistance = 1,   Reactance = 0.8 }
    };

    public List<SmithChartData> Freq500Data = new List<SmithChartData>
    {
        new SmithChartData { Resistance = 8,   Reactance = 15 },
        new SmithChartData { Resistance = 6,   Reactance = 8 },
        new SmithChartData { Resistance = 4.5, Reactance = 4 },
        new SmithChartData { Resistance = 3,   Reactance = 2 },
        new SmithChartData { Resistance = 1.8, Reactance = 1 },
        new SmithChartData { Resistance = 1.2, Reactance = 0.4 }
    };

    public List<SmithChartData> Freq1000Data = new List<SmithChartData>
    {
        new SmithChartData { Resistance = 6,   Reactance = 10 },
        new SmithChartData { Resistance = 4.5, Reactance = 5 },
        new SmithChartData { Resistance = 3,   Reactance = 2.5 },
        new SmithChartData { Resistance = 2,   Reactance = 1.2 },
        new SmithChartData { Resistance = 1.2, Reactance = 0.5 },
        new SmithChartData { Resistance = 1, Reactance = 0 }
    };
}

主要属性

属性	类型	说明	适用场景
SmithChartSeriesCollection	集合	包含所有系列的容器	始终需要，用于显示数据
DataSource	IEnumerable	阻抗数据点列表	绑定电阻和电抗数据
Resistance	string	电阻值的属性名称	映射到数据模型属性
Reactance	string	电抗值的属性名称	映射到数据模型属性
RenderType	Enum	选择阻抗或导纳渲染方式	切换史密斯圆图的坐标解释方式
Radius	string	史密斯圆图绘图区的半径	控制圆形绘图区的大小
ElementSpacing	string	图表元素之间的间距	调整紧凑或宽松的布局
Background	string	图表背景颜色	与宿主 UI 主题保持一致
Theme	string	内置史密斯圆图主题	保持视觉样式一致
ID	string	图表元素标识符	适用于测试或脚本编写
SmithChartSeriesMarker	Component	标记配置	以可视方式突出显示数据点
SmithChartSeriesTooltip	Component	工具提示配置	悬停时显示数值
SmithChartLegendSettings	Component	图例配置	区分多个系列
SmithChartHorizontalAxis	Component	水平轴设置	自定义直线轴
SmithChartRadialAxis	Component	径向轴设置	自定义圆形轴
Width	string	图表宽度（px 或 %）	控制图表尺寸
Height	string	图表高度（px 或 %）	控制图表尺寸

实现工作流

1. 安装软件包 → 添加 Syncfusion.Blazor.SmithChart NuGet 软件包
2. 注册服务 → 在 Program.cs/Startup.cs 中添加服务
3. 添加主题 → 引用 Syncfusion 主题 CSS
4. 准备数据 → 使用 Resistance 和 Reactance 属性构建数据
5. 添加组件 → 在 Razor 页面中放置 <SfSmithChart>
6. 绑定系列 → 使用 DataSource 配置 SmithChartSeries
7. 自定义 → 添加标记、工具提示、图例和样式
8. 测试 → 验证数据可视化和交互功能

边界情况和注意事项

• 数据范围： 史密斯圆图表示归一化阻抗（通常为 0-∞）。请确保数据已适当归一化。
• 系列可见性： 如果多个系列大量重叠，请使用不同的颜色，并通过图例切换可见性。
• 空值： 对 Resistance 和 Reactance 使用可空 double（double?），以妥善处理缺失数据。
• 性能： 大型数据集（每个系列超过 1000 个点）可能会影响渲染。请考虑对数据进行采样。
• 响应式设计： 使用百分比宽度/高度或容器查询实现响应式布局。
• 无障碍性： 在射频工程应用中，请始终启用工具提示和 ARIA 标签，以支持屏幕阅读器。

不适合使用此组件的场景

• 通用 XY 绘图： 标准笛卡尔坐标图请使用常规 Chart 组件
• 金融数据： 时序金融数据请使用 Stock Chart
• 非射频数据： 史密斯圆图专用于阻抗/导纳；其他领域请使用合适的图表类型
• 三维阻抗： 史密斯圆图是二维的；复杂的三维射频可视化需要采用其他方案