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` 组件。
```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. 模板部分
```vue
<template>
  <view class="chart-container">
    <l-echart ref="chart" @init="initChart"></l-echart>
  </view>
</template>
```
- 使用 `l-echart` 组件渲染图表，通过 `ref` 绑定到 `chart`，并在初始化完成时调用 `initChart` 方法。

### 2. 脚本部分

#### 2.1 引入必要的模块
```javascript
import { ref, watch } from 'vue';
```
引入 Vue 3 的 `ref` 和 `watch` 函数。

#### 2.2 定义组件属性
```javascript
const props = defineProps({
  dataList: {
    type: Object,
    default: () => []
  },
  // 其他属性...
});
```
定义组件接收的属性。

#### 2.3 初始化图表
```javascript
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 处理数据
```javascript
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 获取图表配置
```javascript
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 更新图表
```javascript
const updateChart = () => {
  if (!chart.value) return;

  const option = getOption();
  chart.value.setOption(option);
};
```
如果 `chart` 实例存在，获取最新的图表配置并更新图表。

#### 2.7 监听数据变化
```javascript
watch(
  () => props.dataList,
  () => {
    updateChart();
  },
  { deep: true }
);
```
当 `props.dataList` 发生变化时，调用 `updateChart` 方法更新图表。

### 3. 样式部分
```css
.chart-container {
  width: 100%;
  height: 30vh;
}
```
设置图表容器的宽度为 100%，高度为 30vh。

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