常见问题

使用 RayChart 时的常见问题和解决方案。

安装和配置

Q: 安装后提示找不到模块？

A: 确保正确导入了 CSS 文件：

import { RayBar } from 'raychart'
import 'raychart/dist/raychart.css' // 必须导入 CSS

peer 依赖

RayChart 将 vue 与 three 外部化，需在项目中自行安装这两个依赖（npm i vue three）。

Q: TypeScript 提示类型错误？

A: 确保安装了类型定义。RayChart 内置类型，如果仍有问题：

# 重新安装依赖（按 lock 文件精确安装）
npm ci

Q: Vite 项目中报错 "Failed to resolve import"？

A: 在 vite.config.ts 中添加优化配置：

export default defineConfig({
  optimizeDeps: {
    include: ['raychart']
  }
})

图表显示

Q: 图表不显示或显示空白？

A: 检查这几点：

1. 容器高度：确保容器有高度

<template>
  <!-- ❌ 错误：容器没有高度 -->
  <div>
    <RayBar :option="option" />
  </div>
  
  <!-- ✅ 正确：明确指定高度 -->
  <div style="height: 600px">
    <RayBar :option="option" />
  </div>
  
  <!-- ✅ 或者直接在组件上指定 -->
  <RayBar :option="option" height="600px" />
</template>

2. 数据格式：确保数据格式正确

// ✅ 正确
const option = {
  series: [{
    data: [120, 200, 150]
  }],
  xAxis3D: {
    data: ['A', 'B', 'C']
  }
}

// ❌ 错误：缺少 series
const option = {
  xAxis3D: {
    data: ['A', 'B', 'C']
  }
}

3. CSS 导入：确保导入了 CSS 文件

Q: 图表显示但是很暗或看不清？

A: 这通常是光照问题。RayChart 自动配置光照，但如果你手动配置了，确保：

const option = {
  series: [{ data: [120, 200, 150] }],
  // 如果手动配置光照，至少需要环境光和方向光
  lights: [
    {
      type: 'Ambient',
      color: '#ffffff',
      intensity: 0.8  // 环境光强度
    },
    {
      type: 'Directional',
      color: '#ffffff',
      intensity: 1.5,  // 方向光强度
      position: { x: 5, y: 10, z: 5 }
    }
  ]
}

推荐做法：不手动配置 lights，让框架自动配置。

Q: 图表颜色不符合预期？

A: 检查颜色配置：

// 方式 1：在 series 中指定颜色
const option = {
  series: [{
    data: [120, 200, 150],
    color: ['#42b883', '#35495e', '#ff6b6b']  // 为每个数据项指定颜色
  }]
}

// 方式 2：使用 itemStyle
const option = {
  series: [{
    data: [120, 200, 150],
    itemStyle: {
      color: '#42b883'  // 统一颜色
    }
  }]
}

性能问题

Q: 数据量大时图表卡顿？

A: 尝试这些优化：

1. 减少数据点：采样或聚合数据
2. 关闭后处理：后处理消耗性能

const option = {
  series: [{ data: largeDataset }],
  postprocessing: {
    bloom: { enabled: false }  // 关闭辉光
  }
}

3. 降低材质复杂度：使用简单材质

const option = {
  series: [{
    data: largeDataset,
    itemStyle: {
      metalness: 0,  // 非金属
      roughness: 1   // 完全粗糙（计算更快）
    }
  }]
}

Q: 移动端性能差？

A: 移动端 GPU 性能较弱，建议：

1. 减少数据量
2. 关闭后处理效果
3. 使用简单材质
4. 降低图表尺寸

// 移动端优化配置
const isMobile = /Mobile|Android|iPhone/i.test(navigator.userAgent)

const option = {
  series: [{
    data: isMobile ? sampledData : fullData
  }],
  postprocessing: {
    bloom: { enabled: !isMobile }  // 移动端关闭辉光
  }
}

交互问题

Q: 无法旋转或缩放图表？

A: 检查控制器配置：

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

Q: 如何禁用某些交互？

A: 通过 controlSettings 配置：

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

Q: 如何监听点击事件？

A: 使用 Vue 事件：

<template>
  <RayBar 
    :option="option" 
    @click="handleClick"
  />
</template>

<script setup>
const handleClick = (payload) => {
  console.log('点击了:', payload)
  // payload 包含点击的数据项信息
}
</script>

数据更新

Q: 更新数据后图表不刷新？

A: 确保使用响应式数据，组件对 option 做深度监听（deep watch），直接修改或整体替换都会触发更新：

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

const option = ref({
  series: [{ data: [120, 200, 150] }]
})

// 直接修改（推荐，代码更简洁）
const updateData = () => {
  option.value.series[0].data = [150, 230, 180]
}

// 整体替换（同样生效）
const updateData2 = () => {
  option.value = {
    ...option.value,
    series: [{ data: [150, 230, 180] }]
  }
}
</script>

数据未变化不会重渲染

组件内部会对配置做内容哈希比对，内容未变化时自动跳过重渲染。若更新后图表没刷新，请检查新数据与旧数据是否完全相同（例如误用 push 后又还原），而非怀疑监听失效。

Q: 如何实现数据动画？

A: 使用定时器逐步更新数据：

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'

const option = ref({
  series: [{ data: [0, 0, 0] }]
})

let timer = null

onMounted(() => {
  const targetData = [120, 200, 150]
  const steps = 30
  let currentStep = 0
  
  timer = setInterval(() => {
    if (currentStep >= steps) {
      clearInterval(timer)
      return
    }
    
    const progress = currentStep / steps
    option.value = {
      ...option.value,
      series: [{
        data: targetData.map(val => val * progress)
      }]
    }
    
    currentStep++
  }, 16) // 约 60fps
})

onBeforeUnmount(() => {
  if (timer) clearInterval(timer)
})
</script>

样式和主题

Q: 如何自定义图表样式？

A: 使用 itemStyle 配置：

const option = {
  series: [{
    data: [120, 200, 150],
    itemStyle: {
      color: '#42b883',      // 基础颜色
      metalness: 0.8,        // 金属度
      roughness: 0.2,        // 粗糙度
      emissive: '#42b883',   // 自发光颜色
      emissiveIntensity: 0.5 // 自发光强度
    }
  }]
}

详见 材质系统。

Q: 如何实现发光效果？

A: 结合材质和后处理：

const option = {
  series: [{
    data: [120, 200, 150],
    itemStyle: {
      emissive: '#42b883',
      emissiveIntensity: 0.8
    }
  }],
  postprocessing: {
    bloom: {
      enabled: true,
      strength: 1.5,
      threshold: 0.5
    }
  }
}

导出和截图

Q: 如何导出图表为图片？

A: 使用 exportImage 方法：

<template>
  <div>
    <RayBar ref="chartRef" :option="option" />
    <button @click="exportChart">导出图片</button>
  </div>
</template>

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

const chartRef = ref(null)

const exportChart = async () => {
  const dataUrl = await chartRef.value?.exportImage()
  if (dataUrl) {
    // 下载图片
    const link = document.createElement('a')
    link.download = 'chart.png'
    link.href = dataUrl
    link.click()
  }
}
</script>

兼容性

Q: 支持哪些浏览器？

A: RayChart 基于 WebGL，支持所有支持 WebGL 2 的现代浏览器：

• ✅ Chrome / Edge（最新两个大版本）
• ✅ Firefox（最新两个大版本）
• ✅ Safari 15.4+（macOS 12.3+ / iOS 15.4+）
• ❌ IE 11（不支持）

Q: 移动端支持情况？

A: 完全支持移动端，包括：

• ✅ iOS Safari
• ✅ Android Chrome
• ✅ 触摸手势（旋转、缩放、平移）

建议在移动端使用性能优化配置。

其他问题

Q: 如何调试光照？

A: 启用光源辅助器：

const option = {
  series: [{ data: [120, 200, 150] }],
  showLightHelpers: true  // 显示光源辅助器
}

Q: 图表在某些容器中显示异常？

A: 确保容器的 CSS 定位正确：

.chart-container {
  position: relative; /* 或 absolute */
  width: 100%;
  height: 600px;
}

Q: 如何获取技术支持？

A:

1. 查看 文档
2. 查看 示例
3. 通过官网 raychart.cn 联系官方支持

还有问题？

如果以上没有解决你的问题：

1. 查看 故障排查 - 系统性问题诊断
2. 查看 最佳实践 - 推荐的使用方式
3. 查看 API 文档 - 完整的配置参考
4. 参考 示例代码 - 在线演示和代码

TypeScript 支持

RayChart 内置完整的 TypeScript 类型定义，无需额外安装 @types 包。

Q: 如何使用 TypeScript 类型？

import type { RayChartOption, Series3D } from 'raychart'

// 获得完整的类型推断和自动补全
const option: RayChartOption = {
  series: [{
    data: [120, 200, 150, 80, 70, 110, 130]
  }],
  xAxis3D: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  }
}

Q: 组件 ref 的类型如何标注？

import { ref } from 'vue'
import { RayBar } from 'raychart'

// 语义组件已透传 resize / dispose / fitToScreen / exportImage 等方法
const chartRef = ref<InstanceType<typeof RayBar> | null>(null)

// 调用方法
chartRef.value?.resize()
chartRef.value?.dispose()

Q: 为什么 strict 模式下有类型报错？

A: RayChart 支持 TypeScript strict 模式。如果遇到报错，检查：

1. series.data 类型是否与图表类型匹配（柱状图用 number[]，饼图用 {name: string, value: number}[]）
2. 可选属性是否用了 ? 或做了 null 检查
3. 确保 tsconfig.json 中 "moduleResolution": "bundler" 或 "node16"

相关文档

入门学习

• 安装 - 安装和环境配置
• 快速上手 - 5分钟创建第一个图表
• 简介 - 了解 RayChart 核心理念

配置和定制

• 图表配置 - 理解配置结构
• 材质系统 - 自定义视觉效果
• 光照系统 - 光照原理和配置
• 交互控制 - 交互功能和事件

性能和优化

• 性能优化 - 大数据场景优化
• 最佳实践 - 性能优化建议

API 参考

• 组件 API - 组件属性和方法
• 配置项 API - 完整的配置选项
• 事件系统 - 事件类型和参数

图表示例

• 柱状图 - 查看柱状图配置
• 折线图 - 查看折线图配置
• 饼图 - 查看饼图配置
• 所有图表类型 - 浏览完整图表库