VChart 按需加载教程

快速上手

@visactor/vchart 默认提供的是 VChart 所有的图表和组件，如果你不想引入所有组件，也可以按需引入相关的组件。使用示例如下：

// 引入 VChart 核心模块
import { VChart } from '@visactor/vchart';
// 引入柱状图
import { registerBarChart } from '@visactor/vchart';
// 引入坐标轴、提示信息、十字准星组件
import { registerTooltip, registerCartesianCrossHair, registerDomTooltipHandler } from '@visactor/vchart';

// 注册柱状图和组件
VChart.useRegisters([registerBarChart, registerTooltip, registerDomTooltipHandler, registerCartesianCrossHair]);

如果你的项目中关闭了打包软件的 tree-shaking 优化，则需要手动引入内部文件 @visactor/vchart/esm/xxx，如@visactor/vchart/esm/core或@visactor/vchart/esm/component等，使用方法如下所示：

// 引入 VChart 核心模块
import { VChart } from '@visactor/vchart/esm/core';
// 引入柱状图
import { registerBarChart } from '@visactor/vchart/esm/chart';
// 引入坐标轴、Tooltip、CrossHair组件
import { registerTooltip, registerCartesianCrossHair } from '@visactor/vchart/esm/component';
// 引入 Dom tooltip 逻辑
import { registerDomTooltipHandler } from '@visactor/vchart/esm/plugin';
// 引入微信小程序环境代码
import { registerWXEnv } from '@visactor/vchart/esm/env';

// 注册图表和组件
VChart.useRegisters([
  registerBarChart,
  registerTooltip,
  registerCartesianCrossHair,
  registerDomTooltipHandler,
  registerWXEnv
]);

如何使用

当你通过下面的方式引入 VChart，得到的是一个只有核心逻辑，不包含任何图表、组件、插件、环境兼容的对象。用户需要手动引入相关图表、组件，并进行注册。

import { VChart } from '@visactor/vchart'

可以的选择注册内容通常包括：

图表类型
组件
插件（媒体查询、格式化等）
交互（选中、悬浮等）
环境兼容（Lynx、微信小程序、飞书小程序的环境兼容）

通常来说，除了注册图表类型以外，还需要注册必要的组件。例如在折线图中，坐标轴（连续轴和离散轴）是必不可少的，如果不注册，图表将无法绘制。

这篇文的将尽可能详细地说明组件引入的规则。

如何引入图表

VChart 目前支持 20+ 种图表类型，可以通过如下方式引入：

import { registerBarChart } from '@visactor/vchart;

如何引入组合图表

组合图是指图表配置中 type: 'common' 的图表，通常使用多个数据系列和多个视觉元素，如折线系列、柱状系列、面积系列、散点系列、饼系列等，以呈现各种类型的数据。最常用于绘制双轴图、柱线组合图，详细介绍可以参考组合图教程。

按需引入时，需要引入 Common 图表，同时按需注册将要用到的系列：

import { registerCommonChart, registerBarSeries, registerLineSeries } from '@visactor/vchart';

VChart.useRegisters([registerCommonChart, registerBarSeries, registerLineSeries]);

系列注册方法列表，请参考文末附录一。

如何引入组件

用户可以通过教程文档中的图表概念相关内容，了解在图表中，各个功能组件的名词和形式，从而更好地选择所需的组件。

对于下列笛卡尔坐标系图表而言，默认引入了直角坐标系坐标轴，用于数据到图形位置的映射计算。

折线图、面积图、柱状图/条形图、直方图、散点图、热力图、箱型图、瀑布图、区间柱状图、区间面积图、条形进度图

通常，连续轴（registerCartesianLinearAxis）和离散轴（registerCartesianBandAxis）足以满足大部分需求。如果你需要使用到对数轴（registerCartesianLogAxis）、时间轴（registerCartesianTimeAxis），则需要手动注册。

import { registerCartesianTimeAxis, registerCartesianLogAxis } from '@visactor/vchart';

VChart.useRegisters([registerCartesianTimeAxis, registerCartesianLogAxis]);

对于下列极坐标系图表而言，默认引了入极坐标系坐标轴。

雷达图、玫瑰图、仪表盘图、环形进度图、嵌套圆图

其他组件及其注册方法可以文末附录二。

补充说明：自定义图元组件

自定义图元组件，即图表配置项中的 customMark 和 extensionMark 项，通常用于绘制补充注解，用法可以参考自定义图元示例。

VChart 提供了 10+ 种自定义图元，在按需加载的模式下，为了尽可能减少冗余打包，图元需要手动注册。例如：

import { registerTextMark, registerImageMark } from '@visactor/vchart';

VChart.useRegisters([registerTextMark, registerImageMark]);

当然，我们也提供了注册所有图元的方法，请酌情使用：

import { registerAllMarks } from '@visactor/vchart';

VChart.useRegisters([registerAllMarks]);

具体的图元及其注册方法列表请参考文末附录三。

如何引入插件

以媒体查询器为例，可以通过如下方式引入：

import { registerMediaQuery } from '@visactor/vchart';

react-vchart 按需加载

React-VChart 本身代码都支持按需加载，当需要 VChart 按需加载的时候，有两种办法：

使用 <VChartSimple /> 标签，实现自定义的按需加载

<VChartSimple />组件和<VChart />组件使用方法基本完全相同，唯一差异点为，需要用户从 @viasctor/vchart 引用 VChart 构造类，并传入给 <VChartSimple />;

interface VChartSimpleProps extends EventsProps {
  /** 图表定义 */
  spec: any;
  /** 图表配置 */
  options?: ChartOptions;
  /** 图表渲染完成事件 */
  onReady?: (instance: VChart, isInitial: boolean) => void;
  /** throw error when chart run into an error */
  onError?: (err: Error) => void;
  /**
   * 切换到同步渲染
   *
   * @since 1.8.3
   **/
  useSyncRender?: boolean;
  /**
   * props更新的时候，跳过所有函数的检查，即所有的函数都认为没有更新
   *
   * @since 1.6.5
   **/
  skipFunctionDiff?: boolean;
  /**
   * VChart构造类
   *
   * @since 1.8.3
   **/
  vchartConstructor: IVChartConstructor;
}

使用语义化标签，自1.11.0版本，所有的语义化标签默认支持按需加载，其中各种语义化标签默认注册的内容如下：

图表	分类	额外注册的组件
`<LineChart/>`	直角坐标系图表	`registerLabel`
`<AreaChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<BarChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<Bar3dChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<BoxPlotChart/>`	直角坐标系图表	`registerLabel`,
`<HeatmapChart/>`	直角坐标系图表	`registerLabel`
`<Histogram3dChart/>`	直角坐标系图表	`registerLabel`
`<HistogramChart/>`	直角坐标系图表	`registerLabel`
`<LinearProgressChart/>`	直角坐标系图表	`registerLabel`
`<RangeColumnChart/>`	直角坐标系图表	`registerLabel`
`<RangeColumn3dChart/>`	直角坐标系图表	`registerLabel`
`<ScatterChart/>`	直角坐标系图表	`registerLabel`
`<SequenceChart/>`	直角坐标系图表	`registerLabel`
`<WaterfallChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<RadarChart/>`	极坐标系图表	`registerLabel`
`<RoseChart/>`	极坐标系图表	`registerLabel`
`<CircularProgressChart/>`	极坐标系图表	`registerLabel`, `registerIndicator`
`<Pie3dChart/>`	通用图表	`registerLabel`, `registerIndicator`
`<PieChart/>`	通用图表	`registerLabel`, `registerIndicator`
`<CirclePackingChart/>`	通用图表	无
`<FunnelChart/>`	通用图表	`registerLabel`
`<Funnel3dChart/>`	通用图表	`registerLabel`
`<GaugeChart/>`	通用图表	无
`<MapChart/>`	通用图表	`registerLabel`
`<SankeyChart/>`	通用图表	无
`<SunburstChart/>`	通用图表	无
`<TreemapChart/>`	通用图表	无
`<VennChart/>`	通用图表	无
`<WordCloud3dChart/>`	通用图表	无
`<WordCloudChart/>`	通用图表	无
`<LiquidChart/>`	通用图表	`registerIndicator`

其中，直角坐标系图表默认注册组件如下：

registerCartesianLinearAxis
registerCartesianBandAxis
registerCartesianTimeAxis
registerCartesianLogAxis
registerCartesianCrossHair
registerBrush
registerContinuousLegend
registerDataZoom
registerDiscreteLegend
registerCustomMark
registerAllMarks
registerMarkArea
registerMarkLine
registerMarkPoint
registerScrollBar
registerTitle
registerTooltip
registerDomTooltipHandler

极坐标系图表默认注册组件如下：

registerPolarLinearAxis
registerPolarBandAxis
registerPolarCrossHair
registerBrush
registerContinuousLegend
registerDataZoom
registerDiscreteLegend
registerCustomMark
registerAllMarks
registerScrollBar
registerTitle
registerTooltip
registerDomTooltipHandler

通用图表默认注册组件如下：

registerDiscreteLegend
registerContinuousLegend
registerCustomMark
registerAllMarks
registerTitle
registerTooltip
registerDomTooltipHandler

使用语义化标签的时候，如果用到其他没有默认加载的组件，只需要注册未加载的组件即可；

也可以参考react-vchart 教程中的按需加载章节

taro-vchart 按需加载

taro-VChart 本身代码都支持按需加载，当需要 VChart 按需加载的时候，有两种办法：

使用 <VChartSimple /> 标签，实现自定义的按需加载

自1.10.0版本开始支持

<VChartSimple />组件和<VChart />组件使用方法基本完全相同，唯一差异点为，需要用户从 @viasctor/vchart/esm/core 引用 VChart 构造类，根据本文描述，注册需要的图表和组件，并传入给 <VChartSimple />;

使用语义化标签，，所有的语义化标签默认支持按需加载，其中各种语义化标签默认注册的内容如下：

自1.12.0版本开始支持

图表	分类	额外注册的组件
`<LineChart/>`	直角坐标系图表	`registerLabel`
`<AreaChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<BarChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<Bar3dChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<BoxPlotChart/>`	直角坐标系图表	`registerLabel`,
`<HeatmapChart/>`	直角坐标系图表	`registerLabel`
`<Histogram3dChart/>`	直角坐标系图表	`registerLabel`
`<HistogramChart/>`	直角坐标系图表	`registerLabel`
`<LinearProgressChart/>`	直角坐标系图表	`registerLabel`
`<RangeColumnChart/>`	直角坐标系图表	`registerLabel`
`<RangeColumn3dChart/>`	直角坐标系图表	`registerLabel`
`<ScatterChart/>`	直角坐标系图表	`registerLabel`
`<SequenceChart/>`	直角坐标系图表	`registerLabel`
`<WaterfallChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<RadarChart/>`	极坐标系图表	`registerLabel`
`<RoseChart/>`	极坐标系图表	`registerLabel`
`<CircularProgressChart/>`	极坐标系图表	`registerLabel`, `registerIndicator`
`<Pie3dChart/>`	通用图表	`registerLabel`, `registerIndicator`
`<PieChart/>`	通用图表	`registerLabel`, `registerIndicator`
`<CirclePackingChart/>`	通用图表	无
`<FunnelChart/>`	通用图表	`registerLabel`
`<Funnel3dChart/>`	通用图表	`registerLabel`
`<GaugeChart/>`	通用图表	无
`<MapChart/>`	通用图表	`registerLabel`
`<SankeyChart/>`	通用图表	无
`<SunburstChart/>`	通用图表	无
`<TreemapChart/>`	通用图表	无
`<VennChart/>`	通用图表	无
`<WordCloud3dChart/>`	通用图表	无
`<WordCloudChart/>`	通用图表	无
`<LiquidChart/>`	通用图表	`registerIndicator`

其中，直角坐标系图表默认注册组件如下：

registerCartesianLinearAxis
registerCartesianBandAxis
registerCartesianTimeAxis
registerCartesianLogAxis
registerCartesianCrossHair
registerBrush
registerContinuousLegend
registerDataZoom
registerDiscreteLegend
registerCustomMark
registerAllMarks
registerMarkArea
registerMarkLine
registerMarkPoint
registerScrollBar
registerCanvasTooltipHandler
registerTitle

极坐标系图表默认注册组件如下：

registerPolarLinearAxis
registerPolarBandAxis
registerPolarCrossHair
registerBrush
registerContinuousLegend
registerDataZoom
registerDiscreteLegend
registerCustomMark
registerAllMarks
registerScrollBar
registerCanvasTooltipHandler
registerTitle

通用图表默认注册组件如下：

registerDiscreteLegend
registerContinuousLegend
registerCustomMark
registerAllMarks
registerTitle
registerTooltip
registerCanvasTooltipHandler

使用语义化标签的时候，如果用到其他没有默认加载的组件，只需要注册未加载的组件即可；

也可以参考taro-vchart 教程中的按需加载章节

跨端

VChart 默认对浏览器和 node 环境提供了支持。如果你的项目需要运行在小程序环境下，按需加载时，请注意引入小程序环境代码。例如，在微信小程序中使用时，需要调用 registerWXEnv：

import { registerWXEnv } from '@visactor/vchart';
VChart.useRegisters([registerWXEnv]);

目前 VChart 支持的环境兼容注册器包括：

环境	组件注册方法
浏览器	`registerBrowserEnv`
Node	`registerNodeEnv`
微信小程序	`registerWXEnv`
飞书小程序	`registerLarkEnv`
Lynx	`registerLynxEnv`
以上所有	`registerAllEnv`

常见问题

开发环境按需加载不起作用？

开发环境并未做 tree-shaking 处理，以下按需导入等同于import VChart from '@visactor/vchart'全量导入

但需注意，当打包编译时将会开启 tree-shaking，如缺少必要组件导入，项目运行将会报错！

// 引入 VChart 核心模块
import { VChart } from '@visactor/vchart';
// 引入柱状图
import { registerBarChart } from '@visactor/vchart';
// 引入坐标轴、提示信息、十字准星组件
import { registerTooltip, registerCartesianCrossHair, registerDomTooltipHandler } from '@visactor/vchart';
// 注册柱状图和组件
VChart.useRegisters([registerBarChart, registerTooltip, registerDomTooltipHandler, registerCartesianCrossHair]);

NuxtJs 开发环境使用正常，打包后报错如何解决？

在 NuxtJs 中按需加载需要在nuxt.config.ts中进行如下配置，否则将会出现不支持 CommonJS 导入的错误

// nuxt.config.ts
export default defineNuxtConfig({
  build: {
    transpile: [
      // ...
      /visactor/
    ]
  }
});

附录一：系列注册方法列表

系列	系列注册方法
柱系列	`registerBarSeries`
面积系列	`registerAreaSeries`
线系列	`registerLineSeries`
散点系列	`registerScatterSeries`
饼系列	`registerPieSeries`
地图系列	`registerMapSeries`
雷达图系列	`registerRadarSeries`
条形进度图系列	`registerLinearProgressSeries`
箱型图系列	`registerBoxplotSeries`
热力图系列	`registerHeatmapSeries`
区间面积图系列	`registerRangeAreaSeries`
区间柱图系列	`registerRangeColumnSeries`
瀑布图系列	`registerWaterfallSeries`
时序图点系列	`registerDotSeries`
时序图连线系列	`registerLinkSeries`
漏斗图系列	`registerFunnelSeries`
仪表盘系列	`registerGaugeSeries`
玫瑰图系列	`registerRoseSeries`
环形进度图系列	`registerCircularProgressSeries`
仪表图指针系列	`registerGaugePointerSeries`
桑基图系列	`registerSankeySeries`
矩形树图系列	`registerTreemapSeries`
词云系列	`registerWordCloudSeries`
圆嵌套图系列	`registerCirclePackingSeries`
3d 柱系列	`registerBar3dSeries`
3d 漏斗系列	`registerFunnel3dSeries`
3d 饼系列	`registerPie3dSeries`
3d 区间柱系列	`registerRangeColumn3dSeries`
3d 词云系列	`registerWordCloud3dSeries`

附录二：组件注册方法列表

组件	组件注册方法	实际场景示意
离散图例	`registerDiscreteLegend`
连续图例	`registerContinuousLegend`
提示信息	`registerTooltip`	Tooltip 包括 canvas 和 dom 两种绘制方式：通常在浏览器环境下，需要注册`registerDomTooltipHandler` 在小程序、node等非浏览器环境下，需要注册`registerCanvasTooltipHandler`
十字准星（直角坐标系）	`registerCartesianCrossHair`
十字准星（极坐标系）	`registerPolarCrossHair`
缩略轴	`registerDataZoom`
滚动条	`registerScrollBar`
标签	`registerLabel`
指标卡	`registerIndicator`	常用于饼图、仪表盘图的数值指标卡展示。
标题	`registerTitle`
标注线	`registerMarkLine`
标注点	`registerMarkPoint`
标注区域	`registerMarkArea`
总计标签	`registerTotalLabel`	通常用于堆叠图表，显示堆叠总和。
框选	`registerBrush`
自定义图元	`registerCustomMark`	提供自定义绘图的扩展能力。在按需加载的使用方式下，需要手动注册用到的图元。例如，如果用到文本，则需要注册 text 图元：`registerTextMark` 下面的教程会详细列举出各图元类型。
播放器	`registerPlayer`

附录三：图元注册方法列表

图元	图元注册方法	实际场景示意
符号	`registerSymbolMark`	符号图元用于绘制特定图形，如圆、矩形等。支持: 1. 内置形状，请参考使用示例 2. svg path
文本	`registerTextMark`	文本图元支持常规文本和富文本 1. 常规文本 2. 富文本，请参考使用示例
矩形	`registerRectMark`	矩形图元用于绘制矩形，可以用来创建柱状图等可视化效果，请参考使用示例
图像	`registerImageMark`	图像图元用于在视化场景中插入图片，可以用来创建背景、图标等可视化效果，请参考使用示例
多边形	`registerPolygonMark`	多边形图元用于绘制（非闭合）多边形，可以用来创建漏斗图、凸包等可视化效果，请参考使用示例
弧形	`registerArcMark`	弧形图元用于绘制圆弧，可以用来创建饼图、环形图等可视化效果。请参考使用示例
分组	`registerGroupMark`	分组图元用于对多个图元进行收拢，以便对其进行统一操作，如缩放、平移等。需要注意的是，分组图元与其他基础图元不同，并不支持数据映射，请参考使用示例。
线	`registerLineMark`	线图元用于绘制折线，可以用来创建折线图等可视化效果。
连线	`registerRuleMark`	主要是用于展示直线，最简单的使用场景就是用于图表中的辅助线的展示。
面积	`registerAreaMark`	面积图元用于绘制封闭曲线与坐标轴之间的区域，可以用来创建面积图等可视化效果。
路径	`registerPathMark`	路径图元用于绘制任意形状的路径，可以用来创建自定义的图形和地理轨迹等可视化效果。
涟漪点	`registerRippleMark`	涟漪点图元是一种具有涟漪效果的点图元，通常用于强调某个特定的数据点或者表示某个位置上的数据变化。在地图可视化、时间序列分析等场景中，涟漪点图元可以表达数据的空间分布、数据变化的动态过程等。使用场景包括表示地震、疫情、新闻事件等的传播过程。
3D 矩形	`registerRect3dMark`	三维矩形图元用于绘制长方体，可以用来创建三维可视化中的柱状图等可视化效果。
3D 弧形	`registerRect3dMark`	三维弧形图元用于绘制柱体，可以用来创建三维可视化中的饼图、环形图等可视化效果。
3D 金字塔	`registerPyramid3dMark`	三维金字塔图元用于绘制金字塔形状的六面体，可以用来创建三维可视化中的漏斗图等可视化效果。

附录四：插件注册列表

插件	插件注册方法
全局形变动画	`registerMorph`
3d渲染	`register3DPlugin`
动画	`registerAnimate`
React插件	`registerReactAttributePlugin`
HTML插件	`registerHtmlAttributePlugin`
拖拽插件	`registerDragPlugin`
手势插件	`registerGesturePlugin`

附录五：交互注册列表

交互类型	交互名称	交互注册方法	react-vchart是否默认注册	taro-vchart是否默认注册
`element-select`	图元选中交互	`registerElementSelect`	是	是
`element-highlight`	图元Hover交互	`registerElementHighlight`	是	是
`element-active`	图元激活交互	`registerElementActive`	否	否
`element-highlight-by-legend`	图例触发图元高亮、失焦状态	`registerElementHighlightByLegend`	否	否
`element-active-by-legend`	图例触发图元激活状态	`registerElementActiveByLegend`	否	否
`element-highlight-by-group`	图元分组高亮	`registerElementHighlightByGroup`	否	否
`element-highlight-by-key`	图元按key值高亮	`registerElementHighlightByKey`	否	否
`element-highlight-by-name`	图元按名称高亮	`registerElementHighlightByName`	否	否