# 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: '232px',
    height: '160px',
  }"
  :pieImageConfig="{
    top: '0%',
    left: '5%',
    bounding: 'raw',
    origin: [0.5, 0.5],
    scale: [1, 1],
  }"
  :pieImageStyle="{
    opacity: 0.8,
    width: 200,
    height: 150,
    rotate: -12,
  }"
  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组件',
  ]"
  style="height: 300px;"
  :svgWidth="1000"
  :svgHeight="300"
  :RADIUSY="120"
/>
```

## 开发和构建

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build
```

## 许可证

MIT
