!!!###!!!title=VChart 按需加载教程——VisActor/VChart 教程文档!!!###!!!!!!###!!!description=`dot`、`link` 系列的实现、类型和注册方法已迁至 `@visactor/vchart-extension`,主包不再导出或自动注册。单独使用时按以下方式注册;`registerSequenceChart` 和 `registerSequenceAnalysis` 会自动注册所需系列。```tsimport { registerDotSeries, registerLinkSeries } from '@visactor/vchart-extension';import type { IDotSeriesSpec, ILinkSeriesSpec } from '@visactor/vchart-extension';registerDotSeries();registerLinkSeries();```!!!###!!!

VChart 按需加载教程

dot、link 系列的实现、类型和注册方法已迁至 @visactor/vchart-extension,主包不再导出或自动注册。单独使用时按以下方式注册;registerSequenceChart 和 registerSequenceAnalysis 会自动注册所需系列。

import { registerDotSeries, registerLinkSeries } from '@visactor/vchart-extension';
import type { IDotSeriesSpec, ILinkSeriesSpec } from '@visactor/vchart-extension';

registerDotSeries();
registerLinkSeries();

快速上手

@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

SequenceChart 由组件内部调用扩展包的 registerSequenceChart 注册,组件用法不变;直接使用 VChart 核心包时需自行从 @visactor/vchart-extension 导入并注册。

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

  • 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
NoderegisterNodeEnv
微信小程序registerWXEnv
飞书小程序registerLarkEnv
LynxregisterLynxEnv
以上所有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(@visactor/vchart-extension)
时序图连线系列registerLinkSeries(@visactor/vchart-extension)
漏斗图系列registerFunnelSeries
仪表盘系列registerGaugeSeries
玫瑰图系列registerRoseSeries
环形进度图系列registerCircularProgressSeries
仪表图指针系列registerGaugePointerSeries
桑基图系列registerSankeySeries
矩形树图系列registerTreemapSeries
词云系列registerWordCloudSeries
圆嵌套图系列registerCirclePackingSeries
3d 柱系列registerBar3dSeries
3d 漏斗系列registerFunnel3dSeries
3d 饼系列registerPie3dSeries
3d 区间柱系列registerRangeColumn3dSeries
3d 词云系列registerWordCloud3dSeries

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

组件组件注册方法实际场景示意
离散图例registerDiscreteLegend
连续图例registerContinuousLegend
提示信息registerTooltipTooltip 包括 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否否