Vue 3 + ECharts 响应式图表开发实战笔记

一、技术栈与架构设计

1.1 核心技术组合

• Vue 3 Composition API ：使用 <script setup> 语法糖
• ECharts 5.x：专业的数据可视化库
• Tailwind CSS：原子化 CSS 框架
• 响应式布局：自适应不同屏幕尺寸

1.2 关键变量管理

const chartRef = ref(null)          // DOM 元素引用
let chartInstance = null            // ECharts 实例（全局变量）

---

二、生命周期管理

2.1 初始化流程

onMounted 
  → initChart() 
    → 创建 ECharts 实例
    → 设置初始配置项
    → 调用 loadData() 获取数据
  → 添加 resize 事件监听

2.2 销毁流程

onUnmounted 
  → 移除 resize 事件监听
  → 销毁 ECharts 实例（防止内存泄漏）

2.3 代码实现

import { ref, onMounted, onUnmounted, watch } from 'vue'
import * as echarts from 'echarts'

const chartRef = ref(null)
let chartInstance = null

const initChart = () => {
  chartInstance = echarts.init(chartRef.value, 'dark')
  chartInstance.setOption({
    backgroundColor: 'transparent',
    // ... 配置项
  })
  loadData()
}

const handleResize = () => {
  chartInstance && chartInstance.resize()
}

onMounted(() => {
  initChart()
  window.addEventListener('resize', handleResize)
})

onUnmounted(() => {
  window.removeEventListener('resize', handleResize)
  chartInstance && chartInstance.dispose()
})

---

三、响应式特性实现

3.1 数据响应式（监听 props 变化）

watch([() => props.date, () => props.refreshKey], () => {
  loadData()
}, { immediate: true })

说明：

• 监听 props 变化（日期筛选、刷新指令）
• 自动触发数据重新加载
• immediate: true 确保组件挂载时立即执行

3.2 窗口大小响应式

const handleResize = () => {
  chartInstance && chartInstance.resize()
}

关键点：

• 监听窗口尺寸变化
• 自动调整图表大小
• 正确清理事件监听器

---

四、ECharts 配置要点

4.1 主题与背景

echarts.init(chartRef.value, 'dark')  // 暗色主题
backgroundColor: 'transparent'        // 透明背景

4.2 环形饼图配置

series: [{
  name: '爆品销量',
  type: 'pie',
  radius: ['40%', '65%'],  // 内外半径，形成环形
  center: ['40%', '50%'],  // 圆心位置
  avoidLabelOverlap: true, // 避免标签重叠
  itemStyle: {
    borderRadius: 8,
    borderColor: '#111827',
    borderWidth: 2
  },
  label: {
    show: true,
    position: 'outside',
    color: '#9ca3af',
    fontSize: 10,
    formatter: '{b}: {c}'
  },
  labelLine: { 
    show: true, 
    length: 10, 
    length2: 5 
  },
  data: []
}]

4.3 图例配置

legend: {
  type: 'scroll',          // 数据多时可滚动
  orient: 'vertical',      // 垂直排列
  right: '2%',             // 右侧位置
  top: 'middle',           // 垂直居中
  textStyle: { 
    color: '#9ca3af', 
    fontSize: 10 
  },
  icon: 'circle',
  pageTextStyle: { color: '#fff' }
}

4.4 提示框配置

tooltip: { 
  trigger: 'item', 
  formatter: '{a} <br/>{b}: {c} ({d}%)' 
}

---

五、数据更新策略

5.1 动态更新（不重新初始化）

const loadData = async () => {
  // ... 获取数据逻辑
  
  if (chartInstance) {
    chartInstance.setOption({
      series: [{ data: mockData }]
    })
  }
}

优势：

• ✅ 保持图表状态（缩放、高亮等）
• ✅ 性能更优
• ✅ 用户体验更好

5.2 完整数据加载流程

const loadData = async () => {
  console.log(`ProductTrendChart: 正在获取数据...`)

  // 模拟接口数据
  const mockData = [
    { value: 1200, name: '冷冻猪蹄' },
    { value: 1100, name: '新鲜菜心' },
    // ...
  ]

  if (chartInstance) {
    chartInstance.setOption({
      series: [{ data: mockData }]
    })
  }
}

---

六、样式设计要点

6.1 容器布局

.chart-card {
  @apply bg-[#1f2937] bg-opacity-40 border border-[#374151] rounded-xl p-4 flex flex-col;
  backdrop-filter: blur(4px);
  transition: all 0.3s;
}

.card-title {
  @apply text-sm font-bold text-gray-300 mb-2 pl-3 border-l-4 border-blue-500;
}

.chart-dom {
  @apply flex-1 w-full;
  min-height: 100px;
}

6.2 响应式高度

• 使用 flex-1 + min-h-0 确保容器自适应
• min-height: 100px 防止图表过小

---

七、最佳实践总结

7.1 内存管理

• ✅ 组件销毁时调用 chartInstance.dispose()
• ✅ 移除所有事件监听器
• ✅ 清理定时器（如有）

7.2 性能优化

• ✅ 使用 watch 监听而非 computed
• ✅ 数据更新使用 setOption 而非重新初始化
• ✅ 窗口 resize 添加防抖（可选）

7.3 错误处理

• ✅ 检查 chartInstance 是否存在
• ✅ API 调用添加 try-catch
• ✅ 控制台输出调试信息

7.4 代码结构

• ✅ 变量定义清晰（ref vs let）
• ✅ 函数职责单一
• ✅ 注释完整（中文说明）

---

八、扩展建议

8.1 防抖优化

let resizeTimer = null
const handleResize = () => {
  if (resizeTimer) clearTimeout(resizeTimer)
  resizeTimer = setTimeout(() => {
    chartInstance && chartInstance.resize()
  }, 150)
}

8.2 加载状态

const loading = ref(false)

// 显示加载动画
chartInstance.showLoading()

// 隐藏加载动画
chartInstance.hideLoading()

8.3 主题切换

echarts.init(chartRef.value, 'dark')  // 暗色主题
echarts.init(chartRef.value, 'light') // 亮色主题

---

九、常见问题 FAQ

Q1: 为什么使用 watch 而不是 computed？

A : watch 适合处理副作用（如数据加载），computed 适合计算返回值。

Q2: 为什么不在 watch 中重新初始化图表？

A: 重新初始化会丢失用户交互状态（缩放、高亮等），且性能较差。

Q3: 如何处理图表初始化失败？

A : 添加 try-catch，检查 DOM 元素是否存在，提供降级方案。

Q4: 多个图表如何管理？

A : 使用数组或对象存储多个 chartInstance，分别管理生命周期。

Q5: 如何实现点击图表项跳转？

A : 在 series 中添加 emphasis 和 select 配置，或使用 on('click', callback) 监听点击事件。

---

十、完整代码模板

<template>
  <div class="chart-card flex-1 min-h-0">
    <div class="card-title">商品前 10 名爆品占比</div>
    <div ref="chartRef" class="chart-dom"></div>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted, watch } from 'vue'
import * as echarts from 'echarts'

const props = defineProps({
  date: String,
  refreshKey: Number,
})

const chartRef = ref(null)
let chartInstance = null
let resizeTimer = null

const loadData = async () => {
  // 获取数据逻辑
  const mockData = [
    { value: 1200, name: '冷冻猪蹄' },
    { value: 1100, name: '新鲜菜心' },
    // ...
  ]

  if (chartInstance) {
    chartInstance.setOption({
      series: [{ data: mockData }]
    })
  }
}

const initChart = () => {
  chartInstance = echarts.init(chartRef.value, 'dark')
  chartInstance.setOption({
    backgroundColor: 'transparent',
    tooltip: { trigger: 'item', formatter: '{a} <br/>{b}: {c} ({d}%)' },
    legend: {
      type: 'scroll',
      orient: 'vertical',
      right: '2%',
      top: 'middle',
      textStyle: { color: '#9ca3af', fontSize: 10 },
      icon: 'circle',
      pageTextStyle: { color: '#fff' },
    },
    series: [{
      name: '数据',
      type: 'pie',
      radius: ['40%', '65%'],
      center: ['40%', '50%'],
      avoidLabelOverlap: true,
      itemStyle: { borderRadius: 8, borderColor: '#111827', borderWidth: 2 },
      label: {
        show: true,
        position: 'outside',
        color: '#9ca3af',
        fontSize: 10,
        formatter: '{b}: {c}'
      },
      labelLine: { show: true, length: 10, length2: 5 },
      data: [],
    }],
  })
  loadData()
}

const handleResize = () => {
  if (resizeTimer) clearTimeout(resizeTimer)
  resizeTimer = setTimeout(() => {
    chartInstance && chartInstance.resize()
  }, 150)
}

onMounted(() => {
  initChart()
  window.addEventListener('resize', handleResize)
})

onUnmounted(() => {
  window.removeEventListener('resize', handleResize)
  chartInstance && chartInstance.dispose()
  if (resizeTimer) clearTimeout(resizeTimer)
})
</script>

---

十一、总结

响应式图表开发的核心在于：

1. 正确的生命周期管理：初始化和销毁时的资源清理
2. 高效的响应式更新 ：使用 watch 和 setOption
3. 良好的用户体验：窗口大小变化时的自适应

通过本文的实践笔记，您可以快速上手 Vue 3 + ECharts 的响应式图表开发，构建专业的数据可视化应用。

---