F2 与 React 混用时的 TypeScript JSX 类型冲突：定位与解决方案（@antv/f2）

• 数据可视化
• 前端

本文针对 F2 与 React 同时使用时出现的group、circle、rect等 JSX 标签类型报错问题，给出完整的排查思路与两种编译模式下的修复方案。读完本文，你将掌握如何根据项目的tsconfig.json判断 JSX 编译模式，并通过/** @jsx jsx */或/** @jsxImportSource @antv/f2 */注释消除类型冲突，同时理解 F2 标签类型命名空间的底层来源，以及“编译以文件为单位”的边界约束。

问题现象：F2 与 React 共存时标签类型报错

F2 使用声明式 JSX 语法来构建图表（详见 配置 JSX Transform），图表内部大量使用group、circle、rect、text等基础图元标签。当你在一个同时安装并使用了 React 与@antv/f2的项目中编写图表代码时，TypeScript 会对这些标签给出类型提示错误，报错大致指向“类型上不存在属性group/circle/rect”或 JSX 元素类型无法解析。

问题原因：两套 JSX 标签命名空间互相干扰

之所以会报错，是因为 React 的 SVG 标签类型中同样存在circle、rect等标签。React 内置的 JSX 类型声明（React.JSX.IntrinsicElements）与 F2 通过 JSX runtime 定义的图元标签类型发生了冲突：TypeScript 在同一个编译单元内只能依据某个确定的jsxImportSource（Automatic 模式）或jsxFactory（Classic 模式）来解析 JSX 标签，当解析目标落在 React 的命名空间上时，F2 独有的group、circle等标签便无法被识别。

F2 自身的标签类型定义来自@antv/f2对@antv/f-engineJSX runtime 的转发。在仓库中可以看到：

• jsx-runtime.js 内容为export * from '@antv/f-engine/jsx-runtime';
• jsx-runtime.d.ts 内容为export * from '@antv/f-engine/jsx-runtime';
• jsx-dev-runtime.d.ts 同样转发自@antv/f-engine/jsx-dev-runtime

也就是说，@antv/f2包已经为 JSX runtime 模式（Automatic）准备好了独立于 React 的标签命名空间。开发者需要做的是“让 TypeScript 在某一个文件里明确使用 F2 的命名空间”，而不是依赖全局默认的 React 解析。这也正是下面两种解决方式的出发点。

第 1 步：确定当前项目的 JSX 编译模式

在动手修改之前，先打开项目的tsconfig.json，找到compilerOptions下的jsx配置项：

• 若jsx的值为react（或该项未配置，此时默认即react），则项目处于Classic 编译模式；
• 若jsx的值为react-jsx，则项目处于Automatic 编译模式。

两种模式的区别在官方文档 配置 JSX Transform 中有详细说明：

• Classic 模式：每个文件必须显式引入jsx工厂函数（或通过pragma指定），编译时调用jsx(type, props)形式；
• Automatic 模式：编译时自动从jsxImportSource指定的模块导入jsx运行时函数，无需在每个文件手动引入。

在 Babel 一侧，两种模式分别对应@babel/plugin-transform-react-jsx插件的pragma/pragmaFrag配置与runtime: "automatic"/importSource配置；在 TypeScript 一侧，则对应jsxFactory/jsxFragmentFactory与jsx: "react-jsx"/jsxImportSource配置。

第 2 步（Classic 模式）：文件顶部声明 jsx pragma 并引入工厂函数

如果你的项目是 Classic 编译模式（jsx: "react"），在每个用到 F2 图表 JSX 的文件顶部添加如下注释与模块引用：

/** @jsx jsx */ import { jsx } from '@antv/f2';

• /** @jsx jsx */是 TypeScript 支持的 pragma 注释，它告诉编译器：本文件内所有 JSX 都调用jsx函数来创建元素；
• import { jsx } from '@antv/f2'从 F2 包中引入该工厂函数，使类型解析指向 F2 的标签命名空间。

作为佐证，仓库site下的官方示例几乎全部采用这种写法，例如 area.jsx、gradient.jsx 等文件的第一行都是/** @jsx jsx */。

如果你同时使用 Babel 编译，还可以在babel.config.json中全局配置 Classic 模式的 pragma，从而免去逐个文件加注释：

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

对应的 TypeScript 全局配置方式（等价于逐文件@jsx注释）为：

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

第 3 步（Automatic 模式）：文件顶部声明 jsxImportSource

如果你的项目是 Automatic 编译模式（jsx: "react-jsx"），只需在每个用到 F2 图表 JSX 的文件顶部添加一行注释：

/** @jsxImportSource @antv/f2 */

Automatic 模式下，编译器会根据jsxImportSource自动导入jsx/jsxs运行时。将导入源指向@antv/f2后，编译器会从 F2 的 JSX runtime 命名空间解析标签类型，与 React 的 SVG 标签类型不再冲突。

如果你希望全局生效，而不是逐文件加注释，可以在tsconfig.json中配置：

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

Babel 侧的等价配置为：

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

需要注意的是：全局把jsxImportSource设置为@antv/f2会让项目中所有JSX 都按 F2 语义解析，这与 React 项目共存时往往不可取。因此更稳妥的做法是保持全局配置不变（指向 React），仅在 F2 图表代码所在文件顶部添加/** @jsxImportSource @antv/f2 */注释，实现“按文件切换命名空间”。完成上述修改后，重新运行 TypeScript 编译，group、circle、rect等标签的类型错误即消失，代码补全与类型检查恢复正常。

注意事项：编译以文件为单位，同文件不可混用两套标签

一个需要牢记的边界是：代码编译是以文件为单位的，在一个文件里只能使用一种标签类型。

• 对于 Classic 模式，/** @jsx jsx */作用于整个文件；
• 对于 Automatic 模式，/** @jsxImportSource @antv/f2 */同样作用于整个文件。

因此，你不能在同一个文件中既写 React 的div、svg组件，又写 F2 的Chart、Interval等图表 JSX（反之亦然），二者只能取其一。如果业务上确实需要在同一页面混用 React 组件与 F2 图表，标准做法是：将 F2 图表代码拆分到独立的文件中（例如单独的ChartView.jsx），在该文件顶部按上文添加对应注释，React 组件文件保持默认解析即可，通过组件边界实现两套 JSX 命名空间的隔离。

关于 F2 与 React 生态的常规组合方式，可参考 如何在 React 中使用：先安装@antv/f2与@antv/f-react，再通过<Canvas>包裹<Chart>使用，图表内部标签的解析则由上文所述的方式保证。

小结

核心要点一句话总结：F2 的图元标签类型独立于 React 命名空间，通过@jsx或@jsxImportSource注释按文件声明编译目标，即可在同一个 React + TypeScript 项目中安全地使用 F2 的声明式图表 JSX。

• 数据可视化
• 前端