图形工具

概述

Apache ECharts 中的图形组件提供了一套全面的工具，用于低层级的视觉元素创建、操作和渲染。这些组件是自定义可视化、高级图表组件以及对 ECharts 库中视觉呈现进行精细控制的基础。

本文档涵盖了图形组件系统的架构、核心元素和常见使用模式。有关视觉状态和动画的信息，请参阅视觉状态与动画。

架构

图形组件系统充当底层渲染引擎 (ZRender) 的抽象层，为图表开发者提供一致的 API，用于创建和操作视觉元素，而无需考虑实际的渲染技术（Canvas 或 SVG）。

来源：test/custom.html136-141 test/hoverStyle.html136-146

核心图形元素

图形组件提供了一组可组合以创建复杂可视化的基本图形元素。

元素类型	描述	通用属性
`group (分组)`	其他元素的容器	`children`, `$mergeChildren`
`rect (矩形)`	矩形形状	`x`, `y`, `width`, `height`
`circle (圆形)`	圆形	`cx`, `cy`, `r`
`line (直线)`	线段	`x1`, `y1`, `x2`, `y2`
`polygon (多边形)`	闭合多边形	`points (点集)`
`polyline (折线)`	连接的线段	`points (点集)`
`text (文本)`	文本元素	`text`, `x`, `y`, `textAlign`
`image (图片)`	图像元素	`style.image`, `x`, `y`, `width`, `height`

这些元素可以在多种上下文中使用，包括用于独立元素的graphic组件、用于数据驱动可视化的custom系列类型，以及通过 ECharts API 进行编程。

来源：test/custom.html149-152 test/custom.html283-292 test/custom.html361-371

元素层级和分组

图形元素可以使用分组进行分层组织，这对于管理复杂的可视化以及实现适当的堆叠和 Z 轴排序至关重要。

分组可用于：

同时对多个元素应用变换
作为一个单元管理元素的可见性
通过 Z 轴索引控制渲染顺序
通过合并策略实现高效的元素更新

合并策略

$mergeChildren属性允许通过指定子元素在更新期间应如何合并来实现复杂的元素更新

策略	描述
`'byName' (按名称)`	按`name`属性匹配子元素
`'byIndex' (按索引)`	按数组索引匹配子元素
`false`	替换所有子元素

来源：test/custom-children-remove.html153-157

样式管理

图形元素使用一致的样式系统，支持普通状态和强调（悬停）状态。

基本样式属性

属性	描述
`fill (填充色)`	填充颜色
`stroke (描边色)`	描边颜色
`lineWidth (线宽)`	描边宽度
`opacity (透明度)`	整体透明度
`shadowBlur (阴影模糊)`	阴影模糊量
`shadowColor (阴影颜色)`	阴影颜色
`shadowOffsetX/Y (阴影偏移)`	阴影偏移

文本特定样式

属性	描述
`text (文本)`	文本内容
`font (字体)`	字体规范
`textFill (文本填充色)`	文本颜色
`textStroke (文本描边色)`	文本描边颜色
`textStrokeWidth (文本描边宽度)`	文本描边宽度

强调样式

强调样式在元素悬停或高亮时应用。它们使用与普通样式相同的属性，但定义在emphasis属性中

{
    type: 'rect',
    shape: {...},
    style: {...},           // Normal state styles
    styleEmphasis: {...}    // Emphasis state styles
}

来源：test/hoverStyle.html449-455 test/custom.html575-578

使用模式

独立图形

图形元素可以使用graphic组件直接作为独立元素添加到图表中

$action属性控制setOption调用期间元素的更新方式

操作	描述
`'merge' (合并)`	更新现有元素（默认）
`'replace' (替换)`	替换现有元素
`'remove' (移除)`	从图表中移除元素

来源：test/graphicRemove.html89-94

自定义系列 (Custom Series)

custom系列类型通过renderItem函数实现数据驱动的图形元素创建

renderItem函数接收：

params: 上下文信息（系列、数据索引等）
api: 用于数据访问和坐标转换的辅助方法

它返回一个图形元素定义或包含多个元素的分组。

来源：test/custom.html130-153 test/custom.html277-293 test/custom.html355-371

`api`对象

api对象提供了创建数据驱动可视化所需的核心方法

方法	描述
`api.value(dimension)`	获取原始数据值
`api.coord([x, y])`	将数据值转换为像素坐标
`api.size([width, height])`	将数据值转换为像素大小
`api.style(userProps)`	获取应用了视觉映射的元素样式
`api.styleEmphasis(userProps)`	获取应用了视觉映射的强调样式
`api.visual(visualType)`	获取特定的视觉属性（颜色、符号等）

来源：test/custom.html277-293 test/hoverStyle.html448-455

实用函数

裁剪工具

图形组件包括用于裁剪形状以确保它们保持在指定边界内的函数

功能	描述
`echarts.graphic.clipPointsByRect(points, rect)`	将点数组裁剪到矩形边界内
`echarts.graphic.clipRectByRect(targetRect, boundingRect)`	将矩形裁剪到另一个矩形的边界内

这些对于确保可视化保持在其坐标系统内特别有用。

来源：test/custom.html835-841 test/hoverStyle.html136-146

与视觉状态系统交互

图形组件与 ECharts 的视觉状态系统（normal, emphasis, blur）紧密配合。在定义图形元素时，可以为不同状态指定不同的样式。

{
    type: 'circle',
    shape: {...},
    style: {...},           // Normal state
    styleEmphasis: {...}    // Emphasis (hover) state
}

有关视觉状态系统的更多信息，请参阅视觉状态与动画。

来源：test/hoverStyle.html448-455

高级用法：悬停层

ECharts 可以通过为强调状态使用独立的悬停层来优化渲染性能。这由hoverLayerThreshold选项控制。

值	行为
`null`	不使用悬停层
数字	当元素数量超过此阈值时使用悬停层

这对于包含大量元素的可视化尤为重要，因为它能显著提升悬停性能。

来源：test/hoverStyle.html81-91 test/hoverStyle.html95-101

总结

ECharts 中的图形组件系统为创建自定义可视化和扩展库功能提供了灵活而强大的基础。通过理解本文档中描述的核心元素、样式系统和使用模式，开发者可以创建超越内置图表类型的复杂可视化。