F2 快速上手指南：从安装到绘制第一个声明式移动端图表-开发者社区

数据可视化
前端

【免费下载链接】F2

📱📈An elegant, interactive and flexible charting library for mobile.

项目地址：https://gitcode.com/gh_mirrors/f2/F2

本指南基于 F2 官方快速上手文档，完整讲解移动端图表库 F2 的安装、JSX 转换配置、Canvas 画布创建与声明式图表编写流程。读完本文，你将能够在任意 Web 页面中独立完成一个可交互的 F2 柱状图，并理解Canvas、Chart、Interval、Axis、Tooltip等核心组件的职责与关键属性。

特性介绍

F2（@antv/f2）是面向移动端的数据可视化图表库，自 4.0 起采用声明式方式编写图表，带来了更直观的开发体验：

声明式

声明式编程让图表代码更直观、简洁，避免了复杂的命令式 API 调用。F2 采用 JSX 语法构建图表，不仅上手方便，还可以很方便地与 React、Vue 等前端框架结合（参见框架使用概览）。

组件化

为了构建复杂的可视化图表，组件是不可或缺的能力。F2 参考了 React 的设计模式，内置了一套完善的组件体系，可以简单方便地封装自己的组件。在源码层面，从组件统一出口可以看出，F2 内置了Interval、Line、Area、Point、Axis、Legend、Guide、Tooltip、Treemap、Sunburst、PieLabel、Gauge、Zoom、ScrollBar、Candlestick、Pictorial、Magnifier、ElementLink等一批开箱即用的图表组件，同时每个组件都配套导出withXxx高阶组件与XxxView视图，方便开发者自定义封装。

安装

通过 npm 安装

在项目目录下执行：

npm install @antv/f2 --save

安装完成后，即可在项目中以模块方式引入。当前仓库中@antv/f2包版本为5.14.0（见 packages/f2/package.json），其依赖了@antv/f-engine（渲染引擎）、@antv/util、gl-matrix、d3-cloud（词云）等底层库。

通过 CDN 引入

如果不想使用构建工具，可以直接通过 CDN 引入 UMD 构建产物：

<script src="https://unpkg.com/@antv/f2/dist/index.min.js"></script>

在 packages/f2/package.json 中可以看到unpkg字段指向dist/index.min.js，即该包发布到 npm 后可直接用于 CDN 引用。

配置 JSX 转换

F2 使用 JSX 语法构建图表，因此需要在运行前对 JSX 语法进行编译。Babel 和 TypeScript 都可以编译 JSX，并且都存在Classic（经典）与Automatic（自动）两种编译模式，完整说明见配置 JSX Transform。

注意：如果项目本身已经是 React，可以直接复用 React 的 JSX 运行时，参考如何在 React 中使用 F2。

Babel 配置

首先安装编译插件：

npm install --save-dev @babel/plugin-transform-react-jsx

然后在babel.config.json中按模式配置：

Classic 模式（指定pragma为 F2 的jsx函数）：

{ "plugins": [ [ "@babel/plugin-transform-react-jsx", { "pragma": "jsx", "pragmaFrag": "Fragment" } ] ] }

Automatic 模式（指定运行时与导入来源为@antv/f2）：

{ "plugins": [ [ "@babel/plugin-transform-react-jsx", { "runtime": "automatic", "importSource": "@antv/f2" } ] ] }

TypeScript 配置

在tsconfig.json中同样支持两种模式：

Classic 模式：

{ "compilerOptions": { "jsxFactory": "jsx", "jsxFragmentFactory": "Fragment" } }

Automatic 模式：

{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "@antv/f2" } }

Automatic 模式编译出的 JSX 代码会从@antv/f2/jsx-runtime引入运行时函数。仓库中的 jsx-runtime.js 与 jsx-runtime.d.ts 均透出自@antv/f-engine/jsx-runtime，这正是 Automatic 模式下 JSX 运行时函数的真实来源，保证了@antv/f2可直接作为 JSX 导入源使用。

一分钟上手

下面用最简步骤绘制一张柱状图。

1. 创建 canvas 标签

在页面上放置一个<canvas>元素，宽度与高度即图表画布尺寸：

<canvas id="myChart" width="400" height="260"></canvas>

2. 编写代码

// F2 对数据源格式的要求是 JSON 数组，数组的每个元素是一个标准 JSON 对象 const data = [ { genre: 'Sports', sold: 275 }, { genre: 'Strategy', sold: 115 }, { genre: 'Action', sold: 120 }, { genre: 'Shooter', sold: 350 }, { genre: 'Other', sold: 150 }, ]; // 获取 canvas context const context = document.getElementById('myChart').getContext('2d'); const { props } = ( <Canvas context={context} pixelRatio={window.devicePixelRatio}> <Chart data={data}> <Axis field="genre" /> <Axis field="sold" /> <Interval x="genre" y="sold" color="genre" /> <Tooltip /> </Chart> </Canvas> ); const canvas = new Canvas(props); canvas.render();

完成上述两步之后，保存文件并用浏览器打开，一张柱状图就绘制成功了。整体结构一目了然：Canvas负责画布渲染环境，Chart装载数据，Axis声明坐标轴，Interval绘制柱状几何图形，Tooltip提供数据提示交互。

代码解析

Canvas 画布组件

Canvas是图表的根容器，负责提供渲染环境，其内部维护了渲染引擎实例（@antv/f-engine）并执行render()方法完成绘制：

属性	类型	默认值	说明
`context`	`CanvasRenderingContext2D`	-	必填，Canvas 2D 上下文
`pixelRatio`	`number`	`window.devicePixelRatio`	设备像素比，用于高清屏适配
`width`	`number`	-	画布宽度（优先使用 canvas 元素的 width）
`height`	`number`	-	画布高度（优先使用 canvas 元素的 height）
`animate`	`boolean`	`true`	是否开启动画
`children`	`JSX.Element`	-	通过 JSX 语法创建的 F2 组件节点（如`<Chart />`）

在实际使用中，pixelRatio默认取window.devicePixelRatio，因此在 Retina 等高清屏上也能保证图表清晰。

Chart 图表组件

Chart是图表的核心组件，负责数据处理和坐标转换。从 Chart 源码可以看到，Chart在挂载时会初始化ScaleController（度量控制器）与CoordController（坐标系控制器），并在渲染时把data、coord、layout等上下文通过Children.cloneElement注入给每个子组件：

属性	类型	默认值	说明
`data`	`Data[]`	-	必填，数据源
`scale`	`ScaleConfig`	-	度量配置
`coord`	`CoordConfig`	-	坐标系配置
`children`	`JSX.Element`	-	通过 JSX 语法创建的 F2 组件节点（如`<Interval />`、`<Axis />`等）

除此之外，Chart实例还向开发者暴露了一批实用方法与状态能力（均定义在 packages/f2/src/chart/index.tsx）：

filter(field, condition)：按字段条件过滤图表数据（对应内部_getRenderData实现）；
highlight(field, condition)：高亮符合条件的数据（其余图形透明度降为 0.5）；
setScale(field, option)/getScale(field)/getScales()：动态设置与读取字段度量；
getPosition(record)：把一条数据记录转换为画布上的坐标点；
getSnapRecords(point)：获取某个画布位置附近命中的数据记录（Tooltip 命中检测依赖于此）；
on(eventName, listener)/off(...)：绑定/解绑手势交互事件。

Interval 柱状图组件

Interval用于绘制柱状图，是最常用的几何标记（Geometry）组件之一：

属性	类型	默认值	说明
`x`	`string`	-	必填，x 轴字段名
`y`	`string`	-	必填，y 轴字段名
`color`	`string \\| Function`	-	颜色字段或颜色映射函数

Axis 坐标轴组件

Axis用于配置坐标轴。从 withAxis.tsx 源码可以看出，Axis不仅负责渲染坐标轴线、刻度与标签，还会在构造时把自身的度量配置（type、tickCount、range、mask、formatter、min、max、nice、ticks）通过chart.setScale(field, scaleOption)注册到Chart的度量控制器中——这就是在<Axis>上配置格式化函数、刻度个数等参数能生效的底层原理：

属性	类型	默认值	说明
`field`	`string`	-	必填，字段名
`position`	`string`	-	坐标轴位置（`top`、`bottom`、`left`、`right`）

此外Axis还支持type（度量类型，如cat分类、linear线性、timeCat时间分类）、tickCount（刻度数量）、formatter（刻度文本格式化函数）、min/max（数值范围）、nice（是否自动取整）等度量相关属性。

Tooltip 提示框组件

Tooltip用于显示数据提示信息。当用户在图表上触摸/悬停时，会弹出提示框展示命中的数据详情，其命中检测正是通过Chart的getSnapRecords与几何组件的快照机制完成的。

理解组件组合与更多组件

一个完整的 F2 图表由多个组件声明式组合而成，典型层级为：

Canvas (画布容器) └── Chart (图表核心) ├── Axis (坐标轴) ├── Geometry (几何标记：Interval / Line / Area / Point ...) ├── Tooltip (提示框) ├── Legend (图例) └── Guide (辅助标记)

几何标记的类型决定了图表类型：Interval对应柱状图，Line对应折线图，Area对应面积图，Point对应散点图。更多组件与图表的详细结构、核心术语（坐标轴、图例、几何标记、图形属性、坐标系、提示信息、辅助标记）可参考核心概念。