syncfusion-javascript-chart

在 Syncfusion TypeScript 和 JavaScript 中实现图表

Syncfusion EJ2 Charts 包提供全面的可视化组件集合，可用于构建交互式、数据驱动的应用和仪表板。

请根据所需的可视化效果使用相应组件：

• 使用 Chart 展示笛卡尔坐标系、统计、金融、极坐标和雷达系列。
• 使用 AccumulationChart 展示饼图、圆环图、漏斗图和金字塔图。
• 对于需要内置范围选择、周期、指标和股票专用控件的金融仪表板，请使用 StockChart。

该包支持多个系列、坐标轴、技术指标、趋势线、动画、导出、打印、无障碍功能、从右向左渲染以及实时数据更新。

平台支持

此技能涵盖 TypeScript 和 JavaScript 实现。

TypeScript

TypeScript 实现使用：

• 通过 npm 安装包。
• 从 @syncfusion/ej2-charts 导入模块。
• 通过 Chart.Inject(...) 注册功能。
• 类型化数据模型。
• 类型化事件参数。
• webpack 或 Vite 等打包工具。
• 完整的 IDE 和编译器支持。

JavaScript

JavaScript 实现使用：

• 整合式或独立的 CDN 脚本。
• 在需要时使用本地 ES5 脚本文件。
• 全局 ej.charts 命名空间。
• 通过 ej.charts.Chart.Inject(...) 注册功能。
• 无需 TypeScript 编译步骤。

TypeScript 和 JavaScript 的配置模型通常相同。不过，包加载、导入、模块注入、全局命名空间访问和类型注解在不同平台上有所不同。

何时使用此技能

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

• 创建笛卡尔图表： 构建折线图、样条图、面积图、条形图、柱状图、散点图、气泡图、范围图、阶梯图、直方图、箱线图、瀑布图、帕累托图或金融图表。
• 创建累积图表： 使用 AccumulationChart 构建饼图、圆环图、漏斗图或金字塔图。
• 创建金融仪表板： 使用蜡烛图、Hilo、HiloOpenClose、指标、趋势线或 StockChart。
• 可视化复杂数据： 配置多个系列、堆叠系列、分组数据、多个坐标轴和图表窗格。
• 构建交互式仪表板： 将图表与动态或实时数据相结合。
• 自定义外观： 配置调色板、填充、渐变、字体排印、边框、背景、主题和响应式行为。
• 添加交互功能： 启用工具提示、十字线、类似轨迹球的交互、图例、高亮、选择、缩放和平移。
• 实现高级分析： 添加技术指标、趋势线、注释和金融分析。
• 导出或打印图表： 将图表导出为支持的图像、文档或数据格式，并打印渲染后的图表。
• 优化性能： 筛选、汇总、限制或逐步加载大型数据集，并在适当时使用 Canvas 渲染。
• 支持无障碍访问： 配置描述、键盘导航、焦点样式、屏幕阅读器支持、无障碍摘要、数据表格和 RTL 布局。
• 排查应用问题： 诊断渲染、数据绑定、模块注入、浏览器兼容性和性能问题。

组件选择

在实现可视化效果前，请先选择组件。

使用 Chart

以下内容请使用 Chart：

• 折线图和样条图。
• 面积图和堆叠面积图。
• 条形图和柱状图。
• 散点图和气泡图。
• 范围系列。
• 阶梯系列。
• 直方图。
• 箱线图。
• 瀑布图。
• 帕累托图。
• 极坐标图和雷达图。
• 蜡烛图、Hilo 和 HiloOpenClose。
• 技术指标。
• 趋势线。

使用 AccumulationChart

以下内容请使用 AccumulationChart：

• 饼图。
• 圆环图。
• 漏斗图。
• 金字塔图。

圆环图是 innerRadius 非零的饼图系列。

请勿配置：

type: 'Doughnut'

请使用：

type: 'Pie',
innerRadius: '50%'

使用 StockChart

当应用需要以股票为核心的界面，并具备以下功能时，请使用 StockChart：

• 内置范围选择。
• 周期选择器。
• 金融序列切换。
• 技术指标。
• 股票专用工具栏。
• 金融数据导出和打印控件。

导航指南

仅阅读与用户任务相关的参考文件。

TypeScript 和 JavaScript 的 WebMCP

📄 阅读： TypeScript API 参考 和 JavaScript API 参考

• TypeScript WebMCP 示例必须导入并注入所有可用的 Chart 功能模块，包括 WebMcpChart。
• 不要根据初始序列类型删减 TypeScript 导入或注入项。
• 使用全局 EJ2 包的浏览器 JavaScript WebMCP 示例不得包含导入或注入调用。
• JavaScript 示例必须在加载一体化浏览器脚本后使用 new ej.charts.Chart(...)。
• 两种语言都必须使用稳定的 Chart ID、自动注册和已验证的 WebMCP 工具名称。
• 绝不要生成 registerWebMcpTools() 或手动注册按钮。

入门指南

阅读 references/getting-started.md，了解：

• 包安装。
• TypeScript 和 JavaScript 设置。
• 模块注入。
• 创建基本 Chart。
• 本地数据绑定。
• 主题选择。
• 初步故障排除。

Chart 类型与选择

阅读 references/chart-types.md，了解：

• 笛卡尔 Chart 类型。
• 统计类和专用 Chart。
• 金融序列。
• 极坐标和雷达 Chart。
• 饼图、环形图、漏斗图和金字塔图组件的选择。
• 选择合适可视化方式的指南。
• 各种 Chart 类型所需的模块。

序列配置

阅读 references/series-configuration.md，了解：

• 序列属性和映射。
• 多个序列。
• 数据标签。
• 标记。
• 序列边框和填充。
• 堆叠和分组。
• 堆叠组。
• 空数据点处理。
• 多轴序列。

坐标轴自定义

阅读 references/axes-customization.md，了解：

• 数值、类别、DateTime、DateTimeCategory 和对数坐标轴。
• 坐标轴标签和格式设置。
• 坐标轴范围和缩放。
• 多个坐标轴。
• 多个窗格。
• 坐标轴位置。
• 网格线和刻度线。
• 区域线。

功能与交互

阅读 references/features-interaction.md，了解：

• 工具提示和内嵌工具提示格式设置。
• 共享工具提示。
• 十字准线。
• 追踪球式交互。
• 图例和高亮。
• 数据点、序列和簇的选择。
• 缩放和平移。
• Chart 注释。
• 交互事件。

样式与外观

阅读 references/styling-appearance.md，了解：

• 自定义调色板。
• 数据驱动和条件数据点颜色。
• 线性和径向渐变。
• 排版。
• 边框和背景。
• Chart 区域样式。
• 响应式布局。
• 内置主题。
• 动态主题切换。

高级功能

阅读 references/advanced-features.md，了解：

• 技术指标。
• SMA、EMA、MACD、RSI、ATR、布林带和随机指标。
• 趋势线和预测。
• 动画。
• 导出为支持的图像、文档和数据格式。
• 打印。
• 减少动态效果的处理。

数据处理与更新

阅读 references/data-handling.md，了解：

• 动态替换数据。
• 添加、更新和删除数据点。
• 实时 Chart。
• WebSocket 更新。
• API 轮询。
• 基于拖动的数据编辑。
• 本地和远程数据源。
• DataManager。
• CSV 数据。
• 大型数据集筛选和聚合。
• 资源清理。

无障碍与 RTL 支持

阅读 references/accessibility-rtl.md，了解：

• WCAG 和 WAI-ARIA 支持。
• Chart 级无障碍配置。
• 序列和数据点的无障碍支持。
• 键盘导航。
• 焦点边框自定义。
• 屏幕阅读器摘要。
• 语义数据表。
• ARIA 实时区域播报。
• 颜色和对比度指南。
• 从右向左渲染。
• 动态语言切换。

故障排除与优化

阅读 references/troubleshooting.md，了解以下内容：

• 图表空白或缺失。
• 字段映射无效。
• 模块未注入。
• 工具提示和图例问题。
• 内存清理。
• TypeScript 和 CDN 问题。
• SVG 和 Canvas 渲染。
• 大型数据集优化。
• 浏览器兼容性。
• 调试策略。

核心实现规则

每次实现都请遵循以下规则。

选择正确的组件

• Cartesian、统计、Polar、Radar 和金融系列使用 Chart。
• Pie、Doughnut、Funnel 和 Pyramid 使用 AccumulationChart。
• 需要内置股票专用控件时使用 StockChart。
• 不要混用不同 Chart 组件所属的 API。

注入所需模块

导入并注入配置中使用的所有系列、坐标轴和功能模块。

import {
  Category,
  Chart,
  LineSeries,
  Tooltip
} from '@syncfusion/ej2-charts';

Chart.Inject(
  LineSeries,
  Category,
  Tooltip
);

常见示例包括：

• Line Chart 使用 LineSeries。
• Column Chart 使用 ColumnSeries。
• 堆叠 Column Chart 使用 StackingColumnSeries。
• Category 坐标轴使用 Category。
• DateTime 坐标轴使用 DateTime。
• 工具提示使用 Tooltip。
• 图例使用 Legend。
• 选择功能使用 Selection。
• 缩放和平移使用 Zoom。
• Cartesian Chart 数据标签使用 DataLabel。
• 趋势线使用 Trendlines。
• 导出功能使用 Export。
• 注释使用 ChartAnnotation。

保留有效的字段映射

始终配置：

dataSource
xName
yName

确保：

• 映射的字段确实存在。
• Y 值为数字。
• DateTime 值是有效的 JavaScript Date 对象。
• 范围和金融系列包含所有必需的字段映射。

使用正确的图表级属性

使用：

legendSettings
palettes
selectionMode
zoomSettings
annotations
indicators
accessibility

不要使用：

legend
palette
selection
annotation

使用正确的 Cartesian 数据标签位置

对于常规 Cartesian Chart，通过以下方式配置数据标签：

marker: {
  dataLabel: {
    visible: true
  }
}

不要将 dataLabel 直接放在 Cartesian 系列根级别。

使用构造函数目标或 appendTo（二选一）

构造函数目标：

const chart: Chart = new Chart(
  {
    series: []
  },
  '#chart'
);

appendTo 模式：

const chart: Chart = new Chart({
  series: []
});

chart.appendTo('#chart');

不要将同一实例附加两次。

清理资源

永久移除 Chart 时：

• 清除间隔计时器和超时计时器。
• 关闭 WebSocket 连接。
• 移除应用程序自行注册的事件侦听器。
• 调用 chart.destroy()。

快速入门示例

TypeScript

安装软件包：

npm install @syncfusion/ej2-charts

添加 Chart 容器：

<div id="chart"></div>

设置稳定的容器大小：

#chart {
  width: 100%;
  min-height: 420px;
}

创建 Chart：

import {
  Chart,
  DateTime,
  LineSeries,
  Tooltip
} from '@syncfusion/ej2-charts';

Chart.Inject(
  LineSeries,
  DateTime,
  Tooltip
);

interface SalesData {
  date: Date;
  value: number;
}

const chart[To('#chart');
 attach the same instance twice.

 Up Resourcesvalue: 21
  },
  {
    date: new Date(2026, 0, 2),
    value: 24
  },
  {
    date: new Date(2026, 0, 3),
    value: 36
  },
  {
    date: new Date(2026, 0, 4),
    value: 38
  },
  {
    date: new Date(2026, 0, 5),
    value: 54
  }
];

const chart: Chart = new Chart({
  title: 'Sales Over Time',
  primaryXAxis: {
    valueType: 'DateTime',
    labelFormat: 'dd MMM',
    title: 'Date'
  },
  primaryYAxis: {
    title: 'Sales'
  },
  tooltip: {
    enable: true,
    format:
      '<b>${point.x:dd MMM yyyy}</b><br>' +
      'Sales: ${point.y:n2}'
  },
  series: [
    {
      dataSource: chartData,
      xName: 'date',
      yName: 'value',
      type: 'Line',
      name: 'Sales',
      marker: {
        visible: true
      }
    }
  ]
});

chart.appendTo('#chart');

模块用途：

• LineSeries 用于渲染 Line 系列。
• DateTime 用于支持 DateTime X 轴。
• Tooltip 用于启用数据点工具提示。

使用合并 CDN 脚本的 JavaScript

在生产环境中使用固定且一致的 EJ2 版本。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">

  <meta
    name="viewport"
    content="width=device-width, initial-scale=1.0"
  >

  <title>Sales Chart</title>

  <script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script>

  <style>
    #chart {
      width: 100%;
      min-height: 420px;
    }
  </style>
</head>

<body>
  <div id="chart"></div>

  <script>
    ej.charts.Chart.Inject(
      ej.charts.LineSeries,
      ej.charts.DateTime,
      ej.charts.Tooltip
    );

    var chartData = [
      {
        date: new Date(2026, 0, 1),
        value: 21
      },
      {
        date: new Date(2026, 0, 2),
        value: 24
      },
      {
        date: new Date(2026, 0, 3),
        value: 36
      },
      {
        date: new Date(2026, 0, 4),
        value: 38
      },
      {
        date: new Date(2026, 0, 5),
        value: 54
      }
    ];

    var chart = new ej.charts.Chart({
      title: 'Sales Over Time',
      primaryXAxis: {
        valueType: 'DateTime',
        labelFormat: 'dd MMM',
        title: 'Date'
      },
      primaryYAxis: {
        title: 'Sales'
      },
      tooltip: {
        enable: true,
        format:
          '<b>${point.x:dd MMM yyyy}</b><br>' +
          'Sales: ${point.y:n2}'
      },
      series: [
        {
          dataSource: chartData,
          xName: 'date',
          yName: 'value',
          type: 'Line',
          name: 'Sales',
          marker: {
            visible: true
          }
        }
      ]
    });

    chart.appendTo('#chart');
  </script>
</body>
</html>

使用单独 CDN 脚本的 JavaScript

需要使用单独的软件包脚本时，请按依赖顺序加载，并使用相同版本。

<script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-base/dist/global/ej2-base.min.js"></script>
<script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-data/dist/global/ej2-data.min.js"></script>
<script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-svg-base/dist/global/ej2-svg-base.min.js"></script>
<script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-charts/dist/global/ej2-charts.min.js"></script>

不要同时加载合并后的 EJ2 脚本和单独的软件包脚本。

常见模式

模式 1：多系列 Column Chart

使用常规 Column 系列进行并列比较。

所需模块：

import {
  Category,
  Chart,
  ColumnSeries,
  Legend,
  Tooltip
} from '@syncfusion/ej2-charts';

Chart.Inject(
  ColumnSeries,
  Category,
  Legend,
  Tooltip
);

配置：

series: [
  {
    dataSource: chartData,
    xName: 'month',
    yName: 'sales',
    type: 'Column',
    name: 'Sales'
  },
  {
    dataSource: chartData,
    xName: 'month',
    yName: 'revenue',
    type: 'Column',
    name: 'Revenue'
  }
],
legendSettings: {
  visible: true,
  position: 'Bottom'
},
tooltip: {
  enable: true,
  shared: true
}

模式 2：带图例的堆叠 Column Chart

所需模块：

import {
  Category,
  Chart,
  Legend,
  StackingColumnSeries,
  Tooltip
} from '@syncfusion/ej2-charts';

Chart.Inject(
  StackingColumnSeries,
  Category,
  Legend,
  Tooltip
);

配置：

series: [
  {
    dataSource: chartData,
    xName: 'category',
    yName: 'value1',
    type: 'StackingColumn',
    name: 'Current'
  },
  {
    dataSource: chartData,
    xName: 'category',
    yName: 'value2',
    type: 'StackingColumn',
    name: 'Previous'
  }
],
legendSettings: {
  visible: true,
  position: 'Bottom'
},
tooltip: {
  enable: true,
  shared: true
}

每个类别都需要归一化至 100% 时，请使用 StackingColumn100。

模式 3：实时数据更新

使用有界数据窗口，并在频繁更新时禁用动画。

interface RealTimeData {
  timestamp: Date;
  value: number;
}

let realTimeData: RealTimeData[] = [];

const maximumVisiblePoints: number = 100;

const updateInterval: number =
  window.setInterval(() => {
    const nextPoint: RealTimeData = {
      timestamp: new Date(),
      value:
        Math.round(
          Math.random() * 10000
        ) / 100
    };

    realTimeData = [
      ...realTimeData,
      nextPoint
    ].slice(-maximumVisiblePoints);

    chart.series[0].dataSource =
      realTimeData;

    chart.refresh();
  }, 5000);

window.addEventListener(
  'beforeunload',
  (): void => {
    window.clearInterval(
      updateInterval
    );

    chart.destroy();
  }
);

调用 refresh() 前应用所有更改。

模式 4：交互式数据点选择

注入 Selection。

import {
  Chart,
  ColumnSeries,
  Selection
} from '@syncfusion/ej2-charts';

Chart.Inject(
  ColumnSeries,
  Selection
);

通过图表级属性配置选择功能：

const chart: Chart = new Chart({
  selectionMode: 'Point',
  isMultiSelect: false,
  selectionPattern:
    'DiagonalForward',
  selectionComplete: (args): void => {
    console.log(
      'Selected values:',
      args.selectedDataValues
    );
  },
  series: [
    {
      dataSource: chartData,
      xName: 'category',
      yName: 'value',
      type: 'Column'
    }
  ]
});

chart.appendTo('#chart');

不要将 pointRender 用作选择事件。pointRender 用于在数据点渲染前自定义数据点。

模式 5：Pie 和 Doughnut Chart

使用 AccumulationChart。

import {
  AccumulationChart,
  PieSeries
} from '@syncfusion/ej2-charts';

AccumulationChart.Inject(
  PieSeries
);

const pieChart:
  AccumulationChart =
  new AccumulationChart({
    series: [
      {
        dataSource: chartData,
        xName: 'category',
        yName: 'value',
        type: 'Pie'
      }
    ]
  });

pieChart.appendTo('#chart');

设置 innerRadius 可创建 Doughnut Chart。

series: [
  {
    dataSource: chartData,
    xName: 'category',
    yName: 'value',
    type: 'Pie',
    innerRadius: '50%'
  }
]

模式 6：技术指标

技术指标应放在图表级 indicators 集合中。

import {
  CandleSeries,
  Chart,
  DateTime,
  LineSeries,
  SmaIndicator
} from '@syncfusion/ej2-charts';

Chart.Inject(
  CandleSeries,
  LineSeries,
  DateTime,
  SmaIndicator
);

series: [
  {
    dataSource: stockData,
    xName: 'date',
    open: 'open',
    high: 'high',
    low: 'low',
    close: 'close',
    type: 'Candle',
    name: 'Price'
  }
],
indicators: [
  {
    dataSource: stockData,
    xName: 'date',
    close: 'close',
    type: 'Sma',
    period: 20,
    seriesName: 'Price',
    name: 'SMA 20'
  }
]

不要将指标添加到常规 series 集合中。

关键属性

Chart 级属性

• primaryXAxis：配置主 X 轴。
• primaryYAxis：配置主 Y 轴。
• axes：定义其他坐标轴。
• rows：定义水平 Chart 面板。
• columns：定义垂直 Chart 面板。
• series：定义笛卡尔和金融系列。
• indicators：定义技术指标。
• annotations：定义自定义 HTML 注释。
• tooltip：配置 Chart 工具提示。
• legendSettings：配置图例。
• crosshair：配置十字线交互。
• zoomSettings：配置缩放和平移。
• selectionMode：配置数据点、系列或簇选择。
• selectedDataIndexes：定义初始选择。
• palettes：定义 Chart 颜色集合。
• theme：选择内置主题。
• background：配置 Chart 背景。
• chartArea：配置绘图区。
• title：定义 Chart 标题。
• subTitle：定义 Chart 副标题。
• height：配置 Chart 高度。
• width：配置 Chart 宽度。
• enableCanvas：启用 Canvas 渲染。
• enableRtl：启用从右到左的渲染。
• accessibility：配置 Chart 级无障碍功能。

系列级属性

• dataSource：定义系列数据。
• xName：映射 X 值字段。
• yName：映射数值型 Y 值字段。
• type：选择系列类型。
• name：定义图例和工具提示中的系列名称。
• visible：控制系列的初始可见性。
• fill：配置系列颜色。
• width：配置适用的线宽。
• opacity：配置系列不透明度。
• border：配置系列边框。
• marker：配置数据点标记。
• marker.dataLabel：配置笛卡尔 Chart 数据标签。
• pointColorMapping：从数据源映射数据点颜色。
• emptyPointSettings：配置缺失值。
• trendlines：为适用的系列定义趋势线。
• animation：配置系列动画。
• xAxisName：将系列关联到指定名称的 X 轴。
• yAxisName：将系列关联到指定名称的 Y 轴。
• stackingGroup：对适用的堆叠系列进行分组。
• accessibility：配置系列和数据点的无障碍功能。

AccumulationChart 属性

• series：定义 Pie、Doughnut、Funnel 或 Pyramid 系列。
• legendSettings：配置累积图例。
• tooltip：配置累积图工具提示。
• enableSmartLabels：减少标签重叠。
• accessibilityDescription：描述可视化内容。
• focusable：控制 Chart 是否可聚焦。
• focusBorderColor：配置焦点边框颜色。
• focusBorderWidth：配置焦点边框宽度。
• focusBorderMargin：配置焦点边框间距。

WebMCP 语言规则

TypeScript

import { Chart, WebMcpChart } from '@syncfusion/ej2-charts';

// The complete WebMCP sample must import and inject all available Chart feature modules.
Chart.Inject(WebMcpChart);

JavaScript

// No imports and no Chart.Inject(...) for global-bundle JavaScript WebMCP samples.
var chart = new ej.charts.Chart({ enableWebMcp: true });