lz-echarts

基于 Vue3 + TypeScript 二次封装的 ECharts 6.0.0 图表组件库，支持多种图表类型和灵活的配置方式。

特性

• Vue3 + TypeScript：使用最新的 Vue3 组合式 API 和 TypeScript 类型定义
• ECharts 6.0.0：基于最新的 ECharts 6.0.0 版本
• 灵活配置：支持基础配置、图表配置和合并配置的多层级配置方式
• 多图表类型：支持柱状图、折线图等多种图表类型
• 响应式设计：自适应容器大小变化
• TypeScript 类型支持：完善的类型定义，提供良好的开发体验

安装

npm install lz-echarts

核心组件

基础组件

• MainChart：所有图表组件的基础组件，提供灵活的配置选项，可用于创建自定义图表

内置图表组件

• 柱状图：BarChart1、BarChart2、BarChart3、BarChart4、BarChart5、BarChart6、BarChart7、BarChart8、BarChart9、BarChart10、BarChart11、BarChart12、BarChart13
• 条形图：ColumnChart1、ColumnChart2、ColumnChart3、ColumnChart4、ColumnChart5、ColumnChart6、ColumnChart7、ColumnChart8、ColumnChart9、ColumnChart10、ColumnChart11、ColumnChart12、ColumnChart13
• 折线图：LineChart1、LineChart2、LineChart3、LineChart4

MainChart 基础组件使用说明

MainChart 是 lz-echarts 库的核心基础组件，所有内置图表组件都基于此组件构建。它提供了灵活的配置方式，支持多种图表类型和多层级配置管理。

组件参数

| 参数 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| | theme | string | 否 | 'dark' | 图表主题，支持 ECharts 内置主题 | | baseConfig | string | 否 | '' | 基础配置文件名称 | | baseSwapXY | boolean | 否 | false | 是否对调baseConfig的xy轴配置。使用说明：开启后，baseConfig中的x轴和y轴配置会互换位置，此时需要确保mergeConfig和chartList中的配置也按照互换后的轴结构进行设置，以保持图表配置的一致性 | | chartList | Array<ChartItem> | 是 | - | 图表列表配置，包含一个或多个图表的详细信息 | | mergeConfig | EChartsOption | 否 | - | 合并配置，用于覆盖默认配置，优先级最高 |

ChartItem 类型定义

interface ChartItem {
  type: string;         // 图表类型，如 'bar'、'line' 等
  configName?: string;  // 图表配置文件名称
  data: DataItem[];     // 图表数据数组
  name?: string;        // 图表名称，用于图例显示
  isHide?: boolean;     // 是否隐藏该图表
  [key: string]: any;   // 其他自定义属性，可用于扩展功能
}

DataItem 类型定义

interface DataItem {
  name: string;  // 数据项名称，如类别名称
  value: number; // 数据项值，如数值大小
}

使用示例

基础用法

最简单的使用方式，直接提供图表类型和数据：

<template>
  <div class="chart-container" style="width: 100%; height: 400px;">
    <MainChart
      :chartList="chartList"
    />
  </div>
</template>

<script setup lang="ts">
import { MainChart } from 'lz-echarts';

const chartList = [
  {
    type: 'bar',
    data: [
      { name: '产品A', value: 35 },
      { name: '产品B', value: 25 },
      { name: '产品C', value: 20 },
      { name: '产品D', value: 15 },
      { name: '其他', value: 5 }
    ],
    name: '销售数据'
  }
];
</script>

使用配置文件

通过配置文件定义图表样式，实现样式与逻辑分离：

<template>
  <div class="chart-container" style="width: 100%; height: 400px;">
    <MainChart
      baseConfig="BASE001"
      :chartList="chartList"
    />
  </div>
</template>

<script setup lang="ts">
import { MainChart } from 'lz-echarts';

const chartList = [
  {
    type: 'bar',
    configName: 'BAR001',
    data: [
      { name: '产品A', value: 35 },
      { name: '产品B', value: 25 },
      { name: '产品C', value: 20 },
      { name: '产品D', value: 15 },
      { name: '其他', value: 5 }
    ],
    name: '销售数据'
  }
];
</script>

使用合并配置

通过 mergeConfig 直接覆盖默认配置，实现细粒度的样式调整：

<template>
  <div class="chart-container" style="width: 100%; height: 400px;">
    <MainChart
      :chartList="chartList"
      :mergeConfig="mergeConfig"
    />
  </div>
</template>

<script setup lang="ts">
import { MainChart } from 'lz-echarts';

const chartList = [
  {
    type: 'bar',
    data: [
      { name: '产品A', value: 35 },
      { name: '产品B', value: 25 },
      { name: '产品C', value: 20 },
      { name: '产品D', value: 15 },
      { name: '其他', value: 5 }
    ],
    name: '销售数据'
  }
];

const mergeConfig = {
  title: {
    text: '产品销售统计',
    left: 'center',
    textStyle: {
      color: '#fff'
    }
  },
  tooltip: {
    trigger: 'axis',
    axisPointer: {
      type: 'shadow'
    }
  },
  grid: {
    left: '3%',
    right: '4%',
    bottom: '3%',
    containLabel: true
  }
};
</script>

多图表组合

在同一个容器中展示多种类型的图表：

<template>
  <div class="chart-container" style="width: 100%; height: 500px;">
    <MainChart
      :chartList="chartList"
    />
  </div>
</template>

<script setup lang="ts">
import { MainChart } from 'lz-echarts';

const chartList = [
  {
    type: 'bar',
    configName: 'BAR001',
    data: [
      { name: '产品A', value: 35 },
      { name: '产品B', value: 25 },
      { name: '产品C', value: 20 },
      { name: '产品D', value: 15 },
      { name: '其他', value: 5 }
    ],
    name: '柱状图数据'
  },
  {
    type: 'line',
    configName: 'LINE001',
    data: [
      { name: '产品A', value: 40 },
      { name: '产品B', value: 30 },
      { name: '产品C', value: 25 },
      { name: '产品D', value: 20 },
      { name: '其他', value: 10 }
    ],
    name: '折线图数据'
  }
];
</script>

配置说明

MainChart 组件支持通过配置文件管理图表样式，配置文件是内置的，用户只需要知道对应的配置名称即可。

配置名称列表

所有可用的配置名称及其描述请参考 CONFIG.md 文件。

工作原理

MainChart 组件的工作流程如下：

1. 配置加载：根据 baseConfig 和 chartList 中的 configName 加载对应的内置配置
2. 配置合并：将基础配置、图表配置和 mergeConfig 进行深度合并，生成最终的图表配置
3. 数据处理：从 chartList 中提取数据，转换为 ECharts 所需的格式
4. 图表初始化：创建 ECharts 实例并应用最终配置
5. 响应式调整：监听容器大小变化，自动调整图表尺寸

注意事项

1. 容器大小：必须为 MainChart 组件提供明确的容器大小（宽度和高度），否则图表可能无法正确渲染
2. 数据格式：chartList 中的每个图表对象必须包含 type 和 data 属性，且 data 数组必须符合 DataItem 接口定义
3. 配置文件：如果指定了 baseConfig 或 configName，确保使用的配置名称在 配置文件说明 中存在
4. 主题：默认主题为 "dark"，如需使用其他主题，请确保已在项目中引入对应的主题文件
5. 性能优化：对于复杂图表或大量数据，建议使用具体的内置图表组件，它们已经针对特定场景进行了优化

最佳实践

1. 基础图表：对于简单的图表需求，直接使用 MainChart 并提供必要的 chartList 即可
2. 样式定制：优先使用配置文件管理样式，其次使用 mergeConfig 进行局部调整
3. 多图表展示：通过在 chartList 中添加多个图表对象，实现多图表组合展示
4. 复杂场景：对于复杂的图表场景，考虑使用库中提供的内置图表组件，它们已经封装了常见的图表样式和配置
5. 响应式设计：将 MainChart 放置在响应式容器中，图表会自动适应容器大小变化

详细文档

• 配置文件说明
• 柱状图组件
• 条形图组件
• 折线图组件

开发指南

安装依赖

npm install

运行示例

cd examples && npm install && npm run dev

构建项目

npm run build

类型检查

npm run type-check

许可证

MIT