VChart
全局 VChart
对象,也作为图表的总入口,用于图表的创建、更新和销毁。
静态属性
ThemeManager
主题管理器。可用于全局主题的注册、设置以及获取等,详见theme。
globalConfig
VChart 的全局配置项。这个对象里的属性可以直接修改,配置的生效时机依具体配置项而定 。
是否全局显示唯一 tooltip。如果置为 true,当某个图表触发 tooltip 时,同一页面的所有其他图表的 tooltip 将自动消失。
此配置修改后即时生效。
静态方法
useRegisters
1.5.1 版本开始支持。
用于按需加载图表、系列、组件、环境兼容代码等。具体使用请参考 按需引入教程
useChart
用于注册扩展的自定义图表 Chart。
useSeries
用于注册扩展的自定义系列 Series。
useComponent
用于注册扩展的自定义组件 Component。
useMark
用于注册扩展的自定义 组件 Mark。
useLayout
用于注册扩展的自定义布局 Layout。
用于注册 DataSet 数据方 法,常用于按需加载。
registerMap
注册地图数据。
unregisterMap
用于卸载地图数据。
getMap
根据注册的地图名称获取对应的地图数据。
初始化(new VChart)
用于创建 VChart 实例。
参数说明
spec
图表的 spec 配置,详见配置项页面。
options
图表配置,包含渲染容器等,详见的配置如下表:
|
dom | string|HTMLElement | 否 | 仅生效于浏览器环境。 图表挂载的父容器,可以直接指定容器 id,也可以传入 dom 对象 |
renderCanvas | string|HTMLCanvasElement | 否 | 除去选择 dom 属性进行挂载父容器,也可以使用 renderCanvas 属性直接传入 canvas 实例/ canvasId,小程序/小组件环境请直接传入 id |
dataSet | DataSet | 否 | 数据集 |
autoFit | boolean | 否 | 是否自适应容器大小,默认为 true |
animation | boolean | 否 | 是否开启动画,默认为 true |
options3d | srIOption3DType | 否 | 3d 配置 |
layout | LayoutCallBack | 否 | 自定义布局函数 |
mode | string | 否 | 配置渲染环境,默认为 'desktop-browser',当需要在非浏览器环境渲染 VChart 时,需要配置该属性。 'desktop-browser' : 默认模式,适用于 PC 及 H5; 'mobile-browser' : H5 模式; 'node' : Node 渲染; 'worker' : worker 模式; 'miniApp' : 小程序模式; 'lynx' : lynx 渲染 |
modeParams | any | 否 | 配置 mode 参数一起使用,用于配置 mode 参数对应的环境的一些特殊配置 |
dpr | number | 否 | 设置屏幕分辨率 |
interactive | boolean | 否 | 图表交互全局开关,默认为 true ,开启。 |
viewBox | object | 否 | 指定绘制的矩形区域,如 { x1: 100, y1: 100, x2: 300, y2: 300 } |
canvasControled | boolean | 否 | 用于告诉底层的渲染引擎 VRender,图表的 Canvas 是否是受控制的 canvas,如果不是的话,不会进行 resize 等操作。 |
stage | Stage | 否 | 外部传入的 VRender stage |
layer | Layer | 否 | 外部传入的 VRender layer |
beforeRender | Function | 否 | 绘制之前的钩子函数,(stage: IStage) => void |
afterRender | Function | 否 | 绘制之后的钩子函数,(stage: IStage) => void |
background | string\object | 否 | 绘图区域背景色设置,可以配置渐变色 |
logLevel | number | 否 | 日志类型,用于开发调试 |
disableDirtyBounds | boolean | 否 | 是否关闭 dirtyBounds |
enableView3dTransform | boolean | 否 | 是否开启 view3d 的变换模式 |
poptip | boolean | 否 | 是否开启省略文本的 poptip,用于查看完整的文本内容,默认开启 |
disableTriggerEvent | boolean | 否 | 是否关闭交互效果;从1.9.0 版本开始支持 |
theme | string | ITheme | 否 | 默认主题(支持完整主题对象或者主题名称,主题名称需要提前在 ThemeManager 中注册) |
enableHtmlAttribute | boolean | 否 | 底层 vrender 图形节点是否支持html 属性; 从1.8.3 版本开始支持 |
supportsTouchEvents | boolean | 否 | 是否支持 touch 事件,不支持就不监听 touch 事件; 从1.8.9 版本开始支持 |
supportsPointerEvents | boolean | 否 | 是否支持 pointer 事件,不支持就监听 mouse 事件; 从1.8.9 版本开始支持 |
ReactDOM | object | 否 | react-dom 包导出产物,用于开启 vrender 渲染 react 元素; 从1.11.0 版本开始支持 |
示例
属性
id
只读属性,VChart 实例的 id,内部生成。
方法
renderSync
同步渲染图表。
renderAsync
1.9.0 版本以后不推荐使用,后续会废弃异步渲染/异步更新相关 API
异步渲染图表。
updateData
异步更新数据。参数 id
对应在 spec 中 data
属性上的 id
字段,会自动渲染图表不需要再调用 renderAsync()
等渲染方法。
updateDataInBatches
异步批量更新数据,会自动渲染图表不需要再调用 renderAsync()
等渲染方法。
updateDataSync
同步更新数据。参数 id
对应在 spec 中 data
属性上的 id
字段,会自动渲染图表不需要再调用 renderAsync()
等渲染方法。
updateFullData
更新数据接口。参数为完整的数据项配置,可以通过此接口更新数据的 fields
配置,默认会自动渲染图表不需要再调用 renderAsync()
等渲染方法。
updateFullDataSync
同步更新数据。参数为完整的数据项配置,可以通过此接口更新数据的 fields
配置,默认会自动渲染图表不需要再调用 renderAsync()
等渲染方法。
updateSpec
异步spec 更新,会自动渲染图表不需要再调用 renderAsync()
等渲染方法。
updateModelSpec
异步模块 spec 更新,可以通过 filter 指定更新某一个图表模块的配置,会自动渲染图表不需要再调用 renderAsync()
等渲染方法。
updateViewBox
更新绘制区域。viewBox 为绘制区域,格式为 { x1: number; x2: number; y1: number; y2: number }
。
resize
异步方法,图表尺寸更新方法。
release
销毁图表。
on
事件绑定。更加具体的使用,请移步event。
off
事件卸载。
updateState
更新或设置图元状态。
下方例子展示了如何更新状态的筛选条件,当我们点击图中的一个点,与这个点 type
值不同的点都变为半透明, 使用示例:
setSelected
更新图元选中状态。
设置一组数据为选中状态,也可以直接设置 null 来取消选中状态。
setHovered
更新图元 hover 状态。
设置一个数据为 hover
状态,也可以直接设置 null 来取消 hover
状态。
setHovered
效果类似 setSelected
,支持一次将多条数据设置为 hover
状态。
clearState
清除图元的状态
clearSelected
清除图元的选中状态
clearHovered
清除图元的 hover 状态
getCurrentTheme
获取当前主题,会返回完整的主题配置。
getCurrentThemeName
获取当前主题名称(只能获取用户通过 setCurrentTheme
方法设置过的主题,默认值为 ThemeManager
统一设置的主题)。
setCurrentTheme
异步方法, 设置当前主题。
注意:如果在图片的 spec 中配置了 theme
属性,则 spec.theme 的优先级更高。
当配置项无法满足 tooltip 的展示需求时,我们还提供了自定义 tooltip 的能力。可以通过配置 TooltipHandler
来覆盖默认 tooltip 展示逻辑。
注意:
- 当给图表设置了自定义
TooltipHandler
后,内置的 tooltip 将不再起作用。
- VChart 不感知、不托管自定义 tooltip 的渲染,请按照需要自行实现 tooltip 渲染,包括处理原始数据、tooltip 内容设计,以及根据项目 环境创建组件并设置样式。
- 当图表删除时会调用当前
TooltipHandler
的release
函数,请按照需要删除。
- 由于自定义
TooltipHandler
会覆盖内置 tooltip 逻辑,图表spec
中的部分 tooltip 配置项便不再起作用。但以下配置项作用于所有自定义TooltipHandler
:
tooltip.visible
tooltip.activeType
tooltip.trigger
tooltip.triggerOff
ITooltipHandler
接口定义如下:
其中ITooltipHandler.showTooltip
有三个参数,意义分别为:
activeType
: 透出本次触发的 tooltip 类型,值为'mark'
或'dimension'
data
: 透出本次触发的 tooltip 原始数据
params
: 透出本次触发的 tooltip 的鼠标事件
data
参数的类型为TooltipData
,类型定义为:
如果用户触发了 mark tooltip,TooltipData
便为 IDimensionData[]
类型。IDimensionData
的类型定义为:
而如果用户触发了 dimension tooltip,TooltipData
便为 IDimensionInfo[]
类型。IDimensionInfo
承载了鼠标所在整个维度项的信息,类型定义为:
用户可以选择使ITooltipHandler.showTooltip
方法返回一个状态TooltipResult
,用来表示 tooltip 是否成功显示(如果不返回,则默认当做成功)。这个返回值和缓存策略有关。TooltipResult
是个枚举类型,定义为:
ITooltipHandler.showTooltip
方法的最后一个参数为params
,其类型定义为:
其中暴露了一个很有用的参数:changePositionOnly
,代表这个 tooltip 是否仅仅是上一个 tooltip 挪用了下位置,而数据相同。这个参数将帮助用户对 tooltip 渲染进行优化。
示例:在控制台打出用户鼠标 hover 的维度项标题、以及系列图元的填充颜色:
获取TooltipHandler
。
手动调用展示 tooltip。
手动调用,关闭 tooltip
getLegendDataById
根据图例组件 id 获取图例数据,该 id 来源于在 spec 的 legends
字段中配置的 id
。如: legends: { id: 'bottom' }
或者 legends: [{ id: 'left' }]
图例数据类型:
getLegendDataByIndex
根据图例组件索引获取图例数据。
图例数据类型:
getLegendSelectedDataById
根据图例组件 id 获取当前图例的选中项,该 id 来源于在 spec 的 legends
字段中配置的 id
。如: legends: { id: 'bottom' }
或者 legends: [{ id: 'left' }]
getLegendSelectedDataByIndex
根据图例组件索引获取当前图例的选中项。
setLegendSelectedDataById
根据图例组件 id 更新图例选中数据,该 id 来源于在 spec 的 legends
字段中配置的 id
。如: legends: { id: 'bottom' }
或者 legends: [{ id: 'left' }]
setLegendSelectedDataByIndex
根据图例组件索引更新图例选中数据。
getDataURL
异步方法返回一个包含图片展示的 data URI。
exportImg
异步方法 导出图表图片,只支持浏览器端,同时参数 name
可以为图片进行命名。
exportCanvas
导出绘制有图表内容的 canvas ,只支持浏览器端。可以使用这个 canvas 进行二次处理,比如添加水印等。
getImageBuffer
目前仅支持 node 环境,用于 node 端的图片导出。
setLayout
设置自定义布局。
reLayout
强制重新布局。
getCompiler
获取编译器实例。
getChart
获取 Chart 图表实例。
getStage
获取渲染引擎实例。
getCanvas
获取 canvas dom。
getContainer
获取图表的 dom 容器。
getComponents
获取图表所有的组件实例。
getDataSet
获取图表的 DataSet 实例。
getScale
自版本 1.10.4
开始支持;
获取图表的 Scale 实例。
setDimensionIndex
手动调用触发 dimension 交互效果。