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 导入并注册。
其中,直角坐标系图表默认注册组件如下:
registerCartesianLinearAxisregisterCartesianBandAxisregisterCartesianTimeAxisregisterCartesianLogAxisregisterCartesianCrossHairregisterBrushregisterContinuousLegendregisterDataZoomregisterDiscreteLegendregisterCustomMarkregisterAllMarksregisterMarkArearegisterMarkLineregisterMarkPointregisterScrollBarregisterTitleregisterTooltipregisterDomTooltipHandler
极坐标系图表默认注册组件如下:
registerPolarLinearAxisregisterPolarBandAxisregisterPolarCrossHairregisterBrushregisterContinuousLegendregisterDataZoomregisterDiscreteLegendregisterCustomMarkregisterAllMarksregisterScrollBarregisterTitleregisterTooltipregisterDomTooltipHandler
通用图表默认注册组件 如下:
registerDiscreteLegendregisterContinuousLegendregisterCustomMarkregisterAllMarksregisterTitleregisterTooltipregisterDomTooltipHandler
使用语义化标签的时候,如果用到其他没有默认加载的组件,只需要注册未加载的组件即可;
也可以参考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 |
其中,直角坐标系图表默认注册组件如下:
registerCartesianLinearAxisregisterCartesianBandAxisregisterCartesianTimeAxisregisterCartesianLogAxisregisterCartesianCrossHairregisterBrushregisterContinuousLegendregisterDataZoomregisterDiscreteLegendregisterCustomMarkregisterAllMarksregisterMarkArearegisterMarkLineregisterMarkPointregisterScrollBarregisterCanvasTooltipHandlerregisterTitle
极坐标系图表默认注册组件如下:
registerPolarLinearAxisregisterPolarBandAxisregisterPolarCrossHairregisterBrushregisterContinuousLegendregisterDataZoomregisterDiscreteLegendregisterCustomMarkregisterAllMarksregisterScrollBarregisterCanvasTooltipHandlerregisterTitle
通用图表默认注册组件如下:
registerDiscreteLegendregisterContinuousLegendregisterCustomMarkregisterAllMarksregisterTitleregisterTooltipregisterCanvasTooltipHandler
使用语义化标签的时候,如果用到其他没有默认加载的组件,只需要注册未加载的组件即可;
也可以参考taro-vchart 教程中的按需加载章节
跨端
VChart 默认对浏览器和 node 环境提供了支持。如果你的项目需要运行在小程序环境下,按需加载时,请注意引入小程序环境代码。
例如,在微信小程序中使用时,需要调用 registerWXEnv:
import { registerWXEnv } from '@visactor/vchart'; VChart.useRegisters([registerWXEnv]);
目前 VChart 支持的环境兼容注册器包括:
| 环境 | 组件注册方法 |
| 浏览器 | registerBrowserEnv |
| Node | registerNodeEnv |
| 微信小程序 | registerWXEnv |
| 飞书小程序 | registerLarkEnv |
| Lynx | registerLynxEnv |
| 以上所有 | registerAllEnv |