syncfusion-angular-chart

实现 Syncfusion Angular 图表组件

本指南全面介绍如何实现 Syncfusion Angular 图表组件。这是一款高性能、交互式数据可视化库，支持 25 种以上的图表类型，包括折线图、条形图、面积图、柱状图、饼图、金融图表和专用序列。该组件针对响应式渲染、流畅交互和大型数据集进行了优化。

何时使用此技能

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

• 可视化数据： 在 Angular 应用中将数值数据显示为图表、图形或绘图
• 趋势分析： 使用折线图、样条图或面积图展示数据随时间变化的趋势
• 比较数据： 使用柱状图、条形图或分组图表比较分类数据
• 金融数据： 使用蜡烛图、OHLC 或技术指标实现股票图表
• 统计分析： 使用箱线图、直方图或帕累托图展示分布
• 多维数据： 使用散点图或气泡图进行相关性分析
• 实时监控： 为仪表板或监控系统创建实时更新的图表
• 交互式探索： 添加缩放、平移、十字线、工具提示或选择功能
• AI Agent 集成： 启用 WebMCP，让浏览器模型上下文和 AI Agent 通过已注册的工具检查和操作图表
• 自定义可视化： 组合多种序列类型和坐标轴，或创建复杂布局
• 无障碍图表： 实现符合 WCAG 标准的图表，并支持键盘导航和屏幕阅读器

组件概述

Syncfusion Angular 图表是一款功能丰富的数据可视化组件，具有以下特性：

• 25 种以上的序列类型： 折线图、样条图、阶梯折线图、面积图、柱状图、条形图、散点图、气泡图、饼图、金融图表（蜡烛图、OHLC）、统计图表（箱线图、直方图、帕累托图）、极坐标图、雷达图、瀑布图等
• 交互功能： 缩放（选区、鼠标滚轮、双指捏合）、平移、工具提示、十字线、跟踪球、选择、数据编辑
• WebMCP 集成： 通过 enableWebMcp 和 webMcpSettings 自动注册内置图表检查和修改工具
• 多个坐标轴： 支持主坐标轴、次坐标轴和多个坐标轴，并支持不同的数据类型（数值、日期时间、对数、类别）
• 图表元素： 图例、数据标记、数据标签、注释、趋势线、技术指标、条纹线
• 数据绑定： 本地数组、远程数据（OData、DataManager）、JSON 源、动态更新
• 自定义： 主题、CSS 样式、调色板、响应式设计、动画
• 导出和打印： 导出为 PDF、SVG、PNG、JPEG、CSV、XLSX 格式
• 无障碍支持： 符合 WCAG 标准、键盘导航、ARIA 属性、国际化、RTL 支持

此技能的质量标准

本文档遵循严格的质量标准，以确保内容准确并达到可用于生产环境的要求：

✅ API 准确性标准

• 属性名称： 使用准确的 Syncfusion v33+ API 属性名称（例如，使用 legendSettings 而非 legend）
• 类型安全： 所有代码示例均使用来自 @syncfusion/ej2-angular-charts 的显式 TypeScript 类型
• 验证： 已根据官方 Syncfusion API 文档 验证所有属性
• 不作假设： 切勿猜测属性名称；务必先查阅官方文档

✅ 代码质量标准

• TypeScript 严格模式： 所有示例均可通过 "strict": true 编译
• 不使用 any 类型： 100% 类型覆盖，不使用宽松类型
• 已测试的示例： 已在真实 Angular 项目中测试代码示例
• 导入语句： 显式导入所有必需的类型

✅ 文档标准

• 清晰的属性名称： 明确区分模板属性名称和 TypeScript 名称
• 类型声明： 记录每个属性对应的 TypeScript 类型模型
• 常见错误章节： 每项功能均包含“❌ 不要这样做”示例
• 相关属性： 提供相关设置的链接和交叉引用

🔍 常见陷阱（从错误中学习）

❌ 错误	✅ 正确	原因
[legend]	[legendSettings]	配置对象必须使用 Settings 后缀
未声明类型	public legendSettings: LegendSettingsModel = {...}	类型安全可启用 IDE 智能提示
[tooltips]	[tooltip]	使用单数形式，而非复数
全局标记配置	按系列配置标记	标记针对特定系列

参见： 属性映射指南，查看完整参考
面向开发者： 技能开发指南 说明了如何维护本文档

文档与导航指南

入门

📄 阅读： references/getting-started.md

适用于以下场景：

• 在 Angular 项目中安装并设置 Chart 组件
• 了解先决条件和系统要求
• 添加 @syncfusion/ej2-angular-charts 包
• 配置 CSS 主题和导入项
• 创建第一个基础图表
• 了解图表模块结构

系列类型

📄 阅读： references/series-types.md

适用于以下场景：

• 为数据选择合适的图表类型
• 实现折线系列（折线、阶梯折线、样条线、堆积、多色）
• 创建面积图（面积、堆积、百分比堆积、范围、样条范围）
• 构建柱形图和条形图（柱形、条形、堆积、范围）
• 可视化金融数据（蜡烛图、Hilo、Hilo 开盘收盘图）
• 使用统计图表（箱线图、直方图、帕累托图、误差线）
• 创建专用图表（散点图、气泡图、极坐标图、雷达图、瀑布图、垂直图）
• 在一个图表中组合多种系列类型

图表元素

📄 阅读： references/chart-elements.md

适用于以下场景：

• 配置和自定义图例（位置、模板、样式）
• 添加数据标记以突出显示数据点（形状、大小、可见性）
• 在图表元素上显示数据标签（位置、模板、格式）
• 添加自定义注释（在特定坐标处添加文本、形状、图像）
• 添加趋势线（线性、指数、多项式、移动平均）
• 添加技术指标（RSI、MACD、布林带、EMA、SMA）
• 使用条带线突出显示特定范围
• 为系列应用渐变填充

坐标轴与布局

📄 阅读： references/axes-and-layout.md

适用于以下场景：

• 配置坐标轴类型（数值、日期时间、对数、类别）
• 设置主坐标轴和次坐标轴
• 为不同的数据范围添加多个坐标轴
• 设置坐标轴标签格式（旋转、对齐、多级标签）
• 自定义网格线和刻度线
• 实现坐标轴交叉和反向坐标轴
• 创建具有多个面板的图表
• 配置图表标题、副标题和尺寸
• 设置图表边距和内边距

交互功能

📄 阅读： references/interactive-features.md

适用于以下场景：

• 启用缩放（选择缩放、鼠标滚轮缩放、捏合缩放、缩放工具栏）
• 实现平移，以浏览缩放后的图表
• 添加工具提示（默认、自定义模板、共享工具提示）
• 启用十字线，以精确读取数值
• 使用跟踪球追踪多个系列的数据点
• 实现选择（数据点、系列、簇、拖动选择）
• 通过拖动数据点启用数据编辑
• 同步多个图表，以协调交互

WebMCP 与 AI Agent 集成

📄 阅读： references/webmcp-feature-spec.md

在以下情况下使用此参考文档：

• 使用 enableWebMcp 启用 Chart WebMCP 集成。
• 通过 webMcpSettings 配置自动注册。
• 注册所有内置工具，或选择特定工具。
• 生成精简示例，其中仅包含渲染的 Chart、所选工具和允许的修改所需的导入项和提供者。
• 生成不受限制的功能导览示例，其中包含完整的必需 Chart 功能集。
• 导入 ChartModule 并提供 WebMcpChartService。
• 确定 37 个内置 WebMCP 工具各自所需的 Angular 服务。
• 配置 beforeWebMcpToolExecute，以实现验证、确认、取消和自定义取消响应。
• 通过 getWebMcpTools() 获取可执行工具，用于诊断、测试或直接执行。
• 创建具有有效输入架构和 JSON 安全执行响应的自定义 WebMCP 工具。
• 避免不受支持的模式，例如手动注册按钮、调用 registerWebMcpTools()、伪造的模型上下文 UI 和编造的工具响应。

数据绑定

📄 阅读： references/data-binding.md

在以下情况下使用：

• 绑定本地数据（对象数组、JSON）
• 连接远程数据源（OData、RESTful API）
• 使用 DataManager 执行高级数据操作
• 处理动态数据更新和实时数据
• 管理空数据点和 null 值
• 将数据字段映射到图表属性
• 优化大型数据集的性能
• 处理异步数据加载

自定义

📄 阅读： references/customization.md

在以下情况下使用：

• 应用内置主题（Material、Bootstrap、Fabric、Tailwind 等）
• 使用 CSS 自定义图表外观
• 使用 Theme Studio 生成自定义主题
• 配置系列的调色板
• 使用自定义颜色和图案设置单个系列的样式
• 针对不同屏幕尺寸实现响应式设计
• 配置图表背景、边框和区域
• 自定义动画效果

无障碍访问

📄 阅读： references/accessibility.md

在以下情况下使用：

• 实现符合 WCAG 2.0/2.1 标准的图表
• 启用键盘导航（方向键、Tab、Enter）
• 为屏幕阅读器配置 ARIA 属性
• 确保适当的颜色对比度和焦点指示器
• 支持高对比度主题

属性映射指南

📄 阅读： references/property-mapping-guide.md

⚠️ 从这里开始，如果你：

• 不确定该使用哪些属性
• 想了解 Settings 后缀约定
• 需要知道哪些属性适用于图表级别，哪些适用于系列级别
• 想避免常见的 API 命名错误
• 需要所有属性的 TypeScript 类型信息

关键资源：

• 完整的属性映射表，包含 ✅/❌ 对比
• 常见命名陷阱（legend 与 legendSettings）
• 类型安全的实现模式
• 新属性的 QA 验证清单

技能开发指南

📄 阅读： references/skill-development-guide.md

面向技能开发者和贡献者：

• 改进技能文档的 4 个关键领域
• legendSettings 案例研究（问题所在及修复方法）
• API 准确性验证流程
• 发布前文档 QA 清单
• 需要避免的常见陷阱
• 为多种语言实现国际化（i18n）
• 为区域格式启用本地化（l10n）
• 为适用语言添加 RTL（从右到左）支持
• 配置高级无障碍访问功能

高级功能

📄 阅读： references/advanced-features.md

当你需要：

• 处理图表事件（load、loaded、pointClick、seriesRender、axisLabelRender 等）
• 导出图表（PDF、SVG、PNG、JPEG、CSV、XLSX）
• 实现打印功能
• 了解用于摇树优化的模块注入
• 使用不同的渲染方式（SVG、Canvas）
• 配置动画设置
• 处理空数据点模式
• 以编程方式调用图表 API 方法
• 实现高级事件驱动交互
• 通过 WebMCP 工具将 Chart 与浏览器模型上下文集成

常见模式与示例

📄 阅读： references/common-patterns.md

当你需要：

• 查看常见使用场景的完整示例
• 构建趋势分析仪表板
• 创建带有技术指标的金融股票图表
• 实现具有实时更新功能的实时数据监控
• 构建多轴对比图表
• 创建分布分析可视化
• 查找常见问题的故障排除方案
• 学习性能优化技巧
• 从 EJ1 Chart 迁移到 EJ2 Chart
• 遵循图表实现最佳实践

快速入门示例

以下是创建基本折线图的最简示例：

import { ChartModule } from '@syncfusion/ej2-angular-charts'
import { CategoryService, LineSeriesService, DateTimeService } from '@syncfusion/ej2-angular-charts'
import { Component, OnInit } from '@angular/core';

@Component({
imports: [ ChartModule ],
providers: [ CategoryService, LineSeriesService, StepLineSeriesService, SplineSeriesService, StackingLineSeriesService, DateTimeService,
        SplineAreaSeriesService, MultiColoredLineSeriesService, ParetoSeriesService, ColumnSeriesService],
standalone: true,
    selector: 'app-container',
    template: `<ejs-chart id="chart-container" [primaryXAxis]='primaryXAxis'[primaryYAxis]='primaryYAxis'
    [title]='title'>
        <e-series-collection>
            <e-series [dataSource]='chartData' type='Line' xName='month' yName='sales'></e-series>
        </e-series-collection>
    </ejs-chart>`
})
export class AppComponent implements OnInit {
    public chartData?: Object[];
    public title?: string;
     public primaryXAxis?: Object;
      public primaryYAxis?: Object;
    ngOnInit(): void {
        this.chartData = [
          { month: 'Jan', sales: 35 },
          { month: 'Feb', sales: 28 },
          { month: 'Mar', sales: 34 },
          { month: 'Apr', sales: 32 },
          { month: 'May', sales: 40 },
          { month: 'Jun', sales: 32 },
          { month: 'Jul', sales: 35 },
          { month: 'Aug', sales: 55 },
          { month: 'Sep', sales: 38 },
          { month: 'Oct', sales: 30 },
          { month: 'Nov', sales: 25 },
          { month: 'Dec', sales: 32 }
      ];
        this.primaryXAxis = {
            interval: 1,
            valueType: 'Category',
        };
        this.primaryYAxis =
        {
            title: 'Sales',
        },
        this.title = 'Monthly Sales Comparison';
    }
}

常见模式

模式 1：多系列对比图表

import { ChartModule } from '@syncfusion/ej2-angular-charts'
import { CategoryService, BarSeriesService, ColumnSeriesService, LineSeriesService, LegendService, DataLabelService, MultiLevelLabelService, SelectionService } from '@syncfusion/ej2-angular-charts'
import { Component, OnInit } from '@angular/core';

@Component({
imports: [ ChartModule ],
providers: [ CategoryService, BarSeriesService, ColumnSeriesService, LineSeriesService,LegendService, DataLabelService, MultiLevelLabelService, SelectionService],
standalone: true,
    selector: 'app-container',
    template: `<ejs-chart id="chart-container" [primaryXAxis]='primaryXAxis'[primaryYAxis]='primaryYAxis' [title]='title'>
        <e-series-collection>
            <e-series [dataSource]='chartData' type='Column' xName='country' yName='gold' name='gold'></e-series>
            <e-series [dataSource]='chartData' type='Column' xName='country' yName='silver' name='Silver'></e-series>
            <e-series [dataSource]='chartData' type='Column' xName='country' yName='bronze' name='Bronze'></e-series>
        </e-series-collection>
    </ejs-chart>`
})
export class AppComponent implements OnInit {
    public primaryXAxis?: Object;
    public chartData?: Object[];
    public title?: string;
    public primaryYAxis?: Object;
    ngOnInit(): void {
        this.chartData = [
              { country: "USA", gold: 50, silver: 70, bronze: 45 },
              { country: "China", gold: 40, silver: 60, bronze: 55 },
              { country: "Japan", gold: 70, silver: 60, bronze: 50 },
              { country: "Australia", gold: 60, silver: 56, bronze: 40 },
              { country: "France", gold: 50, silver: 45, bronze: 35 },
              { country: "Germany", gold: 40, silver: 30, bronze: 22 },
              { country: "Italy", gold: 40, silver: 35, bronze: 37 },
              { country: "Sweden", gold: 30, silver: 25, bronze: 27 }
        ];
        this.primaryXAxis = {
            valueType: 'Category',
            title: 'Countries'
        };
        this.primaryYAxis = {
            minimum: 0, maximum: 80,
            interval: 20, title: 'Medals'
        };
        this.title = 'Olympic Medals';
    }
}

模式 2：带缩放和工具提示的交互式图表

import { ChartModule } from '@syncfusion/ej2-angular-charts'
import { DateTimeService, StepLineSeriesService, ColumnSeriesService } from '@syncfusion/ej2-angular-charts'
import { LegendService, TooltipService, CategoryService, ZoomService } from '@syncfusion/ej2-angular-charts'
import { Component, OnInit } from '@angular/core';
import { toolData } from './datasource';
@Component({
imports: [ ChartModule ],
providers: [ DateTimeService, ZoomService, StepLineSeriesService, LegendService, TooltipService, CategoryService, ColumnSeriesService],
standalone: true,
    selector: 'app-container',
    template: `<ejs-chart id="chart-container" [primaryXAxis]='primaryXAxis'[primaryYAxis]='primaryYAxis' [title]='title' [tooltip]='tooltip'>
        <e-series-collection>
            <e-series [dataSource]='chartData' type='StepLine' xName='x' yName='y' width=2 name='China' [marker]='marker'></e-series>
        </e-series-collection>
    </ejs-chart>`
})
export class AppComponent implements OnInit {
    public primaryXAxis?: Object;
    public chartData?: Object[];
    public title?: string;
    public primaryYAxis?: Object;
    public marker?: Object;
    public tooltip?: Object;
    public zoom?: Object;
    ngOnInit(): void {
      this.chartData = [
              { x: new Date(1975, 0, 1), y: 16, y1: 10, y2: 4.5 },
              { x: new Date(1980, 0, 1), y: 12.5, y1: 7.5, y2: 5 },
              { x: new Date(1985, 0, 1), y: 19, y1: 11, y2: 6.5 },
              { x: new Date(1990, 0, 1), y: 14.4, y1: 7, y2: 4.4 },
              { x: new Date(1995, 0, 1), y: 11.5, y1: 8, y2: 5 },
              { x: new Date(2000, 0, 1), y: 14, y1: 6, y2: 1.5 },
              { x: new Date(2005, 0, 1), y: 10, y1: 3.5, y2: 2.5 },
              { x: new Date(2010, 0, 1), y: 16, y1: 7, y2: 3.7 }
      ];
      this.primaryXAxis = {
          valueType: 'DateTime',
      };
      this.zoom = {
            enableMouseWheelZooming: true,
            enablePinchZooming: true,
            enableSelectionZooming: true
        };
      this.tooltip = { enable: true };
      this.marker = { visible: true, width: 10, height: 10 };
      this.title = 'Unemployment Rates 1975-2010';
  }
}

模式 3：金融股票图表

import { ChartModule } from '@syncfusion/ej2-angular-charts'
import { CategoryService, CandleSeriesService } from '@syncfusion/ej2-angular-charts'
import { Component, OnInit } from '@angular/core';

@Component({
imports: [ ChartModule ],
providers: [CategoryService, CandleSeriesService],
standalone: true,
    selector: 'app-container',
    template: ` <ejs-chart style='display:block;' id='chart-container' [primaryXAxis]='primaryXAxis' [primaryYAxis]='primaryYAxis' [title]='title' >
                <e-series-collection>
                    <e-series [dataSource]='data' type='Candle' xName='x' high='high' low='low' open='open' close='close' name='SHIRPUR-G'> </e-series>
                </e-series-collection>
     </ejs-chart>`
})
export class AppComponent implements OnInit {
    public primaryXAxis?: Object;
    public title?: string;
    public primaryYAxis?: Object;
    public data?: Object[];
    ngOnInit(): void {
        this.data = [
            { x: 'Jan', open: 120, high: 160, low: 100, close: 140 },
            { x: 'Feb', open: 150, high: 190, low: 130, close: 170 },
            { x: 'Mar', open: 130, high: 170, low: 110, close: 150 },
            { x: 'Apr', open: 160, high: 180, low: 120, close: 140 },
            { x: 'May', open: 150, high: 170, low: 110, close: 130 }
            ];
        this.primaryXAxis = {
            title: 'Date',
            valueType: 'Category',
            };
        this.primaryYAxis = {
            title: 'Price', minimum: 100, maximum: 200, interval: 20,
            };
        this.title = 'Shirpur Gold Refinery Share Price';
    }
}

关键配置选项

系列配置

• type：图表类型（Line、Column、Bar、Area、Scatter 等）
• dataSource：系列的数据数组
• xName、yName：x 和 y 值的属性名称
• name：图例中显示的系列名称
• marker：数据点的标记配置
• fill：系列颜色

坐标轴配置

• valueType：坐标轴类型（Double、DateTime、Category、Logarithmic）
• title：坐标轴标题文本
• minimum、maximum：坐标轴范围
• interval：标签间隔
• labelFormat：标签格式字符串
• opposedPosition：将坐标轴置于对侧

图表配置

• title：图表标题
• width、height：图表尺寸
• theme：内置主题名称
• background：图表背景色
• legendSettings：图例配置
• zoomSettings：缩放配置
• tooltip：工具提示配置

常见使用场景

1. 业务仪表板： 展示 KPI、销售趋势、收入对比
2. 金融应用： 股票图表、投资组合表现、技术分析
3. 分析平台： 用户行为、流量分析、转化漏斗
4. 科学可视化： 实验数据、统计分布、相关性分析
5. 监控系统： 实时指标、系统性能、IoT 数据
6. 报告工具： 自动生成报告、数据导出、定时可视化
7. 教育应用： 数学图表、统计教学、数据科学演示

后续步骤

创建基本图表后：

• 根据具体的数据可视化需求探索不同的系列类型
• 添加缩放和工具提示等交互功能，提升用户体验
• 使用主题和样式自定义外观
• 实现动态数据源的数据绑定
• 确保所有用户都能访问
• 添加导出和打印功能，以便分享可视化内容

如需详细的实现指南，请参阅上方导航指南中列出的具体参考文件。

API 参考文档

📄 完整 API 指南： references/api-reference.md

Syncfusion Angular Chart 组件提供 200 多个 API 文档文件，涵盖：

• 核心 API： ChartModel（40 多个属性）、AxisModel（50 多个属性）、SeriesDirective（60 多个属性）
• 图表元素： 图例、标记、数据标签、工具提示、注释、趋势线、技术指标、条纹线
• 交互功能： 缩放、平移、十字准线、选择、拖动设置
• AI 集成： WebMCP 启用、设置、工具注册、工具执行、确认和清理
• 事件： 40 多个事件接口（ILoadedEventArgs、IPointRenderEventArgs、IZoomingEventArgs 等）
• 枚举： 50 多个枚举（ChartSeriesType、ValueType、ChartTheme、SelectionMode、ExportType 等）
• 实用工具： BorderModel、FontModel、MarginModel、AnimationModel 等

所有 API 文档均可在 https://ej2.syncfusion.com/angular/documentation/api/chart/ 查看。有关全面的 API 导航和文档结构，请参阅 references/api-reference.md。

每份参考指南（getting-started.md、series-types.md、axes-and-layout.md 等）均在内容中链接到官方在线 API 文档。