syncfusion-angular-smith-chart

实现 Syncfusion Angular Smith Chart 组件

何时使用此技能

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

• 可视化传输线 - 在 Smith 图表上绘制阻抗或导纳参数，用于电路分析
• 创建 Smith 图表 - 通过适当的配置和数据绑定来呈现 Smith 图表组件
• 添加多个系列 - 在单个图表上显示多个传输线系列
• 自定义坐标轴 - 配置水平轴和径向轴，并自定义标签、网格线和样式
• 突出显示数据点 - 添加标记和数据标签以强调关键值
• 显示图例 - 实现图例，并支持位置、对齐方式和可见性切换
• 启用交互功能 - 添加工具提示、打印功能和事件处理
• 设置样式和主题 - 应用 Syncfusion 主题、自定义颜色和响应式尺寸
• 确保无障碍访问 - 支持 WCAG 合规性、键盘导航和 RTL 布局

组件概览

Syncfusion Angular Smith Chart 是一个专为高频电路应用设计的数据可视化组件。它使用两组同心圆（恒定电阻和电抗）来绘制传输线参数，用于阻抗和导纳分析。

主要特性：

• 双轴系统 - 水平轴（表示电阻的直线）和径向轴（表示电抗的圆弧）
• 渲染类型 - 支持 Impedance（默认）和 Admittance 参数
• 多系列支持 - 同时显示多个传输线系列，并使用不同的颜色和样式
• 数据绑定 - 两种方法：points 数组，或使用 resistance/reactance 属性映射的 dataSource
• 交互元素 - 标记、数据标签、工具提示、可切换可见性的图例以及导出功能
• 可自定义样式 - 坐标轴标签、主/次网格线、颜色、主题（Material、Bootstrap、Tailwind）和响应式尺寸
• 无障碍功能 - WCAG 合规性、键盘导航、RTL（从右向左）支持以及屏幕阅读器兼容性
• 事件驱动 - 加载事件、系列渲染、图例交互和工具提示自定义
• 导出功能 - PNG、JPEG、SVG 格式，用于报告和文档

文档和导航指南

本技能将指导你实现 Smith 图表。以下是主要主题：

入门

📄 阅读： references/getting-started.md

• Angular 19+ 的安装和程序包设置
• Smith 图表组件的基本实现
• 模块注入要求
• 使用电阻值和矩形值进行数据绑定
• CSS 导入和主题设置
• 何时阅读：实现第一个 Smith 图表之前

系列和数据管理

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

• 了解系列概念和数据结构
• 用于数据输入的 points 与 dataSource
• 阻抗和导纳渲染类型
• 系列自定义（填充、透明度、宽度、可见性）
• 多系列示例和模式
• 智能标签和防止重叠
• 何时阅读：绑定数据并配置多个系列时

坐标轴自定义

📄 阅读： references/axis-customization.md

• 水平轴和径向轴配置
• 坐标轴标签（定位、交叉处理、样式）
• 主网格线和次网格线（可见性、宽度、虚线模式、透明度）
• 坐标轴线自定义
• 标签和值格式
• 何时阅读：自定义坐标轴外观和行为时

标记和数据标签

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

• 标记配置和可见性
• 数据标签的显示和格式设置
• 定位标记和标签以避免重叠
• 自定义标签内容（电阻值、电抗值）
• 数值格式设置
• 何时阅读：突出显示特定数据点或显示详细值时

图例与交互

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

• 图例的可见性和位置（顶部、底部、左侧、右侧、自定义）
• 图例对齐方式和布局
• 自定义图例形状（圆形、矩形、三角形）
• 图例尺寸和响应式行为
• 点击图例切换系列的可见性
• 阅读时机：添加和配置图例，以便识别系列

高级功能

📄 阅读： references/advanced-features.md

• 提示框配置和格式设置
• 打印和导出功能
• RTL（从右向左）支持
• 主题和 CSS 自定义
• 容器尺寸和响应式行为
• WCAG 无障碍合规性
• 键盘导航
• 事件处理（点击、悬停、图例切换）
• 阅读时机：实现提示框、导出、事件或无障碍等复杂功能

故障排除

📄 阅读： references/troubleshooting.md

• 常见实现问题及解决方案
• 数据格式验证和错误
• 模块导入故障排除
• 性能优化技巧
• 图表渲染和显示问题
• 阅读时机：排查问题或优化图表性能

快速入门示例

以下是一个用于渲染基本史密斯圆图的简例：

import { SmithchartModule } from '@syncfusion/ej2-angular-charts'
import { Component } from '@angular/core';

@Component({
  imports: [SmithchartModule],
  standalone: true,
  selector: 'app-container',
  template: `<ejs-smithchart 
    id='smithchart-container'
    [series]="series">
  </ejs-smithchart>`
})
export class AppComponent {
  series = [{
    points: [
      { resistance: 10, reactance: 10 },
      { resistance: 20, reactance: 15 },
      { resistance: 30, reactance: 5 },
      { resistance: 40, reactance: -5 },
      { resistance: 50, reactance: -15 }
    ]
  }]
}

**输出：**一个基本的史密斯圆图，其中包含一个用于显示传输线阻抗值的系列。

常见模式

模式 1：多系列传输线比较

显示多个不同颜色的传输线系列，以比较阻抗：

series = [
  {
    name: 'Transmission Line A',
    points: [
      { resistance: 0.2, reactance: 0.1 },
      { resistance: 0.5, reactance: 0.3 },
      { resistance: 1.0, reactance: 0.5 }
    ],
    fill: '#0066CC',
    marker: { visible: true },
    tooltip: { visible: true }
  },
  {
    name: 'Transmission Line B',
    points: [
      { resistance: 0.3, reactance: 0.15 },
      { resistance: 0.6, reactance: 0.4 },
      { resistance: 1.2, reactance: 0.6 }
    ],
    fill: '#FF6633',
    marker: { visible: true },
    tooltip: { visible: true }
  }
]

模式 2：交互式提示框、图例和标记

启用图例以识别系列，启用提示框以查看详细值，并使用标记突出显示数据点：

@Component({
  template: `
    <ejs-smithchart [series]="series" [legendSettings]="legendSettings">
    </ejs-smithchart>
  `
})
export class AppComponent {
  series = [
    {
      name: 'Device A',
      marker: { 
        visible: true, 
        shape: 'Circle', 
        width: 8,
        height: 8,
        dataLabel: { visible: true }  // ✓ dataLabel INSIDE marker
      },
      tooltip: { visible: true, template: 'R:${resistance}+jX:${reactance}' },
      points: [...]
    }
  ];

  legendSettings = { 
    visible: true, 
    position: 'Bottom',
    alignment: 'Center' 
  };
}

模式 3：导纳渲染类型与轴自定义

切换为导纳渲染，并使用网格线自定义坐标轴：

@Component({
  template: `
    <ejs-smithchart
      renderType: 'Admittance'
      [series]="series"
      [horizontalAxis]="hAxis"
      [radialAxis]="rAxis">
    </ejs-smithchart>
  `
})
export class AppComponent {
  series = [
    {
      points: [...],
    }
  ];

  hAxis = {
    labelPosition: 'Outside',
    majorGridLines: { visible: true, width: 1, opacity: 0.8 },
    minorGridLines: { visible: true, count: 4, opacity: 0.4 }
  };

  rAxis = {
    majorGridLines: { visible: true, width: 1, opacity: 0.8 },
    minorGridLines: { visible: true, count: 4, opacity: 0.4 }
  };
}

模式 4：从外部数据源驱动系列

使用 dataSource 属性从数组绑定系列数据：

series = [
  {
    name: 'Test Results',
    dataSource: [
      { impedance: 50, phase: 0 },     // Will be mapped to resistance/reactance
      { impedance: 75, phase: 15 },
      { impedance: 100, phase: 30 }
    ],
    resistance: 'impedance',
    reactance: 'phase'
  }
];

模式 5：集成导出和打印

启用导出和打印功能，以便用于文档：

@Component({
  template: `
    <div>
      <button (click)="exportChart('PNG')">Export PNG</button>
      <button (click)="exportChart('SVG')">Export SVG</button>
      <button (click)="printChart()">Print</button>
    </div>
    <ejs-smithchart #smithchart [series]="series"></ejs-smithchart>
  `
})
export class AppComponent {
  @ViewChild('smithchart') smithchart!: any;

  exportChart(format: string) {
    this.smithchart.export(format, 'smith-chart-export');
  }

  printChart() {
    this.smithchart.print();
  }
}

## Import Best Practices

### ✅ Minimal Imports (Most Cases)

For basic smith charts without advanced features, import only what you need:

```typescript
import { SmithchartModule } from '@syncfusion/ej2-angular-charts'
import { Component, ViewEncapsulation } from '@angular/core'

@Component({
  imports: [SmithchartModule],  // ✓ Only SmithchartModule needed
  standalone: true,
  encapsulation: ViewEncapsulation.None,
  template: `<ejs-smithchart [series]="series"></ejs-smithchart>`
})
export class AppComponent {
  series = [{ points: [...] }]
}

❌ 不要导入不必要的模块

避免导入未使用的模块或服务：

// ✗ WRONG - CommonModule not needed in standalone component
import { CommonModule } from '@angular/common'
@Component({
  imports: [SmithchartModule, CommonModule],  // CommonModule is unnecessary
  standalone: true
})

// ✗ WRONG - SmithchartLegendService not needed without custom legend events
import { SmithchartLegendService } from '@syncfusion/ej2-angular-charts'
@Component({
  providers: [SmithchartLegendService],  // Only for custom legend click handling
  standalone: true
})
export class AppComponent {
  legendSettings = { visible: true }  // Basic legend doesn't need the service
}

// ✗ WRONG - TooltipRenderService not needed without tooltips
import { TooltipRenderService } from '@syncfusion/ej2-angular-charts'
@Component({
  providers: [TooltipRenderService],  // Only needed if tooltip: { visible: true }
  standalone: true
})
export class AppComponent {
  series = [{ points: [...] }]  // No tooltip configuration
}

✅ 仅在需要时添加服务

用例	服务	导入
基本图表	无	仅 SmithchartModule
带提示框	TooltipRenderService	使用 tooltip: { visible: true } 时添加
高级图例点击	SmithchartLegendService	处理图例交互事件时添加

示例：仅在使用时启用提示框

import { SmithchartModule, TooltipRenderService } from '@syncfusion/ej2-angular-charts'

@Component({
  imports: [SmithchartModule],
  providers: [TooltipRenderService],  // ✓ Add only if using tooltips
  standalone: true
})
export class AppComponent {
  series = [{
    points: [
      { resistance: 0.2, reactance: 0.1 },
      { resistance: 0.4, reactance: 0.3 }
    ],
    tooltip: { visible: true }  // ✓ Tooltips are configured
  }]
}

关键配置属性

属性	类型	默认值	用途
series	数组	[]	包含用于可视化的点数据的系列数组
points	数组	-	系列的数据数组（电阻、电抗对）
dataSource	数组	-	绑定外部来源或数据数组中的数据
resistance	字符串	-	dataSource 中 X 轴值（电阻）的属性名称
reactance	字符串	-	dataSource 中 Y 轴值（电抗）的属性名称
name	字符串	-	用于图例显示的系列名称
renderType	字符串	'Impedance'	渲染类型：'Impedance' 或 'Admittance'
fill	字符串	-	系列线条颜色（十六进制或命名颜色）
width	数字	2	系列线条宽度（像素）
opacity	数字	1	系列线条不透明度（0-1）
marker	对象	-	标记配置（可见性、形状、大小）
dataLabel	对象	-	数据标签配置（可见性、格式）
tooltip	对象	-	工具提示配置（可见性、格式、模板）
title	对象	-	标题配置（文本、可见性、样式）
height	字符串/数字	'400px'	图表高度（像素或百分比）
width	字符串/数字	'100%'	图表宽度（像素或百分比）
theme	字符串	'Material'	内置主题（Material、Bootstrap、Tailwind 等）
legendSettings	对象	-	图例配置（可见性、位置、对齐方式）
horizontalAxis	对象	-	水平轴自定义设置和标签
radialAxis	对象	-	径向轴自定义设置和网格线
enableRtl	布尔值	false	启用从右到左文本方向支持
ariaLabel	字符串	-	供屏幕阅读器使用的无障碍标签

常见用例

1. 电路分析与阻抗匹配 - 可视化高频电路的阻抗匹配和传输线特性
2. 网络与滤波器调试 - 显示多个滤波器响应和网络参数，以便比较和优化
3. 天线设计与优化 - 绘制阻抗曲线，用于天线调谐、SWR 分析和频率响应可视化
4. 射频工程 - 分析反射系数、驻波模式和传输线属性
5. 微波工程 - 设计和分析传输线、波导及微波组件
6. 教育内容 - 通过交互式图表和实时参数可视化讲解高频电路概念
7. 性能仪表板 - 实时监控多个传输线指标和网络参数
8. 设备测试与验证 - 比较测量和模拟的阻抗数据，以表征设备
9. 质量控制 - 在史密斯圆图上可视化电子组件的生产测试结果
10. 信号完整性分析 - 分析终端阻抗和信号反射，以验证 PCB 设计

---

API 参考

Syncfusion Angular Smithchart 的完整 API 参考位于 references 文件夹中。它包含属性锚点、方法链接和事件参数类型，并与官方文档相对应。

阅读 API 参考：references/api-reference.md

后续步骤： 从 getting-started.md 开始，安装并渲染第一个史密斯圆图，然后根据需要探索其他参考指南。