ksg-echarts 简单好用的 vue3 图表库

ksg-echarts 是基于 Vue3.x 与 ECharts5.x 构建封装的组件库，用以解决繁杂的 ECharts 配置项以及初始化echarts带来的烦恼，开箱即用。，开发者可以快速构建出适合自身业务需求的图表组件，无需每次都从头开始编写echarts的配置项，大大提高了开发效率。ksg-echarts可以对echarts的默认配置进行统一设置,如字体、颜色、交互等,使得整个系统中的图表组件保持一致的视觉风格。使用 ksg-echarts 生成图表时，用户只需关心数据与配置项，甚至无需配置项，即可生成一个默认的图表，使用 ksg-echarts 可以帮助你更快捷、更高效的构建图表。

快速上手

我们提供了 ksg-echarts npm 包，通过下面命令即可完成安装，ksg-echarts 依赖于 echarts，所以不要忘记安装依赖包。

sh 复制代码

npm i ksg-echarts echarts -S

ksg-echarts 提高两种引入方式：全局引用与按需加载。

完整引入 ksg-echarts

js 复制代码

import Vue from 'vue'
import KsgEcharts from 'ksg-echarts'

Vue.use(KsgEcharts)

按需引入 ksg-echarts

js 复制代码

import Vue from 'vue'
import { KsgPieChart } from 'ksg-echarts'  // 引入单个图表

Vue.component('KsgPieChart', KsgPieChart)

基本属性

ksg-Echarts 组件的基本属性包括数据与配置项。采用数据与配置相互隔离的概念, 因为配置项基本是保持不变的，而经常改变的是数据，将这两者分开，更好的方便用户只关心数据。这在业务实际开发中是比较重要的一点。

另一方面组件内置了很多默认的配置，这可以减少echarts过多的配置，增加用户上手难度，当然配置也是可以在外部通过option重新设置，覆盖式更新，这样能兼容一些定制化的业务场景。

配置项和 echarts 配置保持一致，可参考 👉 echarts配置项

vue 复制代码

<ksg-pie-chart
  :data="chartData"      // 数据
  :option="chartoption"  // echarts图表配置
/>

ksg-Echarts 的数据设计采用对象数组的形式，这对后端来说是十分友好的。避免了过多数据聚合的逻辑，所见即所得.

需要注意的一点是，对象的首字段为我们的类目轴对应到 dataset 第一列

例如：

js 复制代码

const chartData = [
  { channel: '移动设备', pv1: 150000, },
  { channel: 'PC', pv1: 90000 },
  { channel: 'APP', pv: 40000, },
  { channel: 'PC', pv: 30000 },
  { channel: 'M端', pv: 20000 },
  { channel: '微信', pv: 50000 },
  { channel: '手Q', pv: 10000, },
  { channel: '小程序', pv: 90000 },
];

基本图表

ksg-echarts 目前内置了折线图、柱状图、饼图三种常见图表，可以通过单独引用的方式导入

sh 复制代码

import { KsgPieChart, KsgLineChart, KsgBarChart } from 'ksg-echarts'

通过内置的组件用户可以更快速使用，具体配置项可参考具体的案例：折线图👉：文档柱状图👉：文档饼图👉：文档

useKsgChart 方式

ksg-echarts 提供了 hooks 的使用方式，方便用户手动设置图表的一些属性。详细描述

sh 复制代码

import { useKsgChart } from 'ksg-echarts'

useKsgChart 是一个基础的 hooks，对所有的图表都适用，其中返回两个函数 setChartData, setOptions:

setChartData：设置图表的值
setOptions：设置图表的配置options

useKsgChart 接收两个参数，一个是组件的实例（必填），另一个是初始化图表的配置（可选）

js 复制代码

const { setChartData, setOptions } = useKsgChart(chartRef, {
  title: {
    text: '初始化title',
  }
})

注意：第二个参数不具备依赖响应，尽量避开响应式数据，如果有动态需求，请使用setOptions

setOptions 是在组件初始化之后调用 Echarts 的 setOption 方法，所以使用之前确保图表实例已经生成，另外setOptions参数只支持 Echarts 的配置项，无法解析各组件自定义的api

自定义图表

对于复杂或者 ksg-echarts 组件库无法满足的图表，可以使用自定义图表功能。详细描述

ksg-echarts 提供了基础图表 KsgBaseChart 组件，各图表组件也是基于这基础上进一步封装 options。因此，可以通过配置option的参数来自定义图表实现自己的效果。

javascript 复制代码

import { KsgBaseChart } from 'ksg-echarts'

如下案例中是自定义漏斗图代码，其中我们只需要传递给 echarts 的配置 option 即可渲染自定义图表。

vue 复制代码

<template>
  <ksg-base-chart :option="option" />
</template>
<script setup>
import { ref } from 'vue';
import { FunnelChart } from 'echarts/charts';
import { use } from 'echarts/core';
use([FunnelChart]); // 注册漏斗图
const option = ref({
  series: [{
    name: 'Funnel',
    type: 'funnel',
    data: [
      { value: 60, name: 'Visit' },
      { value: 40, name: 'Inquiry' },
      { value: 20, name: 'Order' },
      { value: 80, name: 'Click' },
      { value: 100, name: 'Show' }
    ]
  }]
})
</script>

组合图表

在开发过程中，我们往往会经常将多个图表绘制在一起，这就需要采用组合图表的方式。详细描述

组合图表并不需要其他特俗的设置，一般通过设置 options 的 series 即可做到，可以参考下面案例：

vue 复制代码

<template>
  <ksg-line-chart :data="chartData" :option="option" />
</template>
<script setup>
import { onMounted, ref, nextTick } from 'vue';
import { BarChart } from 'echarts/charts';
import { use } from 'echarts/core';
use([BarChart]);
const chartData = ref([
  { week: 'Mon', vue: 3000, react: 2000, Angular: 827 },
  { week: 'Tue', vue: 3500, react: 2000, Angular: 949 },
  { week: 'Wed', vue: 3900, react: 2600, Angular: 1400 },
  { week: 'Thu', vue: 3100, react: 2300, Angular: 1000 },
  { week: 'Fir', vue: 3200, react: 2300, Angular: 884 },
  { week: 'Sat', vue: 3100, react: 2000, Angular: 911 },
  { week: 'Sun', vue: 3600, react: 2600 , Angular: 983 }
])
const option = ref({
  series: [
    {
      itemStyle: { color: 'green' },
    }, 
    {
      showSymbol: false,
      lineStyle: { type: 'dotted' }
    },
    {
      type: 'bar'
    }
  ]
})
</script>

这是折线图和柱状图结合，案例中我们在 ksg-line-chart 设置了一个柱状图，所以需要先 use([BarChart]) 才能用，series 是一个数组，根据 data 的数据自定生成的，用户可以自定义每一个 series，这样就可以将多个图表整合在一起。如案例中设置了Angular的 type: 'bar' 即可展示柱状图