AntV F2入门教程

以下教程将系统地介绍 AntV F2（移动端可视化引擎）的核心 组件 API，包含安装与引入、画布与图表、数据映射、几何标记、坐标轴、图例、提示、标注和滚动条等，每个 API 都附带完整示例代码，帮助你快速掌握 F2 用法。

---

一、安装与引入

# 安装 F2 主包
npm install @antv/f2 --save
# 或者使用 yarn
yarn add @antv/f2

// 在小程序或浏览器中引入
import { Canvas, Chart, Line, Interval, Point, Area, Candlestick, Axis, Legend, Tooltip, Guide, ScrollBar } from '@antv/f2';

---

二、Canvas 与 Chart

2.1 <Canvas>

• Props

  • context：必选，传入小程序或浏览器 Canvas 的绘图上下文
  • pixelRatio：设备像素比，默认为 window.devicePixelRatio
  • width/height：画布尺寸，可选

<Canvas context={ctx} pixelRatio={2} width={375} height={300}>{/* Chart 放在 Canvas 内 */}
</Canvas>

([f2.antv.antgroup.com][1])

2.2 <Chart>

• Props

  • data: any[]：数据源
  • scale?: ScaleOption：度量配置
  • coord?: CoordOption：坐标系配置
  • padding?: number \| [top, right, bottom, left]：内边距
  • animate?: boolean：是否开启动画

const data = [{ type: 'A', value: 30 },{ type: 'B', value: 80 },{ type: 'C', value: 45 },
];<Canvas context={ctx}><Chartdata={data}scale={{ value: { min: 0, max: 100 } }}coord={{ type: 'rect', transposed: false }}padding={[10, 20, 50, 20]}animate={true}>{/* Geoms、Axis、Legend 等放在此 */}</Chart>
</Canvas>

([f2.antv.antgroup.com][1])

---

三、几何标记（Geometry）

所有几何标记均继承通用属性：

• x: string、y: string：映射字段
• color：颜色映射，可为固定值、字段名、数组或对象形式
• size：大小映射，用法同 color
• adjust?: 'stack' | 'dodge' | 'symmetric'：调整方式
• viewClip?: boolean：只显示图表区域内
• animation?: AnimationOption：分阶段动画

([f2.antv.antgroup.com][2])

3.1 折线图 <Line>

<Linex="type"y="value"color="#1890FF"size={2}style={{ lineDash: [4, 2] }}animation={{appear: { duration: 500, easing: 'easeCubicIn' },}}
/>

3.2 柱状图 <Interval>

<Intervalx="type"y="value"color={['type', ['#5B8FF9', '#61DDAA', '#65789B']]}adjust="dodge"
/>

3.3 散点图 <Point>

<Pointx="type"y="value"color="type"size={[ 'value', [4, 10] ]}
/>

3.4 面积图 <Area>

<Areax="type"y="value"color="#FF4D4F"adjust="stack"style={{ opacity: 0.6 }}
/>

3.5 K 线图 <Candlestick>

<Candlestickx="date"y="value"color={{ field: 'trend', range: ['#0f0', '#f00'] }}
/>

([f2.antv.antgroup.com][2])

---

四、坐标轴（Axis）

• Props

  • field: string：数据字段
  • position?: 'top'|'right'|'bottom'|'left'
  • visible?: boolean
  • tickCount?: number
  • formatter?: (val) => string
  • grid?: 'line'|'arc'
  • style?: { label?: TextAttr; line?: LineAttr; tickLine?: { length: number }; grid?: LineAttr }

<Axisfield="type"position="bottom"tickCount={data.length}formatter={val => `类型:${val}`}style={{label: { fill: '#666', fontSize: 10 },tickLine: { length: 4 },grid: { stroke: '#eee' },}}
/>
<Axisfield="value"position="left"formatter={val => `${val} 单位`}nice={true}
/>

([f2.antv.antgroup.com][3])

---

五、图例（Legend）

• Props

  • position?: 'top'|'right'|'bottom'|'left'
  • itemFormatter?: (item) => string
  • marker?: 'circle'|'square'|'line'
  • clickable?: boolean
  • onClick?: (item) => void
  • style?, itemStyle?（Flex 布局）
  • nameStyle?, valueStyle?（TextAttr）

<Legendposition="top"marker="square"itemFormatter={name => name.toUpperCase()}onClick={item => console.log('点击图例', item)}style={{ flexDirection: 'row', justifyContent: 'space-around' }}
/>

([f2.antv.antgroup.com][4])

---

六、提示（Tooltip）

• Props

  • triggerOn?: 'press'|'click'
  • triggerOff?: 'pressend'
  • alwaysShow?: boolean
  • showCrosshairs?: boolean
  • crosshairsType?: 'x'|'y'|'xy'
  • nameStyle?: TextAttr、valueStyle?: TextAttr、background?: RectAttr
  • xTip?: string|((x) => string)、xTipTextStyle?、xTipBackground?
  • showItemMarker?: boolean
  • onChange?: (items) => void

• Methods（通过 ref 调用）

  • show({ x, y })
  • hide()

<TooltiptriggerOn="press"showCrosshairs={true}crosshairsType="xy"nameStyle={{ fontSize: 12, fill: '#333' }}valueStyle={{ fontSize: 12 }}
/>

([f2.antv.antgroup.com][5])

---

七、标注（Guide）

内置 <PointGuide>, <TextGuide>, <TagGuide>, <ImageGuide>, <LineGuide>，用于在图表上添加注解。

7.1 文本标注 <TextGuide>

• Props

  • records: Array<{ [field]: value } \| 'min'|'max'|…>
  • content: string
  • attrs?: ShapeAttr
  • offsetX?: number、offsetY?: number

{data.map(item => (<TextGuiderecords={[item]}content={`${item.value}`}attrs={{ fill: '#000', fontSize: '14px' }}offsetY={-10}/>
))}

([f2.antv.antgroup.com][6])

7.2 其他标注示例

import { PointGuide, TagGuide, LineGuide, ImageGuide } from '@antv/f2';// 点标注
<PointGuide records={[data[0]]} style={{ fill: '#f00' }} />// 标签标注
<TagGuiderecords={[{ type: 'A', value: 30 }]}content="重点"direct="tr"background={{ fill: '#fff' }}
/>// 线标注
<LineGuide records={[{ type: 'min', value: 30 }]} />// 图片标注
<ImageGuiderecords={[{ type: 'C', value: 45 }]}src="https://example.com/icon.png"
/>

---

八、滚动条（ScrollBar）

• Props

  • mode?: 'x'|'y'|['x','y']
  • range?: [0,1]
  • pan?: boolean、pinch?: boolean、autoFit?: boolean
  • visible?: boolean、position?: 'top'|'right'|'bottom'|'left'
  • style?: ShapeProps、background?: ShapeProps、barStyle?: ShapeProps

<ScrollBarmode="x"range={[0, 0.5]}pan={true}pinch={true}position="bottom"style={{ margin: ['8px', 0] }}
/>

([f2.antv.antgroup.com][7])

---

九、小结

1. Canvas & Chart：搭建画布并实例化图表，配置数据、度量、坐标系和动画。
2. Geometry：常用折线、柱状、散点、面积、K 线等标记，支持丰富的数据映射和调整方式。
3. 组件：<Axis>、<Legend>、<Tooltip>、<Guide>、<ScrollBar> 等，灵活配置样式和交互。
4. 扩展：通过 ref 调用组件实例方法（如 Tooltip 的 show/hide）、以及生命周期 API（changeData、render 等）实现动态更新。