syncfusion-flutter-cartesian-charts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Flutter Cartesian Charts

实现Syncfusion Flutter笛卡尔图表

SfCartesianChart

is a high-performance Flutter widget from the

syncfusion_flutter_charts

package that supports 30+ chart types plotted on Cartesian (X/Y) coordinates. It handles real-time data, rich interactivity, and deep customization.

SfCartesianChart

是

syncfusion_flutter_charts

包提供的高性能Flutter组件，支持基于笛卡尔(X/Y)坐标绘制的30+种图表类型，兼容实时数据、丰富交互能力和高度自定义配置。

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Render any line, area, column, bar, spline, scatter, or financial chart in Flutter
Configure axis types (numeric, category, date-time, logarithmic)
Add zooming, panning, tooltip, trackball, or crosshair interaction
Customize series appearance (colors, gradients, markers, data labels)
Add annotations, technical indicators, or trendlines
Export charts or respond to chart callbacks
Support RTL, localization, or accessibility

当你需要完成以下需求时可使用本技能：

在Flutter中渲染折线图、面积图、柱状图、条形图、样条图、散点图或金融类图表
配置轴类型（数值、分类、日期时间、对数）
添加缩放、平移、提示框、轨迹球或十字线交互能力
自定义系列外观（颜色、渐变、标记点、数据标签）
添加注释、技术指标或趋势线
导出图表或响应图表回调事件
支持RTL、本地化或无障碍适配

Component Overview

组件概览

The SfCartesianChart widget is a comprehensive charting solution that displays data using Cartesian (X/Y) coordinates. It supports over 30 chart types across multiple categories:

Line Charts: Line, fast line, spline (various tension types), step line
Area Charts: Area, spline area, step area, range area, spline range area, stacked area (including 100%)
Column/Bar Charts: Column, bar, range column, stacked column/bar (including 100%)
Scatter/Bubble: Scatter, bubble charts
Financial Charts: Candle, OHLC, HiLo, HiLoOpenClose with support for technical indicators
Statistical: Histogram, box and whisker, error bar
Waterfall: For cumulative effect visualization

The widget provides five axis types (Numeric, Category, DateTime, DateTimeCategory, Logarithmic), interactive features (zoom, pan, tooltip, trackball, crosshair), selection behaviors, rich customization (markers, data labels, gradients, animations), technical indicators (SMA, EMA, MACD, RSI, Bollinger Bands, etc.), trendlines, annotations, and chart export capabilities.

SfCartesianChart 组件是基于笛卡尔(X/Y)坐标展示数据的综合图表解决方案，支持跨多个类别的30+种图表类型：

折线图：基础折线、快速折线、样条线（多种张力类型）、阶梯折线
面积图：基础面积、样条面积、阶梯面积、范围面积、样条范围面积、堆叠面积（含100%堆叠）
柱状/条形图：柱状图、条形图、范围柱状图、堆叠柱状/条形图（含100%堆叠）
散点/气泡图：散点图、气泡图
金融图表：K线图、OHLC图、HiLo图、HiLoOpenClose图，支持技术指标叠加
统计图表：直方图、箱线图、误差线图
瀑布图：用于累计效果可视化

该组件提供五种轴类型（Numeric、Category、DateTime、DateTimeCategory、Logarithmic）、交互功能（缩放、平移、提示框、轨迹球、十字线）、选中行为、丰富自定义能力（标记点、数据标签、渐变、动画）、技术指标（SMA、EMA、MACD、RSI、布林带等）、趋势线、注释和图表导出能力。

Quick Start

快速开始

bash

undefined

bash

undefined

Always installs the latest compatible version automatically

自动安装最新兼容版本

flutter pub add syncfusion_flutter_charts

> Always install the package via terminal — do **not** edit `pubspec.yaml` directly.
> Run this command from the Flutter project root and wait for it to complete successfully before proceeding.

```dart
import 'package:syncfusion_flutter_charts/charts.dart';

class MyChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return SizedBox(
      height: 300,
      child: SfCartesianChart(
        primaryXAxis: CategoryAxis(),
        title: ChartTitle(text: 'Monthly Sales'),
        legend: Legend(isVisible: true),
        tooltipBehavior: TooltipBehavior(enable: true),
        series: <CartesianSeries>[
          LineSeries<ChartData, String>(
            dataSource: [
              ChartData('Jan', 35),
              ChartData('Feb', 28),
              ChartData('Mar', 34),
              ChartData('Apr', 32),
              ChartData('May', 40),
            ],
            xValueMapper: (ChartData d, _) => d.x,
            yValueMapper: (ChartData d, _) => d.y,
            name: 'Sales',
            dataLabelSettings: DataLabelSettings(isVisible: true),
          ),
        ],
      ),
    );
  }
}

class ChartData {
  ChartData(this.x, this.y);
  final String x;
  final double? y;
}

flutter pub add syncfusion_flutter_charts

> 请始终通过终端安装该包——**不要**直接编辑`pubspec.yaml`文件。
> 请在Flutter项目根目录运行该命令，等待执行成功后再进行后续操作。

```dart
import 'package:syncfusion_flutter_charts/charts.dart';

class MyChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return SizedBox(
      height: 300,
      child: SfCartesianChart(
        primaryXAxis: CategoryAxis(),
        title: ChartTitle(text: '月度销售额'),
        legend: Legend(isVisible: true),
        tooltipBehavior: TooltipBehavior(enable: true),
        series: <CartesianSeries>[
          LineSeries<ChartData, String>(
            dataSource: [
              ChartData('1月', 35),
              ChartData('2月', 28),
              ChartData('3月', 34),
              ChartData('4月', 32),
              ChartData('5月', 40),
            ],
            xValueMapper: (ChartData d, _) => d.x,
            yValueMapper: (ChartData d, _) => d.y,
            name: '销售额',
            dataLabelSettings: DataLabelSettings(isVisible: true),
          ),
        ],
      ),
    );
  }
}

class ChartData {
  ChartData(this.x, this.y);
  final String x;
  final double? y;
}

Navigation Guide

导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Package installation and import
Initialize SfCartesianChart
Bind data source and data model
Add title, data labels, legend, tooltip
Complete minimal working example

📄 阅读： references/getting-started.md

包安装与导入
初始化SfCartesianChart
绑定数据源与数据模型
添加标题、数据标签、图例、提示框
完整最小可运行示例

Line, Area & Spline Chart Types

折线、面积与样条图表类型

📄 Read: references/chart-types-line-area.md

Line, fast line, spline (with spline types)
Step line, area, spline area
Step area, range area, spline range area
When to use each type

📄 阅读： references/chart-types-line-area.md

折线、快速折线、样条线（含样条类型说明）
阶梯折线、面积图、样条面积图
阶梯面积、范围面积、样条范围面积
各类型适用场景

Column, Bar & Other Cartesian Types

柱状、条形与其他笛卡尔图表类型

📄 Read: references/chart-types-column-bar.md

Column, bar, range column
Bubble, scatter, histogram
Waterfall, error bar, box and whisker
Key configuration for each type

📄 阅读： references/chart-types-column-bar.md

柱状图、条形图、范围柱状图
气泡图、散点图、直方图
瀑布图、误差线图、箱线图
各类型核心配置说明

Stacked Chart Types

堆叠图表类型

📄 Read: references/chart-types-stacked.md

Stacked area/bar/column/line
100% stacked variants
When to choose stacked vs 100% stacked

📄 阅读： references/chart-types-stacked.md

堆叠面积/条形/柱状/折线图
100%堆叠变体
堆叠图与100%堆叠图的选型建议

Financial Chart Types

金融图表类型

📄 Read: references/chart-types-financial.md

Candle, HILO, OHLC charts
Financial data model (open/high/low/close mappers)
Hollow candle and solid candle

📄 阅读： references/chart-types-financial.md

K线图、HILO图、OHLC图
金融数据模型（开/高/低/收映射）
空心K线与实心K线

Axis Types

轴类型

📄 Read: references/axis-types.md

NumericAxis, CategoryAxis, DateTimeAxis
DateTimeCategoryAxis, LogarithmicAxis
Choosing the right axis for your data

📄 阅读： references/axis-types.md

NumericAxis、CategoryAxis、DateTimeAxis
DateTimeCategoryAxis、LogarithmicAxis
如何为你的数据选择合适的轴

Axis Customization

轴自定义

📄 Read: references/axis-customization.md

Title, labels, label format
Gridlines, tick marks, range (min/max/interval)
Strip lines, multi-level labels
Secondary axis, axis crossing, inversed axis

📄 阅读： references/axis-customization.md

标题、标签、标签格式
网格线、刻度、范围（最小值/最大值/间隔）
带状线、多级标签
次轴、轴交叉、反向轴

Series Customization

系列自定义

📄 Read: references/series-customization.md

Color, border, opacity, gradient fill
Dash array, width, point color mapper
Animation, palette colors, empty point settings

📄 阅读： references/series-customization.md

颜色、边框、透明度、渐变填充
虚线数组、宽度、点颜色映射
动画、调色板颜色、空点设置

Legend

图例

📄 Read: references/legend.md

Enable and position legend
Toggle series visibility via legend
Overflow modes (wrap, scroll)
Custom legend items and icons

📄 阅读： references/legend.md

图例启用与位置配置
通过图例切换系列可见性
溢出模式（换行、滚动）
自定义图例项与图标

Tooltip, Trackball & Crosshair

提示框、轨迹球与十字线

📄 Read: references/tooltip-trackball.md

TooltipBehavior — enable, format, custom template
Shared tooltip across series
TrackballBehavior — display modes
CrosshairBehavior configuration

📄 阅读： references/tooltip-trackball.md

TooltipBehavior — 启用、格式、自定义模板
跨系列共享提示框
TrackballBehavior — 展示模式
CrosshairBehavior配置

Zooming, Panning & Selection

缩放、平移与选中

📄 Read: references/zoom-pan-selection.md

ZoomPanBehavior — pinch, mouse wheel, directional
ZoomMode (x, y, xy), panning
Auto-scrolling for live data
SelectionBehavior — point, series, cluster, box

📄 阅读： references/zoom-pan-selection.md

ZoomPanBehavior — 捏合、鼠标滚轮、定向缩放
ZoomMode（x、y、xy）、平移
实时数据自动滚动
SelectionBehavior — 点、系列、集群、框选

Annotations, Markers & Data Labels

注释、标记点与数据标签

📄 Read: references/annotations-markers-datalabels.md

CartesianChartAnnotation — text and widget overlays
Coordinate units (point vs pixel vs percent)
MarkerSettings — shape, size, color
DataLabelSettings — position, format, template, connector lines

📄 阅读： references/annotations-markers-datalabels.md

CartesianChartAnnotation — 文本与组件覆盖层
坐标单位（点/像素/百分比）
MarkerSettings — 形状、大小、颜色
DataLabelSettings — 位置、格式、模板、连接线

Technical Indicators & Trendlines

技术指标与趋势线

📄 Read: references/technical-indicators-trendlines.md

SMA, EMA, TMA, WMA, MACD, RSI, Stochastic
Bollinger Bands, ATR, CCI, Momentum, AD, ROC
Trendline types (linear, exponential, polynomial, moving average, power, logarithmic)
Forecasting periods

📄 阅读： references/technical-indicators-trendlines.md

SMA、EMA、TMA、WMA、MACD、RSI、Stochastic
布林带、ATR、CCI、动量指标、AD、ROC
趋势线类型（线性、指数、多项式、移动平均、幂次、对数）
预测周期设置

Chart Appearance & Multiple Charts

图表外观与多图表处理

📄 Read: references/chart-appearance.md

Background color/image, plot area customization
Color palette, theme integration
Rendering multiple charts on the same screen
On-demand / lazy data loading

📄 阅读： references/chart-appearance.md

背景色/背景图、绘图区自定义
调色板、主题集成
同屏渲染多个图表
按需/懒加载数据

Callbacks, Methods, Export & Accessibility

回调、方法、导出与无障碍

📄 Read: references/callbacks-methods-export.md

Key callbacks (onTooltipRender, onDataLabelRender, onZooming, etc.)
ChartSeriesController methods (updateDataSource, animate)
Export to PNG, PDF, JPEG
Localization, RTL, accessibility

📄 阅读： references/callbacks-methods-export.md

核心回调（onTooltipRender、onDataLabelRender、onZooming等）
ChartSeriesController方法（updateDataSource、animate）
导出为PNG、PDF、JPEG
本地化、RTL、无障碍适配

Common Patterns

常见模式

Pattern 1 — Live / Real-Time Data Update

模式1 — 实时/动态数据更新

dart

late ChartSeriesController _controller;

onRendererCreated: (ChartSeriesController controller) {
  _controller = controller;
},

void addDataPoint(ChartData newPoint) {
  chartData.add(newPoint);
  _controller.updateDataSource(
    addedDataIndexes: [chartData.length - 1],
  );
}

dart

late ChartSeriesController _controller;

onRendererCreated: (ChartSeriesController controller) {
  _controller = controller;
},

void addDataPoint(ChartData newPoint) {
  chartData.add(newPoint);
  _controller.updateDataSource(
    addedDataIndexes: [chartData.length - 1],
  );
}

Pattern 2 — Multiple Series on One Chart

模式2 — 单图表多系列

dart

series: <CartesianSeries>[
  LineSeries<ChartData, String>(
    dataSource: data,
    xValueMapper: (d, _) => d.x,
    yValueMapper: (d, _) => d.y1,
    name: 'Revenue',
  ),
  ColumnSeries<ChartData, String>(
    dataSource: data,
    xValueMapper: (d, _) => d.x,
    yValueMapper: (d, _) => d.y2,
    name: 'Cost',
  ),
]

dart

series: <CartesianSeries>[
  LineSeries<ChartData, String>(
    dataSource: data,
    xValueMapper: (d, _) => d.x,
    yValueMapper: (d, _) => d.y1,
    name: '营收',
  ),
  ColumnSeries<ChartData, String>(
    dataSource: data,
    xValueMapper: (d, _) => d.x,
    yValueMapper: (d, _) => d.y2,
    name: '成本',
  ),
]

Pattern 3 — Zoom + Tooltip Together

模式3 — 缩放+提示框组合使用

dart

late ZoomPanBehavior _zoom;
late TooltipBehavior _tooltip;

@override
void initState() {
  _zoom = ZoomPanBehavior(enablePinching: true, enableDoubleTapZooming: true);
  _tooltip = TooltipBehavior(enable: true);
  super.initState();
}

zoomPanBehavior: _zoom,
tooltipBehavior: _tooltip,

dart

late ZoomPanBehavior _zoom;
late TooltipBehavior _tooltip;

@override
void initState() {
  _zoom = ZoomPanBehavior(enablePinching: true, enableDoubleTapZooming: true);
  _tooltip = TooltipBehavior(enable: true);
  super.initState();
}

zoomPanBehavior: _zoom,
tooltipBehavior: _tooltip,

Key Widget Properties

核心组件属性

Property	Type	Purpose
`primaryXAxis`	`ChartAxis`	Horizontal axis type and config
`primaryYAxis`	`ChartAxis`	Vertical axis type and config
`series`	`List<CartesianSeries>`	One or more data series
`title`	`ChartTitle`	Chart heading text
`legend`	`Legend`	Legend visibility and position
`tooltipBehavior`	`TooltipBehavior`	Tooltip on tap
`zoomPanBehavior`	`ZoomPanBehavior`	Zoom and pan interaction
`selectionType`	`SelectionType`	Point/series/cluster selection
`annotations`	`List<CartesianChartAnnotation>`	Overlay widgets/text
`indicators`	`List<TechnicalIndicator>`	Technical analysis overlays
`onTooltipRender`	`ChartTooltipCallback`	Customize tooltip text
`onZooming`	`ChartZoomingCallback`	Respond to zoom events
`palette`	`List<Color>`	Custom series color palette

属性	类型	用途
`primaryXAxis`	`ChartAxis`	水平轴类型与配置
`primaryYAxis`	`ChartAxis`	垂直轴类型与配置
`series`	`List<CartesianSeries>`	一个或多个数据系列
`title`	`ChartTitle`	图表标题文本
`legend`	`Legend`	图例可见性与位置
`tooltipBehavior`	`TooltipBehavior`	点击触发的提示框配置
`zoomPanBehavior`	`ZoomPanBehavior`	缩放和平移交互配置
`selectionType`	`SelectionType`	点/系列/集群选中模式
`annotations`	`List<CartesianChartAnnotation>`	覆盖层组件/文本
`indicators`	`List<TechnicalIndicator>`	技术分析覆盖层
`onTooltipRender`	`ChartTooltipCallback`	自定义提示框文本
`onZooming`	`ChartZoomingCallback`	响应缩放事件
`palette`	`List<Color>`	自定义系列颜色调色板