以下教程將系統地介紹 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 等）實現動態更新。