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}>
  <Chart
    data={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>

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

3.2 柱状图 <Interval>

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

3.3 散点图 <Point>

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

3.4 面积图 <Area>

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

3.5 K 线图 <Candlestick>

<Candlestick
  x="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 }

<Axis
  field="type"
  position="bottom"
  tickCount={data.length}
  formatter={val => `类型:${val}`}
  style={{
    label: { fill: '#666', fontSize: 10 },
    tickLine: { length: 4 },
    grid: { stroke: '#eee' },
  }}
/>
<Axis
  field="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）

<Legend
  position="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()

<Tooltip
  triggerOn="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 => (
  <TextGuide
    records={[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' }} />

// 标签标注
<TagGuide
  records={[{ type: 'A', value: 30 }]}
  content="重点"
  direct="tr"
  background={{ fill: '#fff' }}
/>

// 线标注
<LineGuide records={[{ type: 'min', value: 30 }]} />

// 图片标注
<ImageGuide
  records={[{ 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

<ScrollBar
  mode="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 等）实现动态更新。