@zero-bits/taro-f2-canvas

基于 @antv/f2 封装的 Taro 图表组件，同时支持 H5 和微信小程序。

特性

• 同一套代码，H5 / 微信小程序双端适配
• 基于 @antv/f2 4.0.51，支持折线、柱状、饼图等全部图表类型
• 通过 ref 暴露 update() 方法，支持命令式强制刷新
• 内置 F2 equal() diff 优化，数据未变时不重绘，性能友好
• 小程序端完整桥接触摸事件，Tooltip / 交互手势开箱即用

安装

# npm
npm install @zero-bits/taro-f2-canvas @antv/f2

# pnpm
pnpm add @zero-bits/taro-f2-canvas @antv/f2

@antv/f2 为 peerDependency，版本需固定为 4.0.51。

快速上手

import React, { useRef } from 'react'
import { Chart, Line, Axis, Tooltip } from '@antv/f2'
import { F2Canvas } from '@zero-bits/taro-f2-canvas'
import type { F2RenderContext, F2CanvasInstance } from '@zero-bits/taro-f2-canvas'

const data = [
  { date: '2024-01', value: 30 },
  { date: '2024-02', value: 50 },
  { date: '2024-03', value: 40 },
  { date: '2024-04', value: 80 },
]

export default function Demo() {
  const canvasRef = useRef<F2CanvasInstance>(null)

  const render = ({ context, pixelRatio, width, height }: F2RenderContext) => (
    <Chart data={data} context={context} pixelRatio={pixelRatio} width={width} height={height}>
      <Axis field="date" />
      <Axis field="value" />
      <Line x="date" y="value" />
      <Tooltip />
    </Chart>
  )

  return (
    <F2Canvas
      ref={canvasRef}
      style={{ height: '300px' }}
      render={render}
    />
  )
}

API

F2CanvasProps

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | render | (ctx: F2RenderContext) => unknown | ✅ | 图表渲染函数，返回 F2 JSX 元素树 | | style | CSSProperties | — | 外层容器样式 | | className | string | — | 外层容器类名 | | onInit | (canvasEl: F2CanvasElement) => void | — | Canvas 初始化完成后的回调 | | onDestroy | () => void | — | 组件销毁时的回调 |

F2CanvasInstance（ref）

通过 ref 获取组件实例，可调用以下方法：

| 方法 | 说明 | |------|------| | update() | 主动触发图表重绘，适用于命令式更新场景 |

F2RenderContext

render 函数接收的上下文对象：

| 属性 | 类型 | 说明 | |------|------|------| | context | CanvasRenderingContext2D | Canvas 2D 渲染上下文 | | pixelRatio | number | 设备像素比（DPR） | | width | number | Canvas 宽度（逻辑像素） | | height | number | Canvas 高度（逻辑像素） | | createImage | () => any | 创建图片对象（仅小程序端提供） |

F2CanvasElement

onInit 回调中接收的底层 Canvas 元素接口：

| 成员 | 类型 | 说明 | |------|------|------| | width | number | 元素宽度 | | height | number | 元素高度 | | dispatchEvent | (type, e) => void | 触发事件 | | addEventListener | (type, listener) => void | 添加事件监听 | | removeEventListener | (type, listener) => void | 移除事件监听 | | getBoundingClientRect | () => { top, right, bottom, left } | 获取元素位置 |

数据更新

render 函数每次渲染都会执行，F2 内部通过 equal() 做深比较，数据未变时不会重绘，无需担心性能问题。

当需要命令式强制更新时，使用 ref.current.update()：

const canvasRef = useRef<F2CanvasInstance>(null)

// 某个操作后强制刷新
canvasRef.current?.update()

事件交互（Tooltip / 手势）

组件已自动完成事件桥接，无需额外配置。

• H5：由浏览器原生触摸事件驱动，F2 自动绑定
• 小程序：onTouchStart / onTouchMove / onTouchEnd / onTouchCancel 完整透传至 F2 事件系统

// 直接在 render 里使用 Tooltip，事件自动工作
const render = ({ context, pixelRatio, width, height }: F2RenderContext) => (
  <Chart data={data} context={context} pixelRatio={pixelRatio} width={width} height={height}>
    <Line x="date" y="value" />
    <Tooltip />
  </Chart>
)

注意事项

• 组件容器需有明确的宽高，建议通过 style 传入 height，宽度默认 100%
• 小程序端 Canvas 节点的获取存在时序问题，组件内部已做 nextTick + setTimeout 处理及最多 20 次重试
• 构建产物经过代码混淆，lib/ 为 CommonJS，es/ 为 ES Module

依赖版本

| 依赖 | 版本要求 | |------|----------| | react | >=18.0.0 | | @tarojs/taro | >=4.2.1 | | @tarojs/components | >=4.2.1 | | @antv/f2 | =4.0.51 |

License

MIT