TuiEcharts

💎高级组件

🧊增强封装

⭐明星组件

TuiEcharts 是 TechUI 图表体系中的 “智能渲染壳层 (Intelligent Rendering Shell)”。

它并非是对 ECharts 的传统二次封装，而是一层智能的功能性外壳 (Functional Shell)。它在完美保持 ECharts 原生配置能力的同时，接管了繁琐的实例初始化与生命周期管理，极大地简化了开发流程。

更重要的是，它为标准的 ECharts 实例注入了独有的 “SVG 深度引擎 (SVG Depth Engine)”。通过与 Tui3DPanel 的协同工作，它能对 ECharts 输出的 SVG 节点进行实时解析与特征提取，从而在常规 DOM 环境中实现伪 3D 厚度与光影渲染，赋予平面图表前所未有的空间表现力。

TuiEcharts 是组件库中7个高级组件之一，需要取得授权后使用。

核心特性

SVG 3D 深度模拟：通过独特的节点克隆与投影技术，让普通的柱状图、饼图产生物理厚度感。
高性能渲染：支持 canvas 与 svg 双模式切换，针对 3D 场景进行了 DOM 节点优化。
智能重绘 (Smart Resize)：内置 ResizeObserver，支持组件级 (self) 或全局级 (global) 的自适应策略。
滚动数字集成：与图表动画同步的数字滚动支持（见 Demo）。

3D 化原理

Echarts 图表 3D 化是 TechUI 原创方案: 这是 TuiEcharts 最具黑科技色彩的功能。标准的 ECharts 在非 GL 模式下是扁平的，为了实现 3D 效果，组件采用了 “标记-提取-投影” 的渲染管线。

渲染机制

要开启 3D 效果，必须满足以下两个条件：

外部容器：图表必须包裹在 <Tui3DPanel> 组件中，由它提供 CSS transform 透视变换（如 rotateX, rotateY）。
渲染模式：TuiEcharts 的 renderer 属性必须设置为 'svg'。

厚度模拟原理 (Shadow Layer)

组件会遍历 ECharts 生成的 SVG DOM 树。由于我们无法直接告诉 ECharts "给这个柱子加厚度"，我们采用了一种特征值匹配的方式。

组件会检测 SVG 路径中的 stroke-width (即 ECharts 配置中的 borderWidth)。如果该数值转换成字符串后包含 "358" 这一特定序列，组件就会判定该元素需要“3D 化”。

它会执行以下操作：

克隆 (Clone)：复制该 SVG 节点生成一个独立的“阴影层”。
偏移 (Offset)：根据 Tui3DPanel 的角度计算偏移量。
模糊 (Blur)：应用 CSS Filter 实现体积感阴影。

“358” 文化彩蛋

为什么是 358？ 这个数值并非随机生成，而是起源于道家文化：
3：代表“三才”（天、地、人）；
5：代表“五行”（金、木、水、火、土）；
8：代表“八卦”（乾、兑、离、震、巽、坎、艮、坤）。
将 borderWidth 设为 0.0000358 既不会在视觉上产生可见的边框（极细），又能作为通往 3D 世界的“密钥”。

配置示例

在 ECharts 的 itemStyle 中注入密钥：

javascript

// 在 series data 中配置
itemStyle: {
    borderRadius: 3,
    borderColor: "white",
    opacity: 1,
    // 【关键】注入 358 密钥，触发 TuiEcharts 的 3D 阴影层生成
    borderWidth: 0.0000358,
}

好的，已为您添加了关于 配置来源 与 测试用例 的说明小节。您可以将其放在文档的末尾或 API 参考之后。

API 参考

Props (属性)

属性名	类型	默认值	说明
chartOption	`Object`	(Required)	ECharts 的标准配置对象。
width	`Number/String`	-	容器宽度。
height	`Number/String`	-	容器高度。
ready `v0.0.5+`	`Boolean`	`false`	渲染控制信号。设置为 `true` 时组件才会进行初始化/渲染，常用于异步数据等待。
renderer	`String`	`'canvas'`	渲染模式。注意：若要启用 3D 阴影效果，必须设为 `'svg'`。
initOptions	`Object`	`{}`	ECharts 初始化附加参数 (如 `devicePixelRatio`, `locale`)。
initT3DShadow	`Boolean`	`false`	是否开启 SVG 3D 阴影计算逻辑。
t3DShadowUpdate	`String`	`'finished'`	3D 阴影生成的时机。可选 `'rendered'` (渲染中) 或 `'finished'` (动画结束后)。
dataOpacity	`Number`	-	3D 阴影层的数据透明度。
dataBlur	`Number`	-	3D 阴影层的模糊半径 (px)。
resizeObserver	`String`	`'global'`	自适应策略。`'self'`(自身), `'global'`(窗口), `'none'`(禁用)。
loading	`Boolean`	`null`	加载状态 (支持 `v-model:loading`)。

移除的props

在v0.0.5移除过时的Props: initDelay 、initHold;

Events (事件)

事件名	说明
`chartClick` / `chartDblClick`	点击 / 双击图表元素时触发。
`chartMouseDown` / `chartMouseUp`	鼠标按下 / 抬起时触发。
`chartMouseOver`	鼠标悬停时触发。
`chartGlobalOut`	鼠标移出图表区域时触发。
`chartInit`	实例初始化完成时触发。
`chartReady`	图表首次渲染完成（包含动画）时触发。
`chartRendered`	每次渲染动作发生时触发。
`chartFinished`	渲染动作完全停止（动画结束）时触发。
`update:loading`	加载状态更新事件。

Methods (方法)

可通过 ref 调用：

resize(): 强制重绘。
setOption(option, ...): 更新配置。
getChart(): 获取 ECharts 实例。
clear(): 清空画布。
dispose(): 销毁实例。
initChart(): 手动初始化图表。

配置与示例

TuiEcharts 是基于 Apache ECharts 的 Vue 3 深度封装组件。为了保持 API 的标准性与学习成本的最小化，我们透传了 ECharts 的核心配置能力。

配置项参考 组件的 chartOption 属性完全兼容 ECharts 的标准数据结构。关于 series、xAxis、legend 等具体图表项的配置，请直接查阅 Apache ECharts 官方配置手册。
测试用例与实战代码 本文档中提及的各类图表（如 3D 饼图、雷达图、折线图）的完整测试用例源码，以及更多 TechUI 组件库的集成示例，请访问官方资源中心：前言-生态与资源

最佳实践 3D 饼图

以下代码展示了如何结合 Tui3DPanel 和 TuiEcharts 创建一个具有厚度感的 3D 饼图。

html

<script setup>
  import { reactive } from "vue";

  const state = reactive({
    // 基础 ECharts 配置
    chartOption: {
      series: [
        {
          type: "pie",
          radius: ["50%", "75%"],
          data: [
            {
              value: 325,
              name: "数据A",
              itemStyle: {
                color: "#409EFF",
                // 【核心】注入 358 密钥，告诉组件这个扇区需要 3D 厚度
                borderWidth: 0.0000358,
              },
            },
            {
              value: 252,
              name: "数据B",
              itemStyle: { borderWidth: 0.0000358 },
            }, // 省略颜色配置
          ],
        },
      ],
    },
    // 3D 面板配置
    t3dConfig: {
      view3d: true,
      initialRotate: { x: 40, y: 0 }, // 让面板向后倾斜，展示厚度
    },
  });
</script>

<template>
  <Tui3DPanel v-bind="state.t3dConfig" style="height: 400px; width: 400px;">
    <TuiEcharts
      :chartOption="state.chartOption"
      renderer="svg"
      :initT3DShadow="true"
      :dataOpacity="0.8"
      :dataBlur="2"
    />
  </Tui3DPanel>
</template>

注意事项

性能开销：initT3DShadow 会增加 DOM 节点数量，在数据量极大的散点图或热力图中建议关闭，或仅在鼠标悬停时开启。
动画同步：如果图表有初始动画，建议将 t3DShadowUpdate 设为 'rendered' 以获得更流畅的阴影跟随效果，但这会增加 CPU 负载。

致谢

特别感谢 Echarts 项目的初创团队 百度 EFE (Baidu EFE) 致以诚挚的敬意，感谢他们创造了如此卓越的数据可视化开源标准。

感谢 Apache 软件基金会 (ASF) 对该项目的持续维护与管理。

TuiEcharts ​

核心特性 ​

3D 化原理 ​

渲染机制 ​

厚度模拟原理 (Shadow Layer) ​

“358” 文化彩蛋 ​

配置示例 ​

API 参考 ​

Props (属性) ​

Events (事件) ​

Methods (方法) ​

配置与示例 ​

最佳实践 3D 饼图 ​

注意事项 ​

致谢 ​