在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

apache/echarts

菜单

视觉状态与动画

相关源文件

本页面介绍了 Apache ECharts 中的视觉状态和动画系统，它们共同实现了交互式、动态的可视化。视觉状态定义了图表元素在不同交互上下文（正常、强调、模糊或选中）下的外观，而动画系统则控制元素在这些状态之间的过渡以及对数据变化的响应。

有关高级图形自定义的信息，请参阅 图形工具。

视觉状态系统

ECharts 提供了一个全面的系统来管理图表元素的视觉状态。这些状态决定了图表元素在不同用户交互时的外观。

显示状态概述

ECharts 定义了四种显示状态，如 src/util/types.ts652-653 中可以看到。

  • Normal：图表元素的默认外观
  • Emphasis：应用于元素被高亮时（通常是鼠标悬停时）
  • Blur：应用于元素被弱化时（通常是在其他元素被强调时）
  • Select：应用于元素被选中时（通常是通过点击）

来源：src/util/types.ts652-653 src/util/states.ts82-83

状态配置

视觉状态通过图表选项中的嵌套结构进行配置。

emphasis 配置接受两个重要属性：

  • focus：控制哪些元素被强调

    • 'self'：仅高亮鼠标悬停的元素（饼图、漏斗图默认值）
    • 'series'：高亮整个系列（大多数图表默认值）
    • 'adjacency'：高亮元素及其相邻元素（适用于图、桑基图）
    • 'descendant'：高亮元素及其后代元素（适用于树、树状图、旭日图）

  • blurScope：控制哪些元素被模糊

    • 'coordinateSystem'：模糊同一坐标系内的元素
    • 'series'：模糊系列内的元素
    • 'global'：模糊所有系列的所有元素

来源：src/util/states.ts78-83 src/util/states.ts647-684 test/hoverFocus.html72-81

内部状态管理

ECharts 使用内部属性跟踪每个元素的当前状态。

  • el.hoverState：数值（0：正常，1：模糊，2：强调）
  • el.selected：布尔标志，指示选中状态

状态转换由诸如 enterEmphasis()、leaveBlur() 等函数管理，这些函数会更新这些属性并触发视觉更新。

来源：src/util/states.ts109-145 src/util/states.ts372-396

动画系统

ECharts 的动画系统提供了状态更改和数据更新的平滑过渡。

动画配置

动画选项可以在多个级别指定：

  1. 全局图表级别：应用于所有元素
  2. 系列级别：应用于系列中的所有元素
  3. 单个元素级别：应用于特定元素

在 src/util/types.ts833-872 中定义了关键的动画属性：

  • animation：启用/禁用动画（布尔值）
  • animationThreshold：当元素数量超过阈值时禁用动画
  • animationDuration：初始动画的持续时间（毫秒）
  • animationEasing：缓动函数（例如，'linear'、'quadraticOut'）
  • animationDelay：动画开始前的延迟（毫秒）
  • animationDurationUpdate：更新动画的持续时间（毫秒）
  • animationEasingUpdate：更新的缓动函数
  • animationDelayUpdate：更新动画开始前的延迟（毫秒）

来源：src/util/types.ts823-872 test/bar-race.html117-120

动画实现

动画系统是通过关键方法实现的：

  • initProps()：使用动画初始化元素属性
  • updateProps()：使用动画更新元素属性
  • removeElement()：使用动画移除元素
  • removeElementWithFadeOut()：使用淡出效果移除元素

这些函数从 src/animation/basicTransition.ts 导出，并在 src/util/graphic.ts82 中重新导出。

来源：src/util/graphic.ts72-82 src/chart/bar/BarView.ts319-320

状态与动画的整合

视觉状态和动画协同工作，以创建平滑、交互式可视化。

状态过渡动画

当元素状态改变时（例如，从正常到强调），视觉属性（如颜色、大小或不透明度）会从其初始值过渡到目标状态值。

过渡动画过程

  1. 用户交互触发状态更改。
  2. 状态更改函数更新内部状态标志。
  3. stateProxy 函数计算目标外观。
  4. updateProps() 函数从当前外观动画到目标外观。
  5. 元素以动画属性进行渲染。

来源：src/util/states.ts325-339 src/chart/bar/BarView.ts424-439

标签动画

ECharts 为标签动画提供了特殊处理，允许文本标签在值更改时平滑地进行动画。

当启用 valueAnimation 时，标签中更改的值将从旧值动画到新值。

来源：src/label/labelStyle.ts280-285 test/bar-race.html108-115

现实世界中的例子

柱状赛跑图

柱状图赛跑（Bar racing charts），如 test/bar-race.html 所示，展示了 ECharts 动画系统的强大功能

  • 柱子会根据不断变化的值重新排序
  • 标签会随着动画的值进行更新
  • 数据状态之间的过渡平滑且连续

关键配置元素包括：

来源：test/bar-race.html101-120 src/chart/bar/BarSeries.ts190-162

悬停效果

ECharts 通过 emphasis（强调）状态提供了丰富的悬停效果功能

  • 高亮被悬停的元素
  • 根据 focus 设置来强调相关的元素
  • 根据 blurScope 来弱化（模糊）其他元素

来源：test/hoverStyle.html165-171 test/hoverFocus.html84-85

性能考量

动画阈值

对于大型数据集，动画会影响性能。ECharts 提供了 animationThreshold 选项，当元素数量超过阈值时自动禁用动画。

来源：src/util/types.ts841

强制动画

在某些情况下，您可能希望即使元素不可见也要强制进行动画。ECharts 为此目的提供了特殊的标志。

  • forceLabelAnimation：即使对于不可见的元素，也强制进行标签动画
  • disableLabelAnimation：即使在正常情况下会动画，也禁用标签动画

这些在类似柱状图赛跑（bar-racing）的图表中特别有用，因为元素可能暂时超出视图。

来源：src/util/types.ts125-139 src/chart/bar/BarView.ts296

技术实现

ECElement 接口

ECElement 接口通过状态管理属性扩展了 ZRender 的 Element

来源：src/util/types.ts107-140

状态代理机制

ECharts 使用状态代理机制来计算元素在不同状态下的视觉外观。默认实现位于 elementStateProxy() （src/util/states.ts325-339)

此代理函数在未定义特定样式时应用默认的视觉增强。

来源：src/util/states.ts325-339 src/util/states.ts346-356

总结

Apache ECharts 中的视觉状态和动画系统提供了创建交互式和动态可视化的强大工具

  • 视觉状态：定义元素在不同交互状态下的外观（正常、强调、模糊、选中）
  • 焦点和模糊范围：控制交互期间哪些元素被强调，哪些元素被模糊
  • 动画系统：控制元素如何在状态之间过渡以及如何响应数据更改
  • 集成系统：状态更改会自动触发动画，实现平滑过渡

了解这些系统可以帮助您创建更具吸引力和交互性的图表，并通过平滑的过渡帮助用户理解数据变化和关系。

来源：src/util/types.ts652-653 src/util/states.ts78-83 src/util/types.ts823-872