# ame-echarts-vue-component

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

## 功能特性

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

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

## 安装

### NPM 安装

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

### Yarn 安装

```bash
yarn add ame-echarts-vue-component echarts vue
```

## 快速开始

### 全局注册

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

```javascript
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');
```

### 局部导入

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

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

## 在模板中使用

### 基础用法

```vue
<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>
```

### 使用地图功能

```vue
<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 官方文档](https://echarts.apache.org/zh/option.html) |
| `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              # 说明文档
```

### 构建

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

```bash
# 安装依赖
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 来改进这个项目。