RayChart

Appearance

快速上手 ​

5 分钟创建你的第一个 3D 图表。

💡 新手路线

  1. 本页面 - 快速上手（5 分钟）
  2. 图表配置 - 配置选项（10 分钟）
  3. 最佳实践 - 最佳用法（15 分钟）

1. 安装 ​

bash
npm install raychart
bash
yarn add raychart
bash
pnpm add raychart

⚠️ 注意

RayChart 需要 Vue 3.0+ 和支持 WebGL 的浏览器。

2. 引入组件 ​

RayChart 提供语义化组件，一眼就知道是什么图表：

javascript
import { RayBar, RayLine, RayPie, RayRadar, RayScatter3D, RayLiquid } from 'raychart'
import 'raychart/dist/raychart.css'  // ⚠️ 必须导入 CSS
📦 可用的图表组件
  • RayBar - 3D 柱状图
  • RayLine - 3D 折线图
  • RayPie - 3D 饼图
  • RayRadar - 3D 雷达图
  • RayScatter3D - 3D 散点图
  • RayLiquid - 3D 水球图
  • RayMap3D - 3D 地图

3. 创建第一个图表 ​

最简示例 ​

只需提供数据，光照、颜色等都自动配置：

vue
<template>
  <RayBar :option="chartOption" />
</template>

<script setup>
import { ref } from 'vue'
import { RayBar } from 'raychart'
import 'raychart/dist/raychart.css'

const chartOption = ref({
  series: [{
    data: [120, 200, 150, 80, 70, 110, 130]
  }],
  xAxis3D: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  }
})
</script>

✨ 就这么简单

自动配置：

  • ✅ 专业光照
  • ✅ 美观配色
  • ✅ 流畅交互
  • ✅ 响应式尺寸

自定义尺寸 ​

vue
<template>
  <!-- 方式 1：使用 props -->
  <RayBar :option="chartOption" width="800px" height="500px" />
  
  <!-- 方式 2：使用容器样式 -->
  <div style="width: 800px; height: 500px">
    <RayBar :option="chartOption" />
  </div>
</template>

📏 容器高度

确保图表容器有明确的高度，否则图表可能不显示。

4. 使用其他图表类型 ​

折线图 ​

vue
<template>
  <RayLine :option="chartOption" />
</template>

<script setup>
import { ref } from 'vue'
import { RayLine } from 'raychart'

const chartOption = ref({
  series: [{
    data: [120, 200, 150, 80, 70, 110, 130]
  }],
  xAxis3D: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  }
})
</script>

饼图 ​

vue
<template>
  <RayPie :option="chartOption" />
</template>

<script setup>
import { ref } from 'vue'
import { RayPie } from 'raychart'

const chartOption = ref({
  series: [{
    data: [
      { name: 'A', value: 335 },
      { name: 'B', value: 310 },
      { name: 'C', value: 234 }
    ]
  }]
})
</script>

💡 数据格式

饼图需要使用对象数组格式，包含 name 和 value 字段。

雷达图 ​

vue
<template>
  <RayRadar :option="chartOption" />
</template>

<script setup>
import { ref } from 'vue'
import { RayRadar } from 'raychart'

const chartOption = ref({
  series: [{
    data: [80, 90, 70, 85, 95]
  }],
  radar: {
    indicator: [
      { name: '销售', max: 100 },
      { name: '管理', max: 100 },
      { name: '技术', max: 100 },
      { name: '支持', max: 100 },
      { name: '研发', max: 100 }
    ]
  }
})
</script>

5. 进阶配置（可选） ​

需要自定义光照、材质时：

vue
<template>
  <div class="chart-container">
    <RayBar :option="chartOption" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { RayBar } from 'raychart'
import 'raychart/dist/raychart.css'

const chartOption = ref({
  series: [{
    name: '销售额',
    data: [120, 200, 150, 80, 70, 110, 130],
    color: ['#42b883'],
    itemStyle: {
      metalness: 0.3,    // 金属度
      roughness: 0.5     // 粗糙度
    }
  }],
  xAxis3D: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis3D: {
    name: '销售额'
  },
  // 自定义光照（可选，通常不需要）
  lights: [
    { 
      type: 'Ambient', 
      color: '#ffffff', 
      intensity: 0.8 
    },
    { 
      type: 'Directional', 
      color: '#ffffff', 
      intensity: 1.5, 
      position: { x: 5, y: 10, z: 5 } 
    }
  ]
})
</script>

<style scoped>
.chart-container {
  width: 100%;
  padding: 20px;
}
</style>

💡 关于光照

推荐：不配置 lights，让框架自动处理。

只在这些情况才手动配置：

  • 特殊光照效果
  • 调试光照问题
  • 特定视觉需求

6. 交互操作 ​

内置丰富交互：

操作桌面端移动端
旋转🖱️ 鼠标左键拖动👆 单指拖动
缩放🖱️ 滚轮👆 双指捏合
平移🖱️ 鼠标右键拖动👆 双指拖动

🎮 自定义交互

可以通过 controlSettings 配置启用/禁用特定交互：

javascript
const option = {
  series: [{ data: [120, 200, 150] }],
  controlSettings: {
    enableRotate: true,   // 启用旋转
    enableZoom: true,     // 启用缩放
    enablePan: false      // 禁用平移
  }
}

7. 事件监听 ​

监听图表事件：

vue
<template>
  <RayBar 
    :option="chartOption"
    @click="handleClick"
    @mouseover="handleMouseOver"
  />
</template>

<script setup>
const handleClick = (payload) => {
  console.log('点击了:', payload)
}

const handleMouseOver = (payload) => {
  console.log('悬停:', payload)
}
</script>
📋 可用事件列表
  • @click - 点击事件
  • @dblclick - 双击事件
  • @mouseover - 鼠标悬停
  • @mouseout - 鼠标移出
  • @mousemove - 鼠标移动
  • @mounted - 图表挂载完成
  • @rendered - 图表渲染完成
  • @beforeDestroy - 图表即将销毁
  • @destroyed - 图表已销毁

8. 常见问题 ​

图表不显示？ ​

检查这几点：

  1. ✅ 容器有高度
  2. ✅ 导入了 CSS
  3. ✅ 数据格式对
  4. ✅ 浏览器支持 WebGL

详见 常见问题。

性能优化？ ​

大数据量或移动端：

javascript
const option = {
  series: [{
    data: largeDataset
  }],
  postprocessing: {
    enable: false  // 关闭后处理提升性能
  }
}

详见 性能优化。

下一步 ​

恭喜！已掌握基础用法。接下来：

💬 需要帮助