syncfusion-flutter-circular-charts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Flutter Circular Charts

实现Syncfusion Flutter环形图表

SfCircularChart

is Syncfusion's high-performance Flutter widget for rendering pie, doughnut, and radial bar charts. It supports rich interactivity (tooltips, selection, explode), beautiful customization (gradients, animations, data labels), and accessibility out of the box.

SfCircularChart

是Syncfusion推出的高性能Flutter组件，用于渲染饼图、环形图和径向条形图。它开箱即支持丰富的交互能力（提示框、选中、扇区分离）、精美的自定义效果（渐变、动画、数据标签）以及无障碍特性。

When to Use This Skill

什么时候使用本技能

User wants a pie chart to show part-to-whole proportions
User wants a doughnut chart — ring-style chart, optionally with center content
User wants a radial bar chart for comparing categories in circular arcs

Any

SfCircularChart

PieSeries

DoughnutSeries

, or

RadialBarSeries

question

Customizing segment colors, explode behavior, grouping small slices
Adding data labels inside/outside slices with connector lines
Configuring legend, tooltip, selection, annotations
Exporting the chart as PNG or PDF
Handling accessibility or RTL layouts

用户需要饼图来展示部分占整体的比例
用户需要环形图——环状样式的图表，可选择性添加中心内容
用户需要径向条形图，以圆弧形式对比不同类别数据

任何与

SfCircularChart

、

PieSeries

、

DoughnutSeries

或

RadialBarSeries

Component Overview

组件概览

The SfCircularChart widget is a high-performance charting solution for displaying proportional data in circular formats. It supports three primary series types:

PieSeries: Traditional pie chart showing data as segments of a circle. Supports exploding segments, semi-circle rendering, grouping small slices, per-point radius customization, and various interaction modes.
DoughnutSeries: Ring-shaped chart with customizable inner radius. Ideal for displaying data with center annotations, supports rounded corners, center elevation effects, and all pie chart features.
RadialBarSeries: Circular progress-style chart with customizable tracks. Features include maximum value configuration, corner styles (flat/rounded), track opacity and color customization, and data labels along the arc.

All series types support rich interactivity (tooltips, selection, tap gestures), comprehensive data label positioning (inside/outside with connector lines), legend configuration, animations with customizable duration and delay, gradient fills (linear/sweep/radial), image shaders, empty point handling, data sorting, and chart export to PNG/PDF formats. The widget provides accessibility features, RTL support, and extensive customization through color mapping, point-specific colors, and annotations.

SfCircularChart组件是高性能图表解决方案，用于以圆形格式展示比例数据。它支持三种核心系列类型：

PieSeries：传统饼图，将数据展示为圆形的各个扇区。支持扇区分离、半圆渲染、小扇区分组、单扇区半径自定义以及多种交互模式。
DoughnutSeries：环形图表，支持自定义内半径。非常适合展示带中心注释的数据，支持圆角、中心凸起效果以及所有饼图特性。
RadialBarSeries：类环形进度条样式的图表，支持自定义轨道。特性包括最大值配置、角样式（平角/圆角）、轨道透明度和颜色自定义、沿圆弧展示数据标签。

所有系列类型都支持丰富的交互能力（提示框、选中、点击手势）、全面的数据标签定位（带连接线的内/外显示）、图例配置、可自定义时长和延迟的动画、渐变填充（线性/扫描/径向）、图片着色器、空值处理、数据排序以及图表导出为PNG/PDF格式。该组件提供无障碍特性、RTL支持，并且可通过颜色映射、单点位颜色、注释等实现高度自定义。

Quick Start

快速开始

dart

import 'package:syncfusion_flutter_charts/charts.dart';

class MyChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final List<ChartData> data = [
      ChartData('Jan', 35),
      ChartData('Feb', 28),
      ChartData('Mar', 34),
      ChartData('Apr', 32),
      ChartData('May', 40),
    ];

    return SfCircularChart(
      title: ChartTitle(text: 'Monthly Sales'),
      legend: Legend(isVisible: true),
      tooltipBehavior: TooltipBehavior(enable: true),
      series: <CircularSeries>[
        PieSeries<ChartData, String>(
          dataSource: data,
          xValueMapper: (ChartData d, _) => d.x,
          yValueMapper: (ChartData d, _) => d.y,
          dataLabelSettings: DataLabelSettings(isVisible: true),
          enableTooltip: true,
        ),
      ],
    );
  }
}

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

dart

import 'package:syncfusion_flutter_charts/charts.dart';

class MyChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final List<ChartData> data = [
      ChartData('Jan', 35),
      ChartData('Feb', 28),
      ChartData('Mar', 34),
      ChartData('Apr', 32),
      ChartData('May', 40),
    ];

    return SfCircularChart(
      title: ChartTitle(text: 'Monthly Sales'),
      legend: Legend(isVisible: true),
      tooltipBehavior: TooltipBehavior(enable: true),
      series: <CircularSeries>[
        PieSeries<ChartData, String>(
          dataSource: data,
          xValueMapper: (ChartData d, _) => d.x,
          yValueMapper: (ChartData d, _) => d.y,
          dataLabelSettings: DataLabelSettings(isVisible: true),
          enableTooltip: true,
        ),
      ],
    );
  }
}

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

Common Patterns

常用模式

Doughnut with center annotation

带中心注释的环形图

dart

SfCircularChart(
  annotations: <CircularChartAnnotation>[
    CircularChartAnnotation(
      widget: Text('62%', style: TextStyle(fontSize: 25)),
    ),
  ],
  series: <CircularSeries>[
    DoughnutSeries<ChartData, String>(
      dataSource: data,
      xValueMapper: (d, _) => d.x,
      yValueMapper: (d, _) => d.y,
      innerRadius: '60%',
    ),
  ],
)

dart

SfCircularChart(
  annotations: <CircularChartAnnotation>[
    CircularChartAnnotation(
      widget: Text('62%', style: TextStyle(fontSize: 25)),
    ),
  ],
  series: <CircularSeries>[
    DoughnutSeries<ChartData, String>(
      dataSource: data,
      xValueMapper: (d, _) => d.x,
      yValueMapper: (d, _) => d.y,
      innerRadius: '60%',
    ),
  ],
)

Radial bar with track and rounded corners

带轨道和圆角的径向条形图

dart

RadialBarSeries<ChartData, String>(
  dataSource: data,
  xValueMapper: (d, _) => d.x,
  yValueMapper: (d, _) => d.y,
  maximumValue: 100,
  cornerStyle: CornerStyle.bothCurve,
  useSeriesColor: true,
  trackOpacity: 0.3,
)

dart

RadialBarSeries<ChartData, String>(
  dataSource: data,
  xValueMapper: (d, _) => d.x,
  yValueMapper: (d, _) => d.y,
  maximumValue: 100,
  cornerStyle: CornerStyle.bothCurve,
  useSeriesColor: true,
  trackOpacity: 0.3,
)

Pie with exploded segment on tap

点击分离扇区的饼图

dart

PieSeries<ChartData, String>(
  dataSource: data,
  xValueMapper: (d, _) => d.x,
  yValueMapper: (d, _) => d.y,
  explode: true,
  explodeIndex: 0,
  explodeGesture: ActivationMode.singleTap,
)

dart

PieSeries<ChartData, String>(
  dataSource: data,
  xValueMapper: (d, _) => d.x,
  yValueMapper: (d, _) => d.y,
  explode: true,
  explodeIndex: 0,
  explodeGesture: ActivationMode.singleTap,
)

Key Properties

核心属性

Prop	Where	Purpose
`series`	`SfCircularChart`	List of `CircularSeries` (Pie/Doughnut/RadialBar)
`xValueMapper`	Series	Category label per data point
`yValueMapper`	Series	Numeric value per data point
`dataLabelSettings`	Series	Show/style data labels
`legend`	`SfCircularChart`	Show legend
`tooltipBehavior`	`SfCircularChart`	Configure tooltip
`annotations`	`SfCircularChart`	Overlay widgets on chart
`radius`	Series	Outer size as `'80%'` (default)
`innerRadius`	Doughnut/RadialBar	Inner hole size
`explode`	Pie/Doughnut	Enable segment pop-out on tap
`maximumValue`	RadialBarSeries	Full-arc reference value
`palette`	`SfCircularChart`	Chart-level color list

属性	所属位置	作用
`series`	`SfCircularChart`	`CircularSeries` （饼图/环形图/径向条形图）列表
`xValueMapper`	系列	每个数据点的分类标签
`yValueMapper`	系列	每个数据点的数值
`dataLabelSettings`	系列	展示/设置数据标签样式
`legend`	`SfCircularChart`	展示图例
`tooltipBehavior`	`SfCircularChart`	配置提示框
`annotations`	`SfCircularChart`	图表上的叠加组件
`radius`	系列	外层尺寸，默认值为 `'80%'`
`innerRadius`	环形图/径向条形图	内孔尺寸
`explode`	饼图/环形图	启用点击扇区弹出效果
`maximumValue`	径向条形图系列	全圆弧参考值
`palette`	`SfCircularChart`	图表级颜色列表

Documentation and Navigation Guide

文档和导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Package installation and pubspec setup
Import statement and initialization
Binding data source with
```
PieSeries
```
Adding title, data labels, legend, tooltip
Complete runnable minimal example

📄 阅读： references/getting-started.md

包安装和pubspec配置
导入语句和初始化
为
```
PieSeries
```
绑定数据源
添加标题、数据标签、图例、提示框
完整可运行的最小示例

Chart Types (Pie, Doughnut, Radial Bar)

图表类型（饼图、环形图、径向条形图）

📄 Read: references/chart-types.md

```
PieSeries
```
— radius, explode, angle (semi-pie), grouping small slices, per-slice radius
```
DoughnutSeries
```
— inner radius, rounded corners, center elevation, angle, grouping
```
RadialBarSeries
```
— inner radius, track customization, maximumValue, overfilled bar, data labels

📄 阅读： references/chart-types.md

```
PieSeries
```
— 半径、分离、角度（半圆饼图）、小扇区分组、单扇区半径
```
DoughnutSeries
```
— 内半径、圆角、中心凸起、角度、分组
```
RadialBarSeries
```
— 内半径、轨道自定义、maximumValue、溢出条形、数据标签

Series Customization

系列自定义

📄 Read: references/series-customization.md

Animation duration and delay
Color palette and per-point color mapping
Gradient fill (linear, sweep, radial)
Image shader fill
Per-point shader mapping
Point render mode (solid vs sweep gradient)
Empty/null data point handling
Sorting data points

📄 阅读： references/series-customization.md

动画时长和延迟
调色板和单点位颜色映射
渐变填充（线性、扫描、径向）
图片着色器填充
单点位着色器映射
点位渲染模式（纯色/扫描渐变）
空/Null数据点处理
数据点排序

Data Labels

数据标签

📄 Read: references/data-labels.md

Enable and style data labels
Positioning (inside vs outside)
Smart label layout (avoid overlap)
Connector lines for outside labels
Custom label text (dataLabelMapper)
Label templates (builder)
Zero-value label suppression

📄 阅读： references/data-labels.md

启用和设置数据标签样式
定位（内部/外部）
智能标签布局（避免重叠）
外部标签的连接线
自定义标签文本（dataLabelMapper）
标签模板（builder）
零值标签隐藏

Legend and Title

图例和标题

📄 Read: references/legend-and-title.md

Enable and customize legend appearance
Legend title, positioning, and orientation
Overflow handling (wrap/scroll)
Floating legend with custom offset
Legend item templates
Chart title and text styling

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

启用和自定义图例外观
图例标题、定位和方向
溢出处理（换行/滚动）
自定义偏移的悬浮图例
图例项模板
图表标题和文本样式

Tooltip and Selection

提示框和选中效果

📄 Read: references/tooltip-and-selection.md

Enable and configure
```
TooltipBehavior
```
Tooltip format, positioning, templates
Activation modes (singleTap, longPress, doubleTap)
Segment selection with
```
SelectionBehavior
```
Customizing selected/unselected segment appearance
Multi-selection

📄 阅读： references/tooltip-and-selection.md

启用和配置
```
TooltipBehavior
```
提示框格式、定位、模板
触发模式（点击、长按、双击）
基于
```
SelectionBehavior
```
的扇区选中
自定义选中/未选中扇区的外观
多选

Annotations and Appearance

注释和外观

📄 Read: references/annotations-and-appearance.md

Placing widgets inside the chart (
```
CircularChartAnnotation
```
)
Positioning annotations by radius and alignment
Watermark pattern
Chart sizing, margin, background color and image

📄 阅读： references/annotations-and-appearance.md

在图表内放置组件（
```
CircularChartAnnotation
```
）
通过半径和对齐方式定位注释
水印图案
图表尺寸、边距、背景色和背景图

Accessibility and Export

无障碍支持和导出

📄 Read: references/accessibility-and-export.md

Accessibility (contrast, large fonts, tappable targets)
RTL (right-to-left) layout support
Export chart as PNG image (
```
toImage
```
)
Export chart as PDF (
```
syncfusion_flutter_pdf
```
)

📄 阅读： references/accessibility-and-export.md

无障碍支持（对比度、大字体、可点击目标）
RTL（从右到左）布局支持
将图表导出为PNG图片（
```
toImage
```
）
将图表导出为PDF（
```
syncfusion_flutter_pdf
```
）