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

apache/echarts

菜单

ECharts 核心

相关源文件

ECharts 核心是 Apache ECharts 库的基础。它提供了驱动可视化库中所有图表类型和组件的基本架构、生命周期管理和渲染机制。本页面将介绍核心系统架构、初始化过程以及实现 ECharts 强大可视化能力的关键机制。

有关驱动 ECharts 选项的类型系统信息，请参阅类型系统。有关数据管理和处理的详细信息，请参阅数据管理。

ECharts 核心概述

ECharts 核心主要通过 ECharts 类实现，该类是图表实例的中心控制点。该类封装了整个图表生命周期，从初始化和选项处理到渲染和事件处理。

核心系统负责：

  1. 创建和管理图表实例
  2. 处理配置选项
  3. 管理渲染管道
  4. 处理用户交互和事件
  5. 协调各组件
  6. 管理图表状态和动画

来源: src/core/echarts.ts332-497 package.json1-225

核心架构

来源: src/core/echarts.ts332-497 src/core/echarts.ts578-721

关键组件

  1. ECharts：主类，作为图表创建和配置的入口。它管理图表的生命周期，处理用户交互，并协调不同组件。

  2. ZRender：底层渲染引擎，负责在 Canvas 或 SVG 上实际绘制图形。它是 ECharts 所依赖的一个独立库。

  3. GlobalModel：包含图表的所有配置数据和状态，包括系列、组件和选项。

  4. Scheduler：协调数据处理和可视化任务。它管理数据处理、视觉编码和布局计算的管道。

  5. ExtensionAPI：提供组件扩展与核心系统交互的接口。

  6. MessageCenter：处理组件之间的事件通信。

  7. CoordinateSystemManager：管理图表中使用的不同坐标系，例如笛卡尔坐标系、极坐标系等。

来源: src/core/echarts.ts332-497 src/core/echarts.ts139-192

初始化与生命周期

来源: src/core/echarts.ts395-496 src/core/echarts.ts610-691

初始化过程

ECharts 实例的初始化涉及几个关键步骤：

  1. 创建 ECharts 实例：这通过 echarts.init(dom, theme, opts) 工厂方法完成，该方法创建一个新的 ECharts 实例。

  2. ZRender 初始化：ECharts 实例使用提供的 DOM 元素初始化一个 ZRender 实例。

  3. 组件初始化：初始化各种管理器和组件，包括：

    • 坐标系管理器
    • 调度器
    • 消息中心（用于事件处理）
    • 扩展 API

  4. 事件绑定：为鼠标交互和动画帧设置事件监听器。

ECharts 实例的典型生命周期包括：

init() → setOption() → (render cycle) → resize()/dispatchAction() → (render cycle) → dispose()

来源: src/core/echarts.ts395-496 src/core/echarts.ts498-577

选项处理和渲染管道

来源: src/core/echarts.ts610-691 src/core/echarts.ts139-192

选项处理

ECharts 的核心功能之一是处理配置选项。这发生在 ECharts 类的 setOption 方法中：

  1. 选项合并：当调用 setOption 时，ECharts 可以替换现有选项（使用 notMerge: true）或与现有选项合并（默认行为）。

  2. 选项管理：OptionManager 帮助管理主题和选项，包括将选项与主题合并。

  3. 模型创建：选项用于创建或更新 GlobalModel，然后 GlobalModel 创建组件模型和系列模型。

选项处理管道包括向后兼容性处理、主题应用和组件特定选项处理。

来源: src/core/echarts.ts610-691

渲染管道

ECharts 中的渲染管道由 Scheduler 管理，包含多个阶段：

  1. 数据处理：原始数据被处理成可用于可视化的格式。

    • 包括数据过滤、堆叠和采样等操作
    • 作为具有优先级的处理器任务实现（PRIORITY_PROCESSOR_*）

  2. 视觉编码：数据被映射到颜色、大小和位置等视觉属性。

    • 作为具有优先级的视觉任务实现（PRIORITY_VISUAL_*）
    • 包括根据视觉映射计算颜色的任务

  3. 布局计算：计算元素的位置和大小。

    • 包括坐标系设置、坐标轴定位和图表布局

  4. 渲染：视觉元素被渲染到屏幕上。

    • 轴、图例等组件首先被渲染
    • 系列元素（如柱状图、折线图）接着被渲染
    • 使用 ZRender 创建和更新图形元素

这些阶段中的每一个都作为一系列任务实现，由 Scheduler 按照优先级顺序执行。

来源: src/core/echarts.ts498-577 src/core/echarts.ts139-192

事件处理和用户交互

来源: src/core/echarts.ts843-888 src/core/echarts.ts1000-1049

事件系统

ECharts 拥有一个全面的事件系统，可处理用户交互和内部事件：

  1. 事件注册：用户可以使用 on 方法注册事件处理程序。

  2. 事件类型:

    • 鼠标事件：click、dblclick、mouseover、mouseout 等。
    • 组件事件：legendselected、datazoom 等。
    • 渲染事件：rendered、finished
    • 其他事件：restore、dataviewchanged 等。

  3. 事件传播：事件源自 ZRender 并传播到 ECharts 实例，然后 ECharts 实例处理这些事件并触发相应的处理程序。

  4. 动作分发：可以使用 dispatchAction 方法以编程方式分发动作。

来源: src/core/echarts.ts843-888 src/core/echarts.ts889-999

状态管理

ECharts 管理视觉元素的不同状态，这对于用户交互非常重要：

  1. 普通状态：元素的默认外观。

  2. 强调状态：当鼠标悬停在元素上时激活，通常用于高亮显示。

  3. 选中状态：应用于被选中的元素，通常通过点击实现。

  4. 虚化状态：当其他元素高亮显示时，应用于未聚焦的元素。

状态管理系统通过 states.ts 文件中的一系列辅助函数实现，并在整个 ECharts 渲染管道中使用。

来源: src/core/echarts.ts1050-1100 src/util/states.js56-83

与 ZRender 的集成

来源: src/core/echarts.ts395-420 package.json67-68

ZRender 介绍

ZRender 是 ECharts 使用的渲染引擎。它是一个轻量级的 Canvas 库，提供：

  1. 2D 绘图能力：ZRender 可以渲染到 Canvas 和 SVG。
  2. 元素管理：它管理图形元素，如路径、图像和文本。
  3. 动画：它提供动画功能以实现平滑过渡。
  4. 事件处理：它处理 DOM 事件并提供抽象层。

ECharts 使用 ZRender 作为其底层渲染引擎，创建了一个抽象层，使其能够专注于图表逻辑而非底层渲染细节。

来源: src/core/echarts.ts395-420 package.json67-68

集成点

ECharts 和 ZRender 之间的主要集成点包括：

  1. 初始化：ECharts 在初始化期间创建 ZRender 实例

  2. 元素创建：图表组件和系列创建 ZRender 元素（路径、图像、文本）以表示其视觉形式。

  3. 事件处理：ZRender 处理 DOM 事件并将其传递给 ECharts 进行进一步处理。

  4. 动画：ECharts 使用 ZRender 的动画系统创建平滑过渡。

  5. 渲染：ECharts 在需要时触发 ZRender 渲染元素。

来源: src/core/echarts.ts419-459 src/core/echarts.ts769-772

关键方法和 API

方法描述
echarts.init(dom, theme, opts)创建一个新的 ECharts 实例
chart.setOption(option, notMerge, lazyUpdate)设置或更新图表配置
chart.getWidth() / chart.getHeight()获取图表容器的宽度/高度
chart.resize(opts)调整图表大小
chart.dispatchAction(payload)分派一个动作来触发状态改变
chart.on(eventName, handler, context)注册一个事件处理程序
chart.off(eventName, handler)移除一个事件处理程序
chart.getDataURL(opts)获取图表图片的 base64 URL
chart.getConnectedDataURL(opts)获取关联图表的 base64 URL
chart.appendData(params)向系列追加数据
chart.clear()清除图表内容
chart.isDisposed()检查图表是否已销毁
chart.dispose()销毁图表

来源: src/core/echarts.ts578-842

常用用户 API

最常用的 API 方法包括：

  1. echarts.init(dom, theme, opts)：创建一个新的 ECharts 实例

    • dom：用于渲染图表的 DOM 元素
    • theme：主题名称或配置对象
    • opts：初始化选项，包括渲染器类型

  2. chart.setOption(option, notMerge, lazyUpdate)：设置或更新图表配置

    • option：图表配置对象
    • notMerge：是否与现有选项合并
    • lazyUpdate：是否延迟更新

  3. chart.resize(opts)：调整图表大小

    • opts：调整大小选项，包括宽度和高度

  4. chart.dispatchAction(payload)：以编程方式触发动作

    • payload：带有类型和参数的动作配置

  5. chart.on(eventName, handler, context)：注册事件处理程序

    • eventName：事件名称
    • handler：事件处理函数
    • context：处理程序的上下文

来源: src/core/echarts.ts579-608 src/core/echarts.ts609-691

配置和扩展

来源: src/core/echarts.ts1950-2000 package.json105-223

配置结构

ECharts 通过其选项结构具有高度可配置性。主要的配置部分包括：

  1. 全局选项：控制图表的整体外观和行为

    • title、legend、tooltip、grid 等。

  2. 系列选项：定义数据系列及其可视化

    • series: [{type: 'line', data: [...]}, ...]

  3. 组件选项：配置图表组件

    • xAxis、yAxis、dataZoom、visualMap 等。

  4. 视觉映射：定义数据和视觉属性之间的映射

    • visualMap、系列级别视觉属性等。

来源: src/core/echarts.ts580-608 src/core/echarts.ts609-691

扩展机制

ECharts 提供多种扩展机制：

  1. 注册组件：可以注册新的图表类型或组件

  2. 主题：可以注册和应用自定义主题

  3. 地图数据：可以注册自定义 GeoJSON 数据

  4. 本地化：可以注册自定义本地化文本

ECharts 采用模块化架构，功能可以根据需要包含或排除。包导出反映了这种模块化，允许用户仅导入他们需要的部分。

来源: src/core/echarts.ts1950-2000 package.json105-223

性能考量

ECharts 包含多种性能优化机制：

  1. 渐进式渲染：大型数据集可以渐进式渲染，以避免界面冻结

    • 由 progressive 选项控制
    • 通过调度器的渐进式渲染系统实现

  2. 增量渲染：仅重新渲染更改的部分

    • 使用脏检查机制跟踪更改

  3. 流模式：对于时间序列数据，允许高效追加数据

    • 通过 appendData 方法实现

  4. Canvas 与 SVG：支持两种具有不同性能特征的渲染模式

    • Canvas 通常对大量元素更快
    • SVG 为较小的数据集提供更好的交互能力

  5. 分层渲染：使用多层方法进行渲染

    • 不同的 Z 轴层渲染到不同的 Canvas 层

  6. 节流：对调整大小等频繁操作进行节流

    • 使用节流工具实现

来源: src/core/echarts.ts498-577 src/core/echarts.ts1101-1200

结论

ECharts 核心为整个 ECharts 库提供了基础。它管理图表生命周期、处理选项、协调渲染并处理事件。通过理解核心架构和组件，您可以更好地利用 ECharts 的能力并根据自定义需求进行扩展。

ECharts 核心要点

  1. 它基于 ZRender 进行底层渲染
  2. 它采用模块化、基于组件的架构
  3. 它拥有复杂的数据处理和视觉编码管道
  4. 它为配置和交互提供了丰富的 API
  5. 它包含了多种用于处理大型数据集的性能优化措施

有关基于核心构建的图表类型和组件的更多详细信息，请参阅相应的文档页面。

来源: src/core/echarts.ts332-342 package.json2-29