F2 Chart 图表组件完整指南：坐标系、度量配置、样式与主题定制

• 数据可视化
• 前端

Chart 是 F2 图表库的核心组件，负责创建各类统计图表，并向子组件（几何标记、坐标轴、图例等）统一提供坐标系、度量（scale）和数据过滤能力。本文基于 Chart 官方 API 文档 并结合 Chart 源码 深入讲解其 Props 配置、底层控制器原理与主题机制，读完你可以熟练地在移动端画布中搭建、定制和动态更新任意统计图表。

快速上手：一段声明式图表的骨架

Chart 以 JSX 声明式语法工作，通常作为Canvas的子组件使用，内部再嵌套几何标记组件（如Interval、Line、Area、Point）。文档中的最小示例：

import { Canvas, Chart, Interval } from '@antv/f2'; const data = [ { genre: 'Sports', sold: 5 }, { genre: 'Strategy', sold: 10 }, { genre: 'Action', sold: 20 }, { genre: 'Shooter', sold: 20 }, { genre: 'Other', sold: 40 }, ]; <Canvas context={context}> <Chart data={data}> <Interval x="genre" y="sold" color="genre" /> </Chart> </Canvas>

从 Chart 渲染实现 可以看到，Chart 在render阶段会从数据源读取经过滤后的数据，并把data、chart（当前实例）、layout（布局信息）、coord（坐标系实例）以及scaleOptions注入到每一个子组件中，从而完成整张图表的装配。

TypeScript 泛型：获得完整的类型推断

Chart 是泛型组件，传入自定义数据类型即可让子组件、度量配置获得完整的类型提示与编译期校验：

<Chart<MyDataType> data={data}> ... </Chart>

该泛型约束定义在 ChartProps 与 Data.d.ts 中：ChartProps<TRecord extends DataRecord = DataRecord>，其中DataRecord = Record<string, any>，Data<TRecord> = TRecord[]。测试用例 chart/index.test.tsx 中就以type TRecord = typeof data[0]的方式声明了数据记录类型，并配合Chart<TRecord>、Axis<TRecord>、Interval<TRecord>使用。

Props 总览与类型定义

官方类型定义如下：

interface ChartProps<TRecord extends DataRecord = DataRecord> { /** 数据源，必填 */ data: Data<TRecord>; /** 度量配置 */ scale?: DataRecordScale<TRecord>; /** 坐标系配置 */ coord?: CoordType | CoordProps; /** 图表容器样式 */ style?: GroupStyleProps; /** 主题配置 */ theme?: Record<string, any>; /** 子组件 */ children?: any; } type DataRecord = Record<string, any>; type Data<TRecord> = TRecord[]; type ScaleType = 'identity' | 'linear' | 'cat' | 'timeCat' | 'log' | 'pow'; type CoordType = 'rect' | 'polar';

其中ScaleType与CoordType的完整定义见 Scale.d.ts 和 Coord.d.ts。

data：可视化数据源

必填，类型为对象数组。数据是度量和坐标系计算的基础：Chart 构造时会用new ScaleController(data)创建度量控制器（见 chart/index.tsx）。

数据的变更处理在 willReceiveProps 中：当data引用变化时调用scale.changeData(nextData)重建所有度量；当scale配置变化时调用scale.update(nextScale)增量更新。因此 F2 支持直接在更新阶段替换 data/scale 实现图表刷新，这也是 chart/index.test.tsx 中canvas.update(...)所验证的行为。

scale：度量配置

scale用于定义数据字段的度量类型和配置，是按字段（key 为字段名）组织的对象。未指定type时会根据数据类型自动推断，推断逻辑位于 controller/scale.ts 的 _getType：

• 数值类型 →linear
• 字符串类型 →cat
• 常量字段 →identity

需要说明的是，源码层 F2 通过registerScale注册了cat / category / identity / linear / log / pow / time / timeCat / quantize / quantile多种度量（见 controller/scale.ts），类型定义中的ScaleType是其中最主要的几种。

通用属性

所有度量类型都支持的属性：

linear 度量：连续数值

连续数值类型，type 可省略（默认 linear）：

scale={{ sold: { min: 0, max: 100, nice: true }, }}

源码中 linear 类型默认开启 nice，并在未显式指定 min/max 时用getRange(values)自动计算极值（见 controller/scale.ts）。

cat 度量：分类

分类类型，type 可省略：

scale={{ genre: { values: ['Sports', 'Strategy', 'Action'] }, }}

对 cat 与 timeCat，源码会自动计算输出range：只有一项时居中显示为[0.5, 1]，justifyContent开启时居中分布，否则尾部留出1/count的空隙（见 controller/scale.ts）。

timeCat 度量：时间分类

时间分类类型，通常需要显式声明 type：

scale={{ date: { type: 'timeCat', mask: 'YYYY-MM-DD' }, }}

度量与图表的联动方法

除静态配置外，Chart 实例还暴露了与度量配套的 API（均委托给ScaleController，见 chart/index.tsx）：

• setScale(field, option)：动态设置某字段的度量配置，已创建的度量会随之change更新（见 controller/scale.ts）；
• getScale(field)/getScales()：获取度量实例；
• getXScales()/getYScales()/getColorScales()：按几何标记取各轴向度量。

此外，ScaleController还内置了adjustStartZero（堆叠柱从 0 点对齐）、adjustPieScale（饼图关闭 nice）、_updateStackRange（堆叠场景重算 min/max）等供上层几何组件调用的能力（见 controller/scale.ts）。

度量详细介绍可见：度量教程。

coord：坐标系配置

coord定义图表坐标系，配置会交给CoordController处理（见 controller/coord.ts）：支持字符串'rect' | 'polar'、对象或自定义坐标系构造函数，未指定 type 时默认rect。

rect 直角坐标系

type 可省略（默认为 rect）：

coord={{ transposed: true }}

Rect 实现 将数据空间映射为x: [left, left + width]、y: [top + height, top]的像素区间。

polar 极坐标系

coord={{ type: 'polar', startAngle: -Math.PI / 2, endAngle: Math.PI * 1.5, radius: 0.8, innerRadius: 0.5, }}

Polar 实现 中，默认startAngle = -Math.PI/2、endAngle = (Math.PI*3)/2，radius默认 1、innerRadius默认 0；实际半径取宽高的最小值radiusRatio * (Math.min(width, height) / 2)，极坐标下 x 表示弧度、y 表示半径。transposed会交换 x/y 维度，convertPoint/invertPoint负责像素坐标与数据坐标互转（饼图、玫瑰图的定位即依赖此机制）。

坐标系详细介绍可见：坐标系教程。

坐标系与布局的联动

CoordController的updateLayout会按style中的 padding 计算实际绘图区域（controller/coord.ts）；坐标轴、图例等组件通过layoutCoord/updateCoordFor占位，为周边组件留出空间（见 chart/index.tsx）。从源码结构可以推断，图表区域的实时划分正是由 Chart 协调各子组件的位置布局完成的。

style：图表容器样式

样式属性继承自@antv/g-base的GroupStyleProps，支持数字和字符串单位：

style={{ left: 50, top: 0, width: '100%', height: '100%', padding: ['40px', '40px', '40px', '40px'], }}

Chart 会把style与主题中的theme.chart合并，再经px2hd换算为物理像素（见 chart/index.tsx 的 getStyle）。style变化时willReceiveProps会同步coord.updateLayout重新计算坐标系区域（见 chart/index.tsx）。

theme：主题配置

主题用于覆盖默认主题样式，传入的配置会与默认主题深度合并（Chart 构造时通过deepMix(px2hd(Theme), theme)合并，见 chart/index.tsx）：

theme={{ chart: { padding: ['40px', '40px', '40px', '40px'] }, colors: ['#1890FF', '#2FC25B', '#FACC14'], }}

常用配置项

完整默认主题见 packages/f2/src/theme.ts。从源码可以看到默认主题的完整结构：

• chart.padding默认['30px', '30px', '30px', '30px']（theme.ts）；
• colors默认 8 色：['#1890FF', '#2FC25B', '#FACC14', '#223273', '#8543E0', '#13C2C2', '#3436C7', '#F04864']（theme.ts）；
• 还包含shapes（各几何标记可选形状）、sizes（点大小序列）、shape（各形状默认样式）、axis（坐标轴线/刻度/网格/label 样式）与guide（辅助元素默认样式）等配置块。

进阶：Chart 实例的数据过滤与高亮

除了声明式配置，Chart 实例还提供filter与highlight两个数据交互方法（见 chart/index.tsx）：

// 过滤：只保留满足条件的记录 chart.filter('genre', (value, record) => value === 'Sports'); // 高亮：命中条件的记录正常显示，其余置为半透明 chart.highlight('genre', (value, record) => value === 'Action'); // 清除高亮 chart.highlight('genre', null);

filter的结果会在_getRenderData中逐字段应用于原始数据（chart/index.tsx）；highlight则通过getHighlightStyle为未命中记录附加opacity: 0.5。配合getPosition(record)（数据记录到画布坐标的换算，chart/index.tsx）与getSnapRecords(point)（命中检测，chart/index.tsx），即可实现 tooltip、联动筛选等交互场景。

小结

Chart 是 F2 中"承上启下"的核心组件：向上对接Canvas与数据源，向下为几何标记、坐标轴等子组件提供coord、scale、layout与过滤后的数据。掌握data、scale、coord、style、theme五类 Props 的语义与底层控制器行为，即可在移动端灵活搭建从柱状图、折线图到饼图、玫瑰图、雷达图的各类统计图表，并实现数据动态更新、过滤高亮等交互能力。更多相关参考：坐标系、度量、Axis 坐标轴。

• 数据可视化
• 前端