zcglxt/CHARTS_QUICKSTART.md

# 图表组件快速开始指南

> 5分钟上手图表组件库

## 安装完成检查

图表组件库已集成到项目中，无需额外安装！

## 快速使用

### 1. 基础饼图

```vue
<template>
  <PieChart
    :data="data"
    title="资产状态分布"
    type="doughnut"
    height="400px"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { PieChart } from '@/components/charts'

const data = ref([
  { name: '库存中', value: 200 },
  { name: '在用', value: 750 },
  { name: '维修中', value: 50 },
])
</script>
```

### 2. 统计卡片

```vue
<template>
  <StatCard
    title="资产总数"
    :value="1000"
    unit="台"
    trend="up"
    :trend-value="12.5"
  />
</template>

<script setup lang="ts">
import { StatCard } from '@/components/statistics'
</script>
```

### 3. 柱状图

```vue
<template>
  <BarChart
    :data="data"
    title="资产分布"
    height="400px"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { BarChart } from '@/components/charts'

const data = ref([
  { name: '北京', value: 200 },
  { name: '上海', value: 180 },
  { name: '广州', value: 150 },
])
</script>
```

### 4. 折线图

```vue
<template>
  <LineChart
    :data="data"
    title="资产价值趋势"
    :area="true"
    height="400px"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { LineChart } from '@/components/charts'

const data = ref([
  { name: '1月', value: 850 },
  { name: '2月', value: 920 },
  { name: '3月', value: 980 },
])
</script>
```

### 5. 仪表盘

```vue
<template>
  <GaugeChart
    :value="75"
    title="资产利用率"
    unit="%"
    height="300px"
  />
</template>

<script setup lang="ts">
import { GaugeChart } from '@/components/charts'
</script>
```

## 常用场景

### 场景1：统计仪表盘

```vue
<template>
  <div class="dashboard">
    <!-- 统计卡片 -->
    <StatCardGroup :items="statCards" />

    <!-- 图表行 -->
    <el-row :gutter="16">
      <el-col :span="12">
        <PieChart :data="statusData" title="资产状态分布" />
      </el-col>
      <el-col :span="12">
        <BarChart :data="orgData" title="机构分布" />
      </el-col>
    </el-row>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { StatCardGroup, PieChart, BarChart } from '@/components/charts'

const statCards = ref([
  { title: '资产总数', value: 1000, unit: '台' },
  { title: '在用资产', value: 750, unit: '台' },
  { title: '库存资产', value: 200, unit: '台' },
  { title: '维修中', value: 50, unit: '台' },
])

const statusData = ref([
  { name: '库存中', value: 200, status: 'in_stock' },
  { name: '在用', value: 750, status: 'in_use' },
  { name: '维修中', value: 50, status: 'maintenance' },
])

const orgData = ref([
  { name: '北京', value: 200 },
  { name: '上海', value: 180 },
  { name: '广州', value: 150 },
])
</script>
```

### 场景2：业务图表

```vue
<template>
  <div>
    <AssetStatusChart :data="statusData" @click="handleClick" />
    <AssetUtilizationChart
      :total-assets="1000"
      :used-assets="750"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { AssetStatusChart, AssetUtilizationChart } from '@/components/charts'

const statusData = ref([
  { status: 'in_stock', statusName: '库存中', count: 200, percentage: 20, color: '#3b82f6' },
  { status: 'in_use', statusName: '在用', count: 750, percentage: 75, color: '#10b981' },
])

const handleClick = (item) => {
  console.log('点击了:', item)
}
</script>
```

### 场景3：数据加载

```vue
<template>
  <PieChart
    :data="data"
    :loading="loading"
    title="资产状态分布"
  />
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { PieChart } from '@/components/charts'
import { useChartData } from '@/composables/useChartData'

// 使用 Composable 管理数据
const { data, loading, loadData } = useChartData(fetchAssetStatus)

onMounted(() => {
  loadData()
})

async function fetchAssetStatus() {
  // 模拟 API 调用
  return [
    { name: '库存中', value: 200 },
    { name: '在用', value: 750 },
  ]
}
</script>
```

## API 导入

### 方式1：从图表模块导入

```typescript
import { PieChart, BarChart, LineChart } from '@/components/charts'
import { StatCard, StatCardGroup } from '@/components/statistics'
```

### 方式2：单独导入

```typescript
import PieChart from '@/components/charts/PieChart.vue'
import StatCard from '@/components/statistics/StatCard.vue'
```

### 方式3：导入工具函数

```typescript
import {
  formatNumber,
  formatCurrency,
  getAssetStatusColor,
} from '@/utils/echarts'
```

### 方式4：导入类型

```typescript
import type {
  ChartDataItem,
  PieChartConfig,
  StatCardConfig,
} from '@/types/charts'
```

## 查看示例

运行项目并访问：

```
http://localhost:5173/examples/charts
```

## 需要帮助？

- 详细文档：`CHARTS_README.md`
- 交付文档：`CHARTS_DELIVERY.md`
- 示例代码：`src/views/examples/ChartsExample.vue`

## 常见问题

**Q: 图表不显示？**
A: 确保设置了 `height` 属性

**Q: 如何自定义颜色？**
A: 设置 `custom-color=true`，并在数据中添加 `status` 字段

**Q: 如何处理大数据量？**
A: 设置 `show-data-zoom=true` 启用数据缩放

**Q: 如何导出图片？**
A: 使用 `useECharts` 的 `getDataURL` 方法

---

开始使用图表组件，让数据更美观！🎨📊