# Vue ECharts 3D Components

一组基于Vue 3和ECharts的可视化组件库，提供丰富的图表组件供您在项目中使用。

## 组件列表

- **PieEcharts**: 3D饼图组件，支持自定义图片背景和图例位置
- **WordCloud**: 3D词云组件，支持自定义标签、样式和动画
- **RankingList**: 排名列表组件，支持自定义图标、进度条和滚动加载

## 安装

```bash 
npm install vue-echarts-3d-components
```

## 依赖

该组件库依赖以下库：

- Vue 3
- ECharts 5.x
- echarts-gl (用于3D效果)
- echarts-wordcloud (用于词云效果)

请确保在使用前安装这些依赖：

```bash
npm install vue echarts echarts-gl echarts-wordcloud
```

## 使用方法

### 全局注册

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import VueEcharts3DComponents from 'vue-echarts-3d-components'
import 'vue-echarts-3d-components/dist/style.css'

const app = createApp(App)
app.use(VueEcharts3DComponents)
app.mount('#app')
```

### 局部引入

```javascript
import { PieEcharts, WordCloud } from 'vue-echarts-3d-components'
import 'vue-echarts-3d-components/dist/style.css'

export default {
  components: {
    PieEcharts,
    WordCloud
  }
}
```

## 组件详情

### RankingList 排名列表组件

#### Props

- **rankingData**: 排名数据数组（必填）
  - 数据结构: `Array<Object>`，每个对象必须包含label（标签文本）和value（数值）属性
  - 示例: 
    ```javascript
    [
      { label: '项目1', value: 85 },
      { label: '项目2', value: 72 },
      { label: '项目3', value: 95 }
    ]
    ```

- **showRankIcon**: 是否显示排名图标
  - 数据类型: `Boolean`
  - 默认值: `true`

- **rankIcons**: 自定义排名图标数组
  - 数据类型: `Array<String>`
  - 默认值: 系统默认图标数组
  - 说明: 当showRankIcon为true时有效，用于自定义排名图标

- **maxShowCount**: 最大显示条数
  - 数据类型: `Number | null | undefined`
  - 默认值: `10`
  - 说明: 限制组件显示的数据条数，为null或undefined时显示全部数据并支持滚动加载

- **total**: 自定义基数
  - 数据类型: `Number`
  - 默认值: `0`
  - 验证: 必须为非负数
  - 说明: 当percentMode为'total'时使用此值作为计算百分比的分母

- **percentMode**: 百分比计算模式
  - 数据类型: `String`
  - 默认值: `'max'`
  - 可选值: `'max'`, `'sum'`, `'total'`
  - 说明: 
    - 'max': 基于数据列表中的最大值计算百分比
    - 'sum': 基于数据列表中所有值的总和计算百分比
    - 'total': 基于自定义基数(total)计算百分比

- **progressColors**: 进度条颜色配置对象
  - 数据类型: `Object`
  - 默认值: 
    ```javascript
    {
      bar: 'rgba(99, 195, 255, 0.08)', // 进度条背景色
      fill: 'linear-gradient(270deg, rgba(5, 105, 255, 0.4983) 0%, #01E8FE 100%)', // 进度条填充背景色（支持渐变格式）
      line: '#EEFEFF' // 进度条线条背景色
    }
    ```
  - 优先级: 高于theme配置

- **textStyle**: 文本样式配置对象
  - 数据类型: `Object`
  - 默认值: 
    ```javascript
    {
      label: { fontSize: '16px', color: '#E2E8FF' }, // 标签文本样式
      value: { fontSize: '18px', color: '#FFFFFF' }  // 数值文本样式
    }
    ```
  - 优先级: 高于theme配置

- **theme**: 主题配置对象
  - 数据类型: `Object`
  - 默认值: 
    ```javascript
    {
      container: {
        backgroundColor: '#0c264c',
        scrollbarColor: '#1890ff'
      },
      progress: {
        first: '#ffd700',  // 第一名颜色
        second: '#c0c0c0', // 第二名颜色
        third: '#cd7f32'   // 第三名颜色
      },
      text: {
        primary: '#FFFFFF',
        secondary: '#E2E8FF'
      }
    }
    ```
  - 说明: 用于全局配置组件样式，优先级低于progressColors/textStyle

#### 示例

```vue
<RankingList 
  :rankingData="[
    { label: '项目A', value: 95 },
    { label: '项目B', value: 88 },
    { label: '项目C', value: 76 },
    { label: '项目D', value: 65 },
    { label: '项目E', value: 52 }
  ]"
  :showRankIcon="true"
  :maxShowCount="5"
  :total="500"
  percentMode="max"
  :progressColors="{
    bar: 'rgba(99, 195, 255, 0.08)',
    fill: 'linear-gradient(270deg, rgba(5, 105, 255, 0.4983) 0%, #01E8FE 100%)',
    line: '#EEFEFF'
  }"
  :textStyle="{
    label: { fontSize: '16px', color: '#E2E8FF' },
    value: { fontSize: '18px', color: '#FFFFFF' }
  }"
  :theme="{
    container: {
      backgroundColor: '#0c264c',
      scrollbarColor: '#1890ff'
    }
  }"
/>
```

#### 事件

- **load-more**: 滚动到底部触发的加载更多事件
  - 当maxShowCount为null或undefined时，组件可滚动，滚动到底部会触发此事件
  - 可以在父组件中监听此事件，用于实现分页加载功能

### PieEcharts 3D饼图组件

这是一个集成了饼图和图例的完整可视化组件，基于ECharts GL实现3D效果。

#### Props

- **pieData**: 饼图数据数组
  - 数据结构: `Array<{name: string, value: number, color?: string, itemStyle?: object}>`
  - 默认值: `[]`

- **pieStyle**: 饼图容器样式配置
  - 数据结构: `Object`
  - 默认值: `{width: '232px', height: '160px'}`
  - 说明: 控制饼图容器的宽高

- **pieImageConfig**: 饼图背景图片位置配置
  - 数据结构: `Object`
  - 默认值: 
    ```javascript
    {
      top: '12%',    // 垂直位置
      left: '5%',    // 水平位置
      bounding: 'raw', // 边界计算方式
      origin: [0.5, 0.5], // 旋转中心点
      scale: [1.05, 1.05] // 缩放比例
    }
    ```

- **pieImageStyle**: 饼图背景图片样式配置
  - 数据结构: `Object`
  - 默认值: 
    ```javascript
    {
      image: null,   // 图片URL，为null时使用默认图片
      opacity: 0.8,  // 透明度
      width: 200,    // 宽度
      height: 150,   // 高度
      rotate: -12    // 旋转角度
    }
    ```

- **legendPosition**: 图例位置
  - 数据类型: `String`
  - 默认值: `'right'`
  - 可选值: `'top'`, `'bottom'`, `'left'`, `'right'`

- **legend**: 是否显示图例
  - 数据类型: `Boolean`
  - 默认值: `true`

- **legendText**: 是否显示图例文本（分类名称）
  - 数据类型: `Boolean`
  - 默认值: `true`

- **legendTextColor**: 图例文本颜色
  - 数据类型: `String`
  - 默认值: `'#333333'`

- **legendTextSize**: 图例文本字体大小
  - 数据类型: `Number | String`
  - 默认值: `16`
  - 支持格式: 数字或带单位的字符串（如 '16px', '1rem'）

- **legendValue**: 是否显示图例数值（原始数据值）
  - 数据类型: `Boolean`
  - 默认值: `true`

- **legendValueColor**: 图例数值颜色
  - 数据类型: `String`
  - 默认值: `'#1A1A1A'`

- **legendValueSize**: 图例数值字体大小
  - 数据类型: `Number | String`
  - 默认值: `20`
  - 支持格式: 数字或带单位的字符串（如 '20px', '1.25rem'）

- **legendPercent**: 是否显示图例百分比
  - 数据类型: `Boolean`
  - 默认值: `true`

- **legendPercentColor**: 图例百分比颜色
  - 数据类型: `String`
  - 默认值: `'#1A1A1A'`

- **legendPercentSize**: 图例百分比字体大小
  - 数据类型: `Number | String`
  - 默认值: `20`
  - 支持格式: 数字或带单位的字符串（如 '20px', '1.25rem'）

- **colorList**: 颜色配置列表
  - 数据类型: `Array<String>`
  - 默认值: 
    ```javascript
    [
      '#0A89FF', '#28FFD9', '#7366FF', '#FFDC2F', '#FF6F11',
      '#FF3A1F', '#06FE94', '#83A8FF', '#9FE4FF', '#CA9DFF',
      '#FFBC8E', '#FFF073', '#C3FF8E', '#FF9D4F', '#FF6F4F'
    ]
    ```

- **sortOrder**: 数据排序方式
  - 数据类型: `String`
  - 默认值: `'desc'`
  - 可选值: `'asc'` (按数值从小到大升序排列), `'desc'` (按数值从大到小降序排列)
  - 说明: 控制饼图数据的排序方式

- **pieHeight**: 饼图高度
  - 数据类型: `Number`
  - 默认值: 根据数据排序自动计算
  - 说明: 自定义饼图的高度，不设置时根据排序自动计算

#### 示例

```vue
<PieEcharts 
  :pieData="[
    {
      name: '类别1',
      value: 30,
      color: '#FF6F4F' // 可选，指定该数据项的颜色
    }, 
    {
      name: '类别2',
      value: 50
    }, 
    {
      name: '类别3',
      value: 20
    }
  ]"
  :pieStyle="{
    width: '300px',
    height: '200px'
  }"
  :pieImageConfig="{
    top: '10%',
    left: 'center',
    scale: [1.1, 1.1]
  }"
  :pieImageStyle="{
    image: '/path/to/custom-image.png',
    opacity: 0.7,
    width: 180,
    height: 120,
    rotate: -12
  }"
  sortOrder="desc"
  :pieHeight="15"
  legendPosition="right"
  :legendText="true"
  :legendValue="true"
  :legendPercent="true"
  legendTextColor="#666666"
  :legendTextSize="14"
/>

```

### WordCloud 3D词云组件

#### Props

- `svgWidth`: SVG容器宽度，默认580
- `svgHeight`: SVG容器高度，默认580
- `RADIUSX`: 球半径X轴，默认240
- `RADIUSY`: 球半径Y轴，默认240
- `RADIUSZ`: 球半径Z轴，默认240
- `tagsTemp`: 标签数据，格式为字符串数组
- `rotateType`: 旋转方式，可选值：'x'（绕X轴旋转）、'y'（绕Y轴旋转）、'both'（同时旋转），默认'y'
- `gradientType`: 标签背景渐变色，数组格式：['#009fff', '#002255']或['rgb(0,159,255)', 'rgb(0,34,85)']，默认['rgb(0,159,255)', 'rgb(0,34,85)']
- `fontColor`: 标签字体颜色，默认'#FFFFFF'
- `fontSize`: 标签字体大小，默认18
- `mouseOver`: 鼠标移入球是否停止旋转，默认true
- `defaultSpeedX`: X轴默认旋转速度，默认Math.PI / 360
- `defaultSpeedY`: Y轴默认旋转速度，默认Math.PI / 360

#### 示例

```vue
<WordCloud 
  :tagsTemp="[
    'Vue',
    'ECharts',
    '3D可视化',
    '词云',
    '数据可视化',
    '前端开发',
    'JavaScript',
    'Vue组件'
  ]"
  :rotateType="'both'"
  :gradientType="['#ff6b6b', '#ee5a24']"
  :fontSize="16"
  :svgWidth="600"
  :svgHeight="600"
/>
```

## 开发和构建

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build
```

## 许可证

MIT