cxc-szcx-uniapp/uni_modules/cxc-szcx-lineChart/readme.md

cxc-szcx-lineChart

# line-chart.vue 组件说明书

一、组件概述

line-chart.vue 是一个基于 ECharts 实现的折线图组件，用于在 UniApp 项目中展示数据的折线图。该组件接收一系列数据和配置参数，支持动态更新数据，并展示参考线。

二、组件依赖

• Vue 3：使用 Vue 3 的组合式 API 进行开发。
• ECharts：用于绘制折线图。
• lime-echart：UniApp 插件，提供 ECharts 的渲染支持。

三、组件使用方法

1. 引入组件

在需要使用该组件的页面中引入 line-chart.vue 组件。

<template>
  <view>
    <line-chart 
      :dataList="dataList"
      :xField="xField"
      :yField="yField"
      :legendField="legendField"
      :referenceValue="referenceValue"
    />
  </view>
</template>

<script setup>
import LineChart from '@/components/line-chart.vue';

const dataList = [
  { date: '2023-01-01', value: 10, category: 'A' },
  // 更多数据...
];
const xField = 'date';
const yField = 'value';
const legendField = 'category';
const referenceValue = 15;
</script>

2. 组件属性

属性名	类型	默认值	描述
dataList	Object	[]	包含图表数据的数组，每个元素是一个对象，包含 xField、yField 和 legendField 对应的数据。
xField	String	''	数据中用于表示 x 轴的字段名。
yField	String	''	数据中用于表示 y 轴的字段名。
legendField	String	''	数据中用于表示图例的字段名。
referenceValue	Number	10	图表中参考线的数值。

四、组件内部实现

1. 模板部分

<template>
  <view class="chart-container">
    <l-echart ref="chart" @init="initChart"></l-echart>
  </view>
</template>

• 使用 l-echart 组件渲染图表，通过 ref 绑定到 chart，并在初始化完成时调用 initChart 方法。

2. 脚本部分

2.1 引入必要的模块

import { ref, watch } from 'vue';

引入 Vue 3 的 ref 和 watch 函数。

2.2 定义组件属性

const props = defineProps({
  dataList: {
    type: Object,
    default: () => []
  },
  // 其他属性...
});

定义组件接收的属性。

2.3 初始化图表

const chart = ref(null);
let echarts = null;

const initChart = async (canvas) => {
  await initEcharts(canvas);
  updateChart();
};

const initEcharts = async (canvas) => {
  echarts = await import('echarts');
  const { init } = await import('@/uni_modules/lime-echart/static/echarts.min');
  echarts = init(canvas, echarts);
};

• chart 用于引用 l-echart 组件。
• initChart 方法在图表初始化时调用，先初始化 ECharts 实例，再更新图表。
• initEcharts 方法异步加载 ECharts 并初始化实例。

2.4 处理数据

const processData = () => {
  const legendData = [...new Set(props.dataList.map((item) => item[props.legendField]))];

  return legendData.map((legendItem) => {
    const seriesData = props.dataList
     .filter((item) => item[props.legendField] === legendItem)
     .sort((a, b) => new Date(a[props.xField]) - new Date(b[props.xField]))
     .map((item) => ({
        name: item[props.xField],
        value: [item[props.xField], item[props.yField]]
      }));

    return {
      name: legendItem,
      type: 'line',
      showSymbol: true,
      data: seriesData
    };
  });
};

处理传入的数据，根据 legendField 分组，对每组数据按 xField 排序，并转换为 ECharts 所需的格式。

2.5 获取图表配置

const getOption = () => ({
  tooltip: {
    trigger: 'axis',
    formatter: (params) => {
      return `${params[0].axisValue}<br/>` + params.map((item) => `${item.marker} ${item.seriesName}: ${item.value[1]}`).join('<br/>');
    }
  },
  // 其他配置...
});

返回 ECharts 的配置对象，包括 tooltip、x 轴、y 轴、系列数据、图例和网格等配置。

2.6 更新图表

const updateChart = () => {
  if (!chart.value) return;

  const option = getOption();
  chart.value.setOption(option);
};

如果 chart 实例存在，获取最新的图表配置并更新图表。

2.7 监听数据变化

watch(
  () => props.dataList,
  () => {
    updateChart();
  },
  { deep: true }
);

当 props.dataList 发生变化时，调用 updateChart 方法更新图表。

3. 样式部分

.chart-container {
  width: 100%;
  height: 30vh;
}

设置图表容器的宽度为 100%，高度为 30vh。

五、注意事项

• 确保项目中已经正确安装并配置了 lime-echart 插件。
• 传入的 dataList 数据格式要符合要求，包含 xField、yField 和 legendField 对应的数据。
• 由于使用了异步加载 ECharts，可能会有一定的延迟，需要确保在合适的时机初始化图表。