RayChart

Appearance

图表配置项 ​

完整的图表配置项说明，涵盖所有图表类型的通用配置和特定配置。

配置理念 ​

RayChart 采用智能默认值设计：

  • ✅ 只配置必要数据和业务逻辑
  • ✅ 框架自动处理光照、颜色、材质等
  • ✅ 需要精细控制时再自定义

最佳实践

从最简配置开始，只在需要时添加自定义。保持代码简洁，享受框架智能优化。

通用配置 ​

series ​

  • 类型: Array<Series>
  • 必填: 是
  • 说明: 系列列表，包含图表数据和样式配置
typescript
series: [{
  name: '销售额',           // 系列名称
  data: [120, 200, 150],   // 数据（必填）
  color: ['#42b883'],      // 颜色（可选，自动分配）
  itemStyle: {             // 样式（可选）
    metalness: 0.3,
    roughness: 0.5
  }
}]

语义化组件

使用 RayBar、RayLine 等语义化组件时，不需要指定 series.type。

坐标轴配置 ​

xAxis3D / yAxis3D / zAxis3D ​

  • 类型: Axis3D
  • 说明: 三维坐标轴配置
typescript
xAxis3D: {
  data: ['Mon', 'Tue', 'Wed'],        // 类别数据（必填）
  name: 'Day',                         // 坐标轴名称
  axisLabel: {                         // 轴标签样式
    show: true,
    textStyle: { color: '#666', fontSize: 12 }
  }
}

坐标轴类型：

轴类型说明
xAxis3D / zAxis3D类别轴只能通过 data 指定离散类别；不支持 value/time/log 类型
yAxis3D数值轴连续数值，可通过 min/max 限制范围

X 轴无“数值轴”模式

xAxis3D 仅支持类别轴：传入的 data 数组即刻度列表，数据点按其索引对齐。type: 'value' 等写法不会生效。

grid3D ​

  • 类型: Grid3D
  • 说明: 三维网格配置
typescript
grid3D: {
  boxWidth: 100,      // 网格宽度
  boxHeight: 100,     // 网格高度
  boxDepth: 100       // 网格深度
}

光照配置 ​

lights ​

  • 类型: Array<Light>
  • 说明: 光源配置（可选，框架会自动配置）
光源类型说明
类型说明适用场景
Ambient环境光提供基础照明，均匀照亮所有物体
Directional方向光模拟太阳光，产生明显的明暗对比
Point点光源从一个点向四周发光，如灯泡
Spot聚光灯锥形光束，如舞台灯光
typescript
lights: [
  {
    id: 'ambient-1',            // 光源唯一 ID（必填）
    type: 'Ambient',
    color: '#ffffff',
    intensity: 0.5
  },
  {
    id: 'dir-1',                // 光源唯一 ID（必填）
    type: 'Directional',
    color: '#ffffff',
    intensity: 1.0,
    position: { x: 5, y: 10, z: 5 }
  }
]

不配置也能亮

lights 整体缺省时，框架自动生成一组三点光照，绝大多数场景无需手动配置。

详见 光照系统 :::

后处理配置 ​

postprocessing ​

  • 类型: Postprocessing
  • 说明: 后处理效果配置
typescript
postprocessing: {
  bloom: {              // 辉光效果（当前仅支持辉光）
    enabled: true,
    strength: 1.5,
    radius: 0.4,
    threshold: 0.85
  }
}

bloom 完整字段：

字段类型默认值说明
enabledbooleantrue是否启用辉光
selectivebooleanfalse是否仅对图表主体生效（避免背景发光）
strengthnumber1.0辉光强度
radiusnumber0.4辉光扩散半径
thresholdnumber0.85亮度阈值（高于此值才产生辉光）
resolutionScalenumber0.5辉光渲染分辨率缩放

详见 后处理效果

交互配置 ​

controlSettings ​

  • 类型: ControlSettings
  • 说明: 相机控制器配置
typescript
controlSettings: {
  enableRotate: true,        // 启用旋转
  enableZoom: true,          // 启用缩放
  enablePan: true,           // 启用平移
  minPolarAngle: 0,          // 垂直旋转最小角（弧度）
  maxPolarAngle: Math.PI,    // 垂直旋转最大角（弧度）
  fitToScreenFactor: 0.8,    // 相机适配距离系数（0-1）
  cameraDirection: { x: 1, y: 1.5, z: 1 }  // 自定义观察方向
}

controlSettings 全部字段：minPolarAngle / maxPolarAngle / minAzimuthAngle / maxAzimuthAngle / enableRotate / enableZoom / enablePan / fitToScreenFactor / cameraDirection，均为可选。

详见 交互控制

完整示例 ​

typescript
import type { RayChartOption } from 'raychart'

const option: RayChartOption = {
  series: [{
    data: [120, 200, 150, 80, 70, 110, 130]
  }],
  xAxis3D: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  }
}
typescript
import type { RayChartOption } from 'raychart'

const option: RayChartOption = {
  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'],
    name: 'Day'
  },
  yAxis3D: {
    name: 'Value',
    min: 0,
    max: 250
  },
  postprocessing: {
    bloom: {
      enabled: true,
      strength: 1.5
    }
  },
  controlSettings: {
    enableRotate: true,
    enableZoom: true,
    enablePan: true
  }
}

相关文档 ​