ame-echarts-vue-component

一个基于 Vue 3 的 ECharts 组件库，提供按需加载功能，为 Vue 应用提供简单灵活的图表可视化解决方案。

功能特性

核心功能

• 按需加载：智能按需加载所需的 ECharts 组件和图表类型，显著减少打包体积
• 地图可视化：内置支持世界地图、中国地图和北京市地图的可视化展示
• 响应式设计：当容器尺寸变化时，图表会自动调整大小，适应不同的屏幕尺寸
• 完整的事件支持：提供丰富的事件系统，方便与图表交互
• Vue 3 组合式 API：完全兼容 Vue 3 的组合式 API，提供更好的开发体验

组件功能

• 高度可配置：支持 ECharts 的所有配置项，灵活定制图表样式和行为
• 实例访问：可直接访问 ECharts 实例，执行底层操作
• 懒加载地图数据：地图数据采用动态导入，减少初始加载时间
• 错误处理：内置完善的错误处理机制，提供更好的开发体验

安装

NPM 安装

npm install ame-echarts-vue-component echarts vue --save

Yarn 安装

yarn add ame-echarts-vue-component echarts vue

快速开始

全局注册

在你的应用入口文件（如 main.js）中进行全局注册：

import { createApp } from 'vue';
import AmeEchartsVueComponent from 'ame-echarts-vue-component';
import App from './App.vue';

const app = createApp(App);

// 全局注册组件
app.use(AmeEchartsVueComponent);

app.mount('#app');

局部导入

在需要使用的组件中进行局部导入：

import { EchartsComponent } from 'ame-echarts-vue-component';

在模板中使用

基础用法

<template>
  <div class="chart-wrapper">
    <EchartsComponent 
      ref="chartRef"
      :option="chartOption"
      :components="['LineChart', 'TitleComponent']"
      :style="{ width: '100%', height: '400px' }"
      @init="handleChartInit"
      @click="handleChartClick"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { EchartsComponent } from 'ame-echarts-vue-component';

// 图表引用，用于调用实例方法
const chartRef = ref(null);

// 图表配置项
const chartOption = {
  title: {
    text: '基础折线图示例',
    left: 'center'
  },
  tooltip: {
    trigger: 'axis'
  },
  xAxis: {
    type: 'category',
    data: ['周一', '周二', '周三', '周四', '周五', '周六', '周日']
  },
  yAxis: {
    type: 'value'
  },
  series: [{
    data: [120, 200, 150, 80, 70, 110, 130],
    type: 'line',
    smooth: true
  }]
};

// 处理图表初始化完成事件
const handleChartInit = (instance) => {
  console.log('图表初始化完成:', instance);
};

// 处理图表点击事件
const handleChartClick = (params) => {
  console.log('图表点击事件:', params);
};

// 手动更新图表
const updateChartData = () => {
  chartOption.series[0].data = [220, 300, 250, 180, 170, 210, 230];
  chartRef.value.updateChart();
};
</script>

<style scoped>
.chart-wrapper {
  width: 100%;
  height: 400px;
  margin: 20px 0;
}
</style>

使用地图功能

<template>
  <div class="map-wrapper">
    <EchartsComponent 
      :option="mapOption"
      :components="['MapChart', 'VisualMapComponent']"
      :maps="['china']"
      :style="{ width: '100%', height: '600px' }"
    />
  </div>
</template>

<script setup>
import { ref, reactive } from 'vue';
import { EchartsComponent } from 'ame-echarts-vue-component';

// 地图配置项
const mapOption = reactive({
  title: {
    text: '中国地图示例',
    left: 'center'
  },
  tooltip: {
    trigger: 'item',
    formatter: '{b}: {c}'
  },
  visualMap: {
    min: 0,
    max: 1000,
    text: ['高', '低'],
    realtime: false,
    calculable: true,
    inRange: {
      color: ['lightskyblue', 'yellow', 'orangered']
    }
  },
  series: [{
    name: '数据示例',
    type: 'map',
    map: 'china',
    roam: true,
    label: {
      show: true
    },
    emphasis: {
      label: {
        show: true,
        fontSize: 16
      },
      itemStyle: {
        areaColor: '#f0f'
      }
    },
    data: [
      { name: '北京', value: Math.random() * 1000 },
      { name: '上海', value: Math.random() * 1000 },
      { name: '广东', value: Math.random() * 1000 },
      // 更多数据...
    ]
  }]
});
</script>

<style scoped>
.map-wrapper {
  width: 100%;
  height: 600px;
  margin: 20px 0;
}
</style>

Props

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | option | Object | {} | ECharts 配置选项，详细配置参考 ECharts 官方文档 | | components | Array | ['LineChart', 'BarChart', 'PieChart', 'RadarChart', 'TitleComponent', 'TooltipComponent', 'GridComponent', 'LegendComponent', 'ToolboxComponent'] | 需要加载的 ECharts 组件列表，按需加载以减少体积 | | maps | Array | [] | 需要加载的地图数据列表，可选值：'world'、'china'、'beijing' | | initOptions | Object | {} | ECharts 初始化选项，如 renderer、useDirtyRect 等 | | style | Object | { width: '100%', height: '100%' } | 图表容器样式 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | init | chartInstance | 图表初始化完成时触发，返回 ECharts 实例 | | resize | - | 图表尺寸调整时触发 | | click | params | 图表点击时触发，返回点击参数 | | dataChange | - | 图表数据更新时触发 | | error | error | 图表加载或渲染出错时触发 |

暴露的方法

通过组件引用（ref）可以调用以下方法：

| 方法名 | 说明 | 参数 | |--------|------|------| | updateChart() | 使用新的 option 更新图表 | 无 | | resizeChart() | 调整图表大小以适应容器 | 无 | | getInstance() | 获取 ECharts 实例 | 无 | | disposeChart() | 销毁图表实例 | 无 |

开发指南

目录结构

├── src/                    # 源代码目录
│   ├── components/         # 组件目录
│   │   └── EchartsComponent.vue  # 主组件
│   ├── utils/              # 工具函数目录
│   │   ├── install.js      # 安装和按需加载逻辑
│   │   └── json/           # 地图数据目录
│   │       ├── world.json  # 世界地图数据
│   │       ├── china.json  # 中国地图数据
│   │       └── beijing.json # 北京地图数据
│   └── index.js           # 入口文件
├── dist/                   # 构建输出目录
├── package.json            # 包配置
├── vite.config.js          # Vite 配置
└── README.md              # 说明文档

构建

克隆仓库后，可以执行以下命令进行开发和构建：

# 安装依赖
npm install

# 构建包
npm run build

# 本地预览
npm run preview

构建后的文件将输出到 dist 目录，包含以下格式：

• ES Module: index.es.js
• UMD: index.umd.js

最佳实践

1. 按需加载组件：只加载需要的 ECharts 组件，以减少打包体积
2. 使用响应式数据：对于需要频繁更新的图表，使用 Vue 的响应式数据
3. 合理设置容器尺寸：为图表容器设置合适的宽高，避免频繁调整大小
4. 避免不必要的重绘：只在数据真正变化时更新图表

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。