flutter-chart

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flutter Chart with Graphic

基于Graphic库的Flutter图表开发

A skill for helping users build data visualizations in Flutter using the Graphic library — a Grammar of Graphics-based charting library.

本技能用于帮助用户使用Graphic库在Flutter中构建数据可视化内容，Graphic是一款基于图形语法的图表库。

When to Use

适用场景

User wants to create any type of chart in Flutter (bar, line, area, pie, scatter, heatmap, etc.)
User needs help configuring chart appearance, interactivity, or animations
User asks about Graphic library APIs or usage patterns
User wants to convert data into visual representations
User wants to create custom, bespoke visualizations — Graphic's customization system is its most powerful feature and a key strength of AI-assisted development

用户想要在Flutter中创建任意类型的图表（柱状图、折线图、面积图、饼图、散点图、热力图等）
用户需要帮助配置图表外观、交互效果或动画
用户询问Graphic库的API或使用模式
用户想要将数据转换为可视化呈现形式
用户想要创建自定义的专属可视化内容 —— Graphic的自定义系统是其最强大的特性，也是AI辅助开发的核心优势

Why Custom Charts?

为什么选择自定义图表？

Standard chart types (bar, line, pie) only cover a fraction of data visualization needs. Graphic is built on Grammar of Graphics theory, which means every visual layer is independently customizable:

Custom Shapes — Render any geometry (triangles, lollipops, arrows, gauges, bullet charts, sparklines, etc.)
Custom Tooltips — Fully custom interactive overlays with any layout
Custom Annotations — Draw any graphics at data or absolute positions
Custom Encoders — Map data to visuals using arbitrary logic
Custom Modifiers — Define custom collision/arrangement behavior

This makes AI-assisted development especially valuable: the AI can write custom shape renderers, coordinate math, and drawing code that would be tedious to implement manually.

Always consider customization when the user's requirements don't perfectly match a standard chart type. See

references/customization.md

for the comprehensive customization guide.

标准图表类型（柱状图、折线图、饼图）只能覆盖一小部分数据可视化需求。Graphic基于图形语法理论构建，这意味着每个视觉层都支持独立自定义：

自定义形状 —— 渲染任意几何图形（三角形、棒棒糖图、箭头、仪表盘、子弹图、迷你图等）
自定义提示框 —— 支持任意布局的完全自定义交互浮层
自定义标注 —— 在数据对应位置或绝对位置绘制任意图形
自定义编码器 —— 通过任意逻辑将数据映射到视觉属性
自定义修饰器 —— 定义自定义的碰撞/排布行为

这使得AI辅助开发的价值尤为突出：AI可以编写自定义形状渲染器、坐标计算和绘制代码，省去手动实现的繁琐工作。

当用户的需求不能完全匹配标准图表类型时，请优先考虑自定义能力。完整的自定义指南可查看

references/customization.md

。

Quick Start

快速开始

Installation

安装

Add to

pubspec.yaml

yaml

dependencies:
  graphic: ^latest

Then run

flutter pub get

添加到

pubspec.yaml

：

yaml

dependencies:
  graphic: ^latest

然后运行

flutter pub get

。

Import

导入

dart

import 'package:graphic/graphic.dart';

dart

import 'package:graphic/graphic.dart';

Minimal Example

最小示例

dart

Chart(
  data: [
    {'category': 'A', 'value': 10},
    {'category': 'B', 'value': 20},
    {'category': 'C', 'value': 15},
  ],
  variables: {
    'category': Variable(
      accessor: (Map map) => map['category'] as String,
    ),
    'value': Variable(
      accessor: (Map map) => map['value'] as num,
    ),
  },
  marks: [IntervalMark()],
  axes: [Defaults.horizontalAxis, Defaults.verticalAxis],
)

dart

Chart(
  data: [
    {'category': 'A', 'value': 10},
    {'category': 'B', 'value': 20},
    {'category': 'C', 'value': 15},
  ],
  variables: {
    'category': Variable(
      accessor: (Map map) => map['category'] as String,
    ),
    'value': Variable(
      accessor: (Map map) => map['value'] as num,
    ),
  },
  marks: [IntervalMark()],
  axes: [Defaults.horizontalAxis, Defaults.verticalAxis],
)

Core Concepts

核心概念

Graphic follows the Grammar of Graphics theory. A chart is composed of independent, declarative layers:

data → Variable → Scale → Encode → Mark → Shape → Render

Everything is configured through the single

Chart<D>

widget constructor. There are no imperative APIs — all configuration is declarative.

Graphic遵循图形语法理论，图表由独立的声明式层组成：

data → Variable → Scale → Encode → Mark → Shape → Render

所有配置都通过唯一的

Chart<D>

组件构造函数完成，没有命令式API，所有配置都是声明式的。

The Chart Widget

Chart组件

Chart<D>

is the only public widget. The type parameter

is the data item type. Key parameters:

Parameter	Type	Purpose
`data`	`List<D>`	Required. Data to visualize
`variables`	`Map<String, Variable<D, dynamic>>`	Required. How to extract values from data
`marks`	`List<Mark>`	Required. Geometry types to render
`coord`	`Coord?`	Coordinate system (default: `RectCoord` )
`axes`	`List<AxisGuide>?`	Axis configuration
`tooltip`	`TooltipGuide?`	Tooltip on interaction
`crosshair`	`CrosshairGuide?`	Crosshair on interaction
`annotations`	`List<Annotation>?`	Static annotations
`selections`	`Map<String, Selection>?`	Named selection behaviors
`transforms`	`List<VariableTransform>?`	Data transforms (filter, sort, proportion)
`padding`	`EdgeInsets Function(Size)?`	Padding around the plot area
`transition`	—	Set on each Mark, not on Chart

See

references/chart-widget.md

for full parameter details.

Chart<D>

是唯一对外公开的组件，类型参数

是数据项的类型。核心参数：

参数	类型	用途
`data`	`List<D>`	必填要可视化的数据
`variables`	`Map<String, Variable<D, dynamic>>`	必填如何从数据中提取值
`marks`	`List<Mark>`	必填要渲染的几何图形类型
`coord`	`Coord?`	坐标系（默认： `RectCoord` ）
`axes`	`List<AxisGuide>?`	坐标轴配置
`tooltip`	`TooltipGuide?`	交互提示框
`crosshair`	`CrosshairGuide?`	交互十字准星
`annotations`	`List<Annotation>?`	静态标注
`selections`	`Map<String, Selection>?`	命名选择行为
`transforms`	`List<VariableTransform>?`	数据转换（过滤、排序、占比计算）
`padding`	`EdgeInsets Function(Size)?`	绘图区域的内边距
`transition`	—	在每个Mark上设置，而非Chart上

完整的参数详情可查看

references/chart-widget.md

。

Variables

变量（Variable）

Variables define how raw data maps to abstract values:

dart

variables: {
  'date': Variable(
    accessor: (MyData d) => d.date,
    scale: TimeScale(formatter: (t) => DateFormat.MMMd().format(t)),
  ),
  'value': Variable(
    accessor: (MyData d) => d.value,
    scale: LinearScale(min: 0),
  ),
}

Each variable can have a

Scale

that controls domain-to-range mapping. See

references/scales.md

变量定义了原始数据如何映射到抽象值：

dart

variables: {
  'date': Variable(
    accessor: (MyData d) => d.date,
    scale: TimeScale(formatter: (t) => DateFormat.MMMd().format(t)),
  ),
  'value': Variable(
    accessor: (MyData d) => d.value,
    scale: LinearScale(min: 0),
  ),
}

每个变量都可以配置

Scale

来控制定义域到值域的映射，详情查看

references/scales.md

。

Marks

标记（Mark）

Marks are the geometric elements that represent data:

Mark	Use Case	Default Shape
`IntervalMark`	Bar charts, histograms, pie charts	`RectShape`
`LineMark`	Line charts, sparklines	`BasicLineShape`
`AreaMark`	Area charts, stream graphs	`BasicAreaShape`
`PointMark`	Scatter plots, bubble charts	`CircleShape`
`PolygonMark`	Heatmaps, treemaps	`HeatmapShape`
`CustomMark`	Candlestick, custom shapes	Any `Shape`

See

references/marks.md

for parameters and

references/shapes.md

for shape options.

标记是代表数据的几何元素：

Mark类型	适用场景	默认形状
`IntervalMark`	柱状图、直方图、饼图	`RectShape`
`LineMark`	折线图、迷你图	`BasicLineShape`
`AreaMark`	面积图、流图	`BasicAreaShape`
`PointMark`	散点图、气泡图	`CircleShape`
`PolygonMark`	热力图、矩形树图	`HeatmapShape`
`CustomMark`	K线图、自定义形状	任意 `Shape`

参数详情查看

references/marks.md

，形状选项查看

references/shapes.md

。

Encodes (Aesthetic Mappings)

编码（视觉映射）

Encodes map data values to visual properties. Every encode supports three modes:

Fixed value:
```
ColorEncode(value: Colors.blue)
```

Variable mapping:

ColorEncode(variable: 'type', values: Defaults.colors10)

Custom function:

ColorEncode(encoder: (tuple) => myColorLogic(tuple))

Available encodes:

ColorEncode

SizeEncode

ShapeEncode

LabelEncode

GradientEncode

ElevationEncode

See

references/encodes.md

for details.

编码将数据值映射到视觉属性，每个编码都支持三种模式：

固定值：
```
ColorEncode(value: Colors.blue)
```

变量映射：

ColorEncode(variable: 'type', values: Defaults.colors10)

自定义函数：

ColorEncode(encoder: (tuple) => myColorLogic(tuple))

可用的编码类型：

ColorEncode

、

SizeEncode

、

ShapeEncode

、

LabelEncode

、

GradientEncode

、

ElevationEncode

。

详情查看

references/encodes.md

。

Position Algebra (Varset)

位置代数（Varset）

Position is specified using

Varset

algebra with three operators:

Operator	Name	Effect
`*`	Cross	Assigns variables to different dimensions (x, y)
`+`	Blend	Combines variables on the same dimension
`/`	Nest	Groups data by a variable

dart

// x=date, y=value, grouped by type
position: Varset('date') * Varset('value') / Varset('type')

See

references/algebra.md

for details.

位置通过

Varset

代数和三个运算符定义：

运算符	名称	作用
`*`	交叉	将变量分配到不同维度（x、y）
`+`	混合	在同一维度上合并变量
`/`	嵌套	按变量对数据分组

dart

// x=日期，y=数值，按类型分组
position: Varset('date') * Varset('value') / Varset('type')

详情查看

references/algebra.md

。

Coordinates

坐标系

RectCoord
— Cartesian coordinates (default). Supports
```
transposed
```
,
```
horizontalRange
```
,
```
verticalRange
```
.
PolarCoord
— Polar/radial coordinates for pie charts, radar charts, rose charts. Supports
```
startAngle
```
,
```
endAngle
```
,
```
startRadius
```
,
```
endRadius
```
.

See

references/coordinates.md

for details.

RectCoord
—— 笛卡尔坐标系（默认），支持
```
transposed
```
（转置）、
```
horizontalRange
```
（水平范围）、
```
verticalRange
```
（垂直范围）配置。
PolarCoord
—— 极坐标系，用于饼图、雷达图、玫瑰图，支持
```
startAngle
```
（起始角度）、
```
endAngle
```
（结束角度）、
```
startRadius
```
（起始半径）、
```
endRadius
```
（结束半径）配置。

详情查看

references/coordinates.md

。

Interaction

交互

Define named selections and use them in encode updaters:

dart

selections: {
  'tap': PointSelection(dim: Dim.x),
},
marks: [
  IntervalMark(
    color: ColorEncode(
      value: Colors.blue,
      updaters: {
        'tap': {
          true: (color) => color.withAlpha(255),   // selected
          false: (color) => color.withAlpha(100),  // not selected
        },
      },
    ),
  ),
],

See

references/selections.md

for selection types and gesture configuration.

定义命名选择器并在编码更新器中使用：

dart

selections: {
  'tap': PointSelection(dim: Dim.x),
},
marks: [
  IntervalMark(
    color: ColorEncode(
      value: Colors.blue,
      updaters: {
        'tap': {
          true: (color) => color.withAlpha(255),   // 选中状态
          false: (color) => color.withAlpha(100),  // 未选中状态
        },
      },
    ),
  ),
],

选择器类型和手势配置详情查看

references/selections.md

。

Modifiers

修饰器

Modifiers handle geometry collision/arrangement:

```
StackModifier()
```
— Stack elements (stacked bar, stacked area)
```
DodgeModifier()
```
— Place side by side (grouped bar)
```
JitterModifier()
```
— Random scatter (strip plot)
```
SymmetricModifier()
```
— Center symmetrically (stream graph)

See

references/modifiers.md

修饰器处理几何图形的碰撞/排布：

```
StackModifier()
```
—— 堆叠元素（堆叠柱状图、堆叠面积图）
```
DodgeModifier()
```
—— 并排排布（分组柱状图）
```
JitterModifier()
```
—— 随机散列（带状图）
```
SymmetricModifier()
```
—— 居中对称（流图）

详情查看

references/modifiers.md

。

Animation

动画

dart

IntervalMark(
  transition: Transition(duration: Duration(seconds: 1), curve: Curves.easeOut),
  entrance: {MarkEntrance.y},  // Animate from y=0
  tag: (tuple) => tuple['id'].toString(),  // Element matching for transitions
)

See

references/animation.md

dart

IntervalMark(
  transition: Transition(duration: Duration(seconds: 1), curve: Curves.easeOut),
  entrance: {MarkEntrance.y},  // 从y=0位置开始动画
  tag: (tuple) => tuple['id'].toString(),  // 过渡动画的元素匹配标识
)

详情查看

references/animation.md

。

Common Chart Recipes

常见图表示例

Bar Chart

柱状图

dart

marks: [IntervalMark()]
coord: RectCoord()  // default

dart

marks: [IntervalMark()]
coord: RectCoord()  // 默认

Horizontal Bar Chart

横向柱状图

dart

marks: [IntervalMark()]
coord: RectCoord(transposed: true)

dart

marks: [IntervalMark()]
coord: RectCoord(transposed: true)

Grouped Bar Chart

分组柱状图

dart

marks: [
  IntervalMark(
    position: Varset('x') * Varset('y') / Varset('group'),
    color: ColorEncode(variable: 'group', values: Defaults.colors10),
    modifiers: [DodgeModifier()],
  ),
]

dart

marks: [
  IntervalMark(
    position: Varset('x') * Varset('y') / Varset('group'),
    color: ColorEncode(variable: 'group', values: Defaults.colors10),
    modifiers: [DodgeModifier()],
  ),
]

Stacked Bar Chart

堆叠柱状图

dart

marks: [
  IntervalMark(
    position: Varset('x') * Varset('y') / Varset('group'),
    color: ColorEncode(variable: 'group', values: Defaults.colors10),
    modifiers: [StackModifier()],
  ),
]

dart

marks: [
  IntervalMark(
    position: Varset('x') * Varset('y') / Varset('group'),
    color: ColorEncode(variable: 'group', values: Defaults.colors10),
    modifiers: [StackModifier()],
  ),
]

Line Chart

折线图

dart

marks: [LineMark()]

dart

marks: [LineMark()]

Smooth Line Chart

平滑折线图

dart

marks: [
  LineMark(shape: ShapeEncode(value: BasicLineShape(smooth: true))),
]

dart

marks: [
  LineMark(shape: ShapeEncode(value: BasicLineShape(smooth: true))),
]

Area Chart

面积图

dart

marks: [AreaMark()]

dart

marks: [AreaMark()]

Pie Chart

饼图

dart

transforms: [Proportion(variable: 'value', as: 'percent')],
marks: [
  IntervalMark(
    position: Varset('percent') / Varset('category'),
    color: ColorEncode(variable: 'category', values: Defaults.colors10),
    modifiers: [StackModifier()],
  ),
],
coord: PolarCoord(transposed: true, dimCount: 1),

dart

transforms: [Proportion(variable: 'value', as: 'percent')],
marks: [
  IntervalMark(
    position: Varset('percent') / Varset('category'),
    color: ColorEncode(variable: 'category', values: Defaults.colors10),
    modifiers: [StackModifier()],
  ),
],
coord: PolarCoord(transposed: true, dimCount: 1),

Scatter Plot

散点图

dart

marks: [
  PointMark(
    size: SizeEncode(variable: 'magnitude', values: [2, 20]),
    color: ColorEncode(variable: 'type', values: Defaults.colors10),
  ),
]

dart

marks: [
  PointMark(
    size: SizeEncode(variable: 'magnitude', values: [2, 20]),
    color: ColorEncode(variable: 'type', values: Defaults.colors10),
  ),
]

Rose Chart

玫瑰图

dart

marks: [IntervalMark(color: ColorEncode(variable: 'name', values: Defaults.colors10))],
coord: PolarCoord(startRadius: 0.15),

See

references/examples.md

for more complete examples.

dart

marks: [IntervalMark(color: ColorEncode(variable: 'name', values: Defaults.colors10))],
coord: PolarCoord(startRadius: 0.15),

更多完整示例可查看

references/examples.md

。

Custom Chart Development

自定义图表开发

Graphic's greatest strength is its fully customizable rendering pipeline. When standard chart types don't meet requirements, create custom visualizations by implementing your own shapes, tooltips, annotations, and encoders.

Graphic最大的优势是其完全可自定义的渲染管线。当标准图表类型无法满足需求时，可以通过实现自定义形状、提示框、标注和编码器来创建自定义可视化内容。

Custom Shapes — The Core Extension Point

自定义形状——核心扩展点

Create entirely new chart geometries by extending a Shape base class and implementing

drawGroupPrimitives()

dart

class LollipopShape extends IntervalShape {
  LollipopShape({this.radius = 6});
  final double radius;

  @override
  List<MarkElement> drawGroupPrimitives(
    List<Attributes> group, CoordConv coord, Offset origin,
  ) {
    final rst = <MarkElement>[];
    for (var item in group) {
      if (item.position.any((p) => !p.dy.isFinite)) continue;
      final style = getPaintStyle(item, false, 0, null, null);
      final base = coord.convert(item.position[0]);
      final tip = coord.convert(item.position[1]);

      // Stem line
      rst.add(PolylineElement(
        points: [base, tip],
        style: PaintStyle(strokeColor: style.fillColor, strokeWidth: 2),
        tag: item.tag,
      ));
      // Circle head
      rst.add(CircleElement(
        center: tip, radius: radius, style: style, tag: item.tag,
      ));
    }
    return rst;
  }

  @override
  bool equalTo(Object other) =>
    other is LollipopShape && radius == other.radius;
}

Available base classes:

IntervalShape

LineShape

AreaShape

PointShape

PolygonShape

Available drawing primitives:

RectElement

CircleElement

PolygonElement

PolylineElement

ArcElement

SectorElement

SplineElement

PathElement

LabelElement

GroupElement

通过继承Shape基类并实现

drawGroupPrimitives()

方法可以创建全新的图表几何图形：

dart

class LollipopShape extends IntervalShape {
  LollipopShape({this.radius = 6});
  final double radius;

  @override
  List<MarkElement> drawGroupPrimitives(
    List<Attributes> group, CoordConv coord, Offset origin,
  ) {
    final rst = <MarkElement>[];
    for (var item in group) {
      if (item.position.any((p) => !p.dy.isFinite)) continue;
      final style = getPaintStyle(item, false, 0, null, null);
      final base = coord.convert(item.position[0]);
      final tip = coord.convert(item.position[1]);

      // 茎线
      rst.add(PolylineElement(
        points: [base, tip],
        style: PaintStyle(strokeColor: style.fillColor, strokeWidth: 2),
        tag: item.tag,
      ));
      // 圆形头部
      rst.add(CircleElement(
        center: tip, radius: radius, style: style, tag: item.tag,
      ));
    }
    return rst;
  }

  @override
  bool equalTo(Object other) =>
    other is LollipopShape && radius == other.radius;
}

可用基类：

IntervalShape

、

LineShape

、

AreaShape

、

PointShape

、

PolygonShape

可用绘制图元：

RectElement

、

CircleElement

、

PolygonElement

、

PolylineElement

、

ArcElement

、

SectorElement

、

SplineElement

、

PathElement

、

LabelElement

、

GroupElement

Custom Tooltip Renderer

自定义提示框渲染器

dart

tooltip: TooltipGuide(
  renderer: (Size size, Offset anchor, Map<int, Tuple> selected) {
    final t = selected.values.first;
    return [
      RectElement(
        rect: Rect.fromCenter(center: anchor, width: 100, height: 36),
        borderRadius: BorderRadius.circular(6),
        style: PaintStyle(fillColor: Colors.black87, elevation: 4),
      ),
      LabelElement(
        text: '${t['name']}: ${t['value']}',
        anchor: anchor,
        style: LabelStyle(
          textStyle: TextStyle(color: Colors.white, fontSize: 12),
          align: Alignment.center,
        ),
      ),
    ];
  },
)

dart

tooltip: TooltipGuide(
  renderer: (Size size, Offset anchor, Map<int, Tuple> selected) {
    final t = selected.values.first;
    return [
      RectElement(
        rect: Rect.fromCenter(center: anchor, width: 100, height: 36),
        borderRadius: BorderRadius.circular(6),
        style: PaintStyle(fillColor: Colors.black87, elevation: 4),
      ),
      LabelElement(
        text: '${t['name']}: ${t['value']}',
        anchor: anchor,
        style: LabelStyle(
          textStyle: TextStyle(color: Colors.white, fontSize: 12),
          align: Alignment.center,
        ),
      ),
    ];
  },
)

Custom Encoder Functions

自定义编码器函数

Every encode supports arbitrary logic via

encoder

dart

color: ColorEncode(encoder: (tuple) {
  final v = tuple['value'] as num;
  return v > 100 ? Colors.red : v > 50 ? Colors.orange : Colors.green;
}),

label: LabelEncode(encoder: (tuple) => Label(
  '${tuple['value']}%',
  LabelStyle(textStyle: TextStyle(
    fontSize: (tuple['value'] as num) > 50 ? 14 : 10,
    fontWeight: FontWeight.bold,
  )),
)),

每个编码都支持通过

encoder

参数实现任意逻辑：

dart

color: ColorEncode(encoder: (tuple) {
  final v = tuple['value'] as num;
  return v > 100 ? Colors.red : v > 50 ? Colors.orange : Colors.green;
}),

label: LabelEncode(encoder: (tuple) => Label(
  '${tuple['value']}%',
  LabelStyle(textStyle: TextStyle(
    fontSize: (tuple['value'] as num) > 50 ? 14 : 10,
    fontWeight: FontWeight.bold,
  )),
)),

Key Classes for Custom Development

自定义开发的核心类

Class	Purpose
`Attributes`	Encoded data element — contains `position` , `color` , `gradient` , `size` , `label` , `tag`
`CoordConv`	Converts normalized [0,1] positions to canvas pixels via `convert()` / `invert()`
`PaintStyle`	Full paint specification — fill, stroke, gradient, dash, elevation, shadow
`MarkElement`	Drawing primitives — the building blocks for custom rendering
`getPaintStyle()`	Utility to extract `PaintStyle` from `Attributes`

See
references/customization.md
for the comprehensive guide including coordinate handling, all drawing primitives, custom annotations, custom modifiers, and best practices.

类名	用途
`Attributes`	编码后的数据元素，包含 `position` 、 `color` 、 `gradient` 、 `size` 、 `label` 、 `tag`
`CoordConv`	通过 `convert()` / `invert()` 方法将归一化的[0,1]位置转换为画布像素坐标
`PaintStyle`	完整的绘制规范——填充、描边、渐变、虚线、 elevation、阴影
`MarkElement`	绘制图元——自定义渲染的基础构建块
`getPaintStyle()`	从 `Attributes` 中提取 `PaintStyle` 的工具方法

完整指南查看
references/customization.md
，包含坐标处理、所有绘制图元、自定义标注、自定义修饰器和最佳实践。

Guides & Annotations

引导组件与标注

Axes: Use

Defaults.horizontalAxis

Defaults.verticalAxis

for quick setup, or customize with

AxisGuide

. See

references/guides.md

Tooltip:
```
TooltipGuide()
```
with optional custom renderer. See
```
references/guides.md
```
.
Crosshair:
```
CrosshairGuide()
```
. See
```
references/guides.md
```
.

Annotations:

LineAnnotation

RegionAnnotation

TagAnnotation

CustomAnnotation

. See

references/annotations.md

坐标轴：使用

Defaults.horizontalAxis

、

Defaults.verticalAxis

快速配置，或通过

AxisGuide

自定义，详情查看

references/guides.md

。

提示框：
```
TooltipGuide()
```
支持可选的自定义渲染器，详情查看
```
references/guides.md
```
。
十字准星：
```
CrosshairGuide()
```
，详情查看
```
references/guides.md
```
。

标注：

LineAnnotation

、

RegionAnnotation

、

TagAnnotation

、

CustomAnnotation

，详情查看

references/annotations.md

。

Styling

样式配置

```
PaintStyle
```
— Fill/stroke colors, gradients, dash patterns, shadows
```
LabelStyle
```
— Text style, alignment, rotation, offset
```
Defaults
```
— Built-in color palettes (
```
colors10
```
,
```
colors20
```
), preset axes, default styles

See

references/styling.md

```
PaintStyle
```
—— 填充/描边颜色、渐变、虚线模式、阴影
```
LabelStyle
```
—— 文本样式、对齐方式、旋转、偏移
```
Defaults
```
—— 内置调色板（
```
colors10
```
、
```
colors20
```
）、预设坐标轴、默认样式

详情查看

references/styling.md

。

Event Streams

事件流

Charts expose

StreamController

parameters for external event coupling:

```
gestureStream
```
— Send/receive gesture events
```
resizeStream
```
— React to resize events
```
changeDataStream
```
— React to data change events
```
selectionStream
```
(on Mark) — Programmatically set selections

图表暴露

StreamController

参数用于外部事件耦合：

```
gestureStream
```
—— 发送/接收手势事件
```
resizeStream
```
—— 响应尺寸变化事件
```
changeDataStream
```
—— 响应数据变化事件
```
selectionStream
```
（Mark上的参数） —— 可编程设置选择状态

Dynamic Data

动态数据

Simply update the

data

parameter via

setState()

dart

setState(() {
  data = newData;
});

The chart automatically re-renders with transition animations when

tag

is set.

只需通过

setState()

更新

data

参数即可：

dart

setState(() {
  data = newData;
});

当设置了

tag

参数时，图表会自动通过过渡动画重新渲染。

Important Notes

注意事项

The
```
Chart
```
widget is the only public widget — all configuration is via its constructor
```
color
```
and
```
gradient
```
on encodes are mutually exclusive

Pie charts require

Proportion

transform +

PolarCoord(transposed: true, dimCount: 1)

Use
```
tag
```
on marks for smooth transition animations between data states
```
Varset
```
```
/
```
(nest) operator is required for grouping (multi-series, stacked, dodged)
Function-typed properties are always treated as "unchanged" in equality comparisons

```
Chart
```
组件是唯一对外公开的组件，所有配置都通过其构造函数完成
编码中的
```
color
```
和
```
gradient
```
互斥

饼图需要

Proportion

转换 +

PolarCoord(transposed: true, dimCount: 1)

配置

在Mark上使用
```
tag
```
可以实现数据状态之间的平滑过渡动画
```
Varset
```
的
```
/
```
（嵌套）运算符是分组必需的（多系列、堆叠、分组排布）
函数类型的属性在相等性比较中始终被视为「未变更」

Reference Files

参考文件

File	Content
`references/customization.md`	Custom chart development guide — shapes, tooltips, annotations, encoders, drawing primitives
`references/chart-widget.md`	Full Chart widget parameter reference
`references/marks.md`	All mark types and parameters
`references/encodes.md`	Aesthetic encoding reference
`references/shapes.md`	Shape types for each mark
`references/scales.md`	Scale types and configuration
`references/coordinates.md`	Coordinate system reference
`references/guides.md`	Axis, Tooltip, Crosshair reference
`references/annotations.md`	Annotation types reference
`references/selections.md`	Selection and interaction reference
`references/modifiers.md`	Geometry modifier reference
`references/transforms.md`	Data transform reference
`references/algebra.md`	Varset algebra reference
`references/animation.md`	Transition and entrance animation reference
`references/styling.md`	PaintStyle, LabelStyle, Defaults reference
`references/examples.md`	Complete chart examples

When answering user questions, read the source code for the most accurate and up-to-date API details. The library uses extensive code comments as documentation. Key source directories:

```
lib/src/chart/
```
— Chart widget
```
lib/src/mark/
```
— Mark types
```
lib/src/encode/
```
— Encode types
```
lib/src/shape/
```
— Shape implementations
```
lib/src/scale/
```
— Scale types
```
lib/src/coord/
```
— Coordinate systems
```
lib/src/guide/
```
— Axis, Tooltip, Crosshair, Annotations
```
lib/src/interaction/
```
— Selection, gestures
```
lib/src/variable/
```
— Variable and transforms
```
lib/src/algebra/
```
— Varset algebra
```
lib/src/common/
```
— Shared types (Label, PaintStyle, Defaults)

文件	内容
`references/customization.md`	自定义图表开发指南 —— 形状、提示框、标注、编码器、绘制图元
`references/chart-widget.md`	Chart组件完整参数参考
`references/marks.md`	所有Mark类型及参数
`references/encodes.md`	视觉编码参考
`references/shapes.md`	每个Mark对应的形状类型
`references/scales.md`	比例尺类型及配置
`references/coordinates.md`	坐标系参考
`references/guides.md`	坐标轴、提示框、十字准星参考
`references/annotations.md`	标注类型参考
`references/selections.md`	选择与交互参考
`references/modifiers.md`	几何修饰器参考
`references/transforms.md`	数据转换参考
`references/algebra.md`	Varset代数参考
`references/animation.md`	过渡与入场动画参考
`references/styling.md`	PaintStyle、LabelStyle、Defaults参考
`references/examples.md`	完整图表示例

回答用户问题时，请阅读源代码获取最准确最新的API详情，库中使用了大量代码注释作为文档。核心源码目录：

```
lib/src/chart/
```
—— Chart组件
```
lib/src/mark/
```
—— Mark类型
```
lib/src/encode/
```
—— 编码类型
```
lib/src/shape/
```
—— 形状实现
```
lib/src/scale/
```
—— 比例尺类型
```
lib/src/coord/
```
—— 坐标系
```
lib/src/guide/
```
—— 坐标轴、提示框、十字准星、标注
```
lib/src/interaction/
```
—— 选择、手势
```
lib/src/variable/
```
—— 变量与转换
```
lib/src/algebra/
```
—— Varset代数
```
lib/src/common/
```
—— 共享类型（Label、PaintStyle、Defaults）