RayChart

Appearance

常见问题 ​

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

安装和配置 ​

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

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

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

Q: TypeScript 提示类型错误？ ​

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

bash
# 清除缓存重新安装
rm -rf node_modules package-lock.json
npm install

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

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

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

图表显示 ​

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

A: 检查这几点：

  1. 容器高度：确保容器有高度
vue
<template>
  <!-- ❌ 错误：容器没有高度 -->
  <div>
    <RayBar :option="option" />
  </div>
  
  <!-- ✅ 正确：明确指定高度 -->
  <div style="height: 600px">
    <RayBar :option="option" />
  </div>
  
  <!-- ✅ 或者直接在组件上指定 -->
  <RayBar :option="option" height="600px" />
</template>
  1. 数据格式：确保数据格式正确
javascript
// ✅ 正确
const option = {
  series: [{
    data: [120, 200, 150]
  }],
  xAxis3D: {
    data: ['A', 'B', 'C']
  }
}

// ❌ 错误：缺少 series
const option = {
  xAxis3D: {
    data: ['A', 'B', 'C']
  }
}
  1. CSS 导入：确保导入了 CSS 文件

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

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

javascript
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: 检查颜色配置：

javascript
// 方式 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. 关闭后处理：后处理消耗性能
javascript
const option = {
  series: [{ data: largeDataset }],
  postprocessing: {
    enable: false  // 关闭后处理
  }
}
  1. 降低材质复杂度：使用简单材质
javascript
const option = {
  series: [{
    data: largeDataset,
    itemStyle: {
      metalness: 0,  // 非金属
      roughness: 1   // 完全粗糙（计算更快）
    }
  }]
}

Q: 移动端性能差？ ​

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

  1. 减少数据量
  2. 关闭后处理效果
  3. 使用简单材质
  4. 降低图表尺寸
javascript
// 移动端优化配置
const isMobile = /Mobile|Android|iPhone/i.test(navigator.userAgent)

const option = {
  series: [{
    data: isMobile ? sampledData : fullData
  }],
  postprocessing: {
    enable: !isMobile  // 移动端关闭后处理
  }
}

交互问题 ​

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

A: 检查控制器配置：

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

Q: 如何禁用某些交互？ ​

A: 通过 controlSettings 配置：

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

Q: 如何监听点击事件？ ​

A: 使用 Vue 事件：

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

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

数据更新 ​

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

A: 确保使用响应式数据：

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

// ✅ 正确：使用 ref
const option = ref({
  series: [{ data: [120, 200, 150] }]
})

// 更新数据
const updateData = () => {
  option.value = {
    ...option.value,
    series: [{ data: [150, 230, 180] }]
  }
}

// ❌ 错误：直接修改（不会触发更新）
const updateDataWrong = () => {
  option.value.series[0].data = [150, 230, 180]
}
</script>

Q: 如何实现数据动画？ ​

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

vue
<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 配置：

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

详见 材质系统。

Q: 如何实现发光效果？ ​

A: 结合材质和后处理：

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

导出和截图 ​

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

A: 使用 exportImage 方法：

vue
<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，支持：

  • ✅ Chrome 56+
  • ✅ Firefox 51+
  • ✅ Safari 11+
  • ✅ Edge 79+
  • ❌ IE 11（不支持）

Q: 移动端支持情况？ ​

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

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

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

其他问题 ​

Q: 如何调试光照？ ​

A: 启用光源辅助器：

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

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

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

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

Q: 如何获取技术支持？ ​

A:

  1. 查看 文档
  2. 查看 示例
  3. 提交 Issue（如果是开源版本）

还有问题？ ​

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

  1. 查看 最佳实践
  2. 查看 API 文档
  3. 参考 示例代码