RayChart

Appearance

RayChart 组件 ​

RayChart 是核心组件，用于渲染 3D 图表。通常使用语义化组件（RayBar、RayLine 等）而非直接使用此组件。

组件属性 ​

option ​

  • 类型: RayChartOption
  • 必填: 是
  • 说明: 图表配置对象
typescript
interface RayChartOption {
  series?: Series3D[]          // 系列列表（必填，至少一个系列）
  lights?: LightConfig[]       // 光照配置（可选，缺省自动配置三点光照）
  xAxis3D?: Axis3D             // X 轴配置
  yAxis3D?: Axis3D             // Y 轴配置
  zAxis3D?: Axis3D             // Z 轴配置
  grid3D?: Grid3D              // 网格配置
  radar?: Radar                // 雷达图配置（仅 RayRadar）
  map3D?: Map3DOption          // 地图配置（仅 RayMap3D）
  postprocessing?: PostprocessingOptions  // 后处理效果（仅辉光）
  controlSettings?: ControlSettings       // 相机交互控制
  backgroundColor?: string | null         // 背景颜色
}

智能默认值

除 series 外所有字段均可省略：光照、颜色、材质、轴、网格均由框架自动生成。

width ​

  • 类型: string | number
  • 默认值: '100%'
  • 说明: 图表宽度

height ​

  • 类型: string | number
  • 默认值: '600px'
  • 说明: 图表高度

组件方法 ​

通过 ref 获取组件实例后，可以调用以下方法：

resize() ​

调整图表大小，通常在容器尺寸变化时调用。

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

const chartRef = ref()

const handleResize = () => {
  chartRef.value?.resize()
}

onMounted(() => {
  window.addEventListener('resize', handleResize)
})

onUnmounted(() => {
  window.removeEventListener('resize', handleResize)
})
</script>

<template>
  <RayBar ref="chartRef" :option="chartOption" />
</template>

dispose() ​

销毁图表实例，释放资源。

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

const chartRef = ref()

onUnmounted(() => {
  chartRef.value?.dispose()
})
</script>

资源清理

在组件卸载时调用 dispose() 可以避免内存泄漏，特别是在频繁创建/销毁图表的场景中。

fitToScreen() ​

让相机自动适配当前图表内容，将全部图形完整收入视野。适合在图表容器尺寸变化后或数据更新后调用，以修正视野留白。

javascript
chartRef.value?.fitToScreen()

setOption(option) ​

以新配置更新图表（整体替换）。若需要局部更新，直接修改响应式的 option 对象即可（组件内部对 option 做深度监听）。

javascript
chartRef.value?.setOption({
  series: [{ data: [1, 2, 3] }]
})

exportImage() ​

将当前画面导出为图片，返回 Promise<string>（dataURL）。

javascript
const dataUrl = await chartRef.value?.exportImage()
// 将 dataUrl 赋给 <img src> 或触发下载

生命周期事件 ​

RayChart 提供了完整的生命周期事件：

事件名触发时机参数
@mounted图表挂载完成-
@rendered图表渲染完成-
@beforeDestroy图表销毁前-
@destroyed图表销毁后-
vue
<template>
  <RayBar 
    :option="chartOption"
    @mounted="handleMounted"
    @rendered="handleRendered"
    @beforeDestroy="handleBeforeDestroy"
    @destroyed="handleDestroyed"
  />
</template>

<script setup>
const handleMounted = () => {
  console.log('Chart mounted')
}

const handleRendered = () => {
  console.log('Chart rendered')
}

const handleBeforeDestroy = () => {
  console.log('Chart will be destroyed')
}

const handleDestroyed = () => {
  console.log('Chart destroyed')
}
</script>

详见 生命周期

交互事件 ​

RayChart 支持丰富的交互事件，详见 事件系统。

完整示例 ​

vue
<template>
  <RayBar 
    ref="chartRef"
    :option="chartOption" 
    width="100%" 
    height="600px"
    @click="handleClick"
    @rendered="handleRendered"
  />
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import { RayBar } from 'raychart'

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

const handleClick = (params) => {
  console.log('Clicked:', params)
}

const handleRendered = () => {
  console.log('Chart rendered')
}

// 窗口大小改变时调整图表
const handleResize = () => {
  chartRef.value?.resize()
}

onMounted(() => {
  window.addEventListener('resize', handleResize)
})

onUnmounted(() => {
  window.removeEventListener('resize', handleResize)
  chartRef.value?.dispose()
})
</script>

TypeScript 支持 ​

RayChart 提供完整的 TypeScript 类型定义：

typescript
import type { RayChartOption, Series, Axis3D } from 'raychart'

const option: RayChartOption = {
  series: [{
    data: [120, 200, 150]
  }],
  xAxis3D: {
    data: ['A', 'B', 'C']
  }
}

相关文档 ​

基础学习 ​

组件使用 ​

API 参考 ​

图表组件 ​

TypeScript 支持 ​

RayChart 提供完整的 TypeScript 类型定义，详见 常见问题 - TypeScript 支持