Appearance
图表配置
RayChart 的配置参考了 ECharts，如果你熟悉 ECharts，上手会很快。
配置理念
约定优于配置 - 提供数据，其他交给默认值
配置结构
javascript
{
series: [], // 系列列表（必需）
xAxis3D: {}, // X 轴配置
yAxis3D: {}, // Y 轴配置
zAxis3D: {}, // Z 轴配置（散点图等）
grid3D: {}, // 网格配置
lights: [], // 光照配置（可选）
postprocessing: {}, // 后处理效果
controlSettings: {} // 交互控制
}Series 配置
series 是图表核心，定义数据和样式。
基础配置
javascript
series: [{
name: '销售额', // 系列名称
data: [120, 200], // 数据（必需）
color: ['#42b883'], // 颜色（可选）
itemStyle: {} // 样式配置
}]⚠️ 关于 type 字段
使用语义化组件（RayBar、RayLine 等）时，不需要指定 type 字段。 组件会自动设置正确的类型。
数据格式
不同图表类型支持不同的数据格式：
javascript
// 简单数组
series: [{
data: [120, 200, 150, 80, 70]
}]javascript
// 对象数组（需要 name 和 value）
series: [{
data: [
{ name: 'A', value: 335 },
{ name: 'B', value: 310 },
{ name: 'C', value: 234 }
]
}]javascript
// 二维数组
series: [{
data: [
[10, 20, 30], // [x, y, z]
[15, 25, 35],
[20, 30, 40]
]
}]javascript
// 简单数组 + radar 配置
series: [{
data: [80, 90, 70, 85, 95]
}],
radar: {
indicator: [
{ name: '销售', max: 100 },
{ name: '管理', max: 100 },
{ name: '技术', max: 100 }
]
}样式配置
javascript
series: [{
data: [120, 200, 150],
itemStyle: {
// 基础属性
color: '#42b883',
opacity: 0.8,
// 材质属性
metalness: 0.5, // 金属度 (0-1)
roughness: 0.5, // 粗糙度 (0-1)
// 发光效果
emissive: '#42b883',
emissiveIntensity: 0.5
}
}]更多材质属性
查看 材质系统 了解完整的材质配置选项。
坐标轴配置
基础配置
javascript
xAxis3D: {
data: ['Mon', 'Tue', 'Wed'], // 类别数据
name: 'X 轴' // 坐标轴名称
}轴类型
X/Z 轴仅支持类别轴（内部使用 scaleBand 实现），type 字段会被忽略，不支持 value / time / log 类型。
Y 轴为数值轴，可通过 yAxis3D.min / yAxis3D.max 手动指定范围，默认根据数据自动计算。
样式配置
javascript
xAxis3D: {
data: ['A', 'B', 'C'],
// 轴线样式
axisLine: {
show: true,
lineStyle: {
color: '#333',
width: 1
}
},
// 标签样式（文字样式放在 textStyle 中）
axisLabel: {
show: true,
textStyle: {
fontSize: 12,
color: '#666'
}
}
}光照配置
智能默认值
大多数情况不需要手动配置光照，引擎内置四点光照系统（环境光 + 主光 + 补光 + 轮廓光）会自动生效。
手动配置（高级）
javascript
lights: [
{
id: 'ambient',
type: 'Ambient', // 环境光
color: '#ffffff',
intensity: 0.8
},
{
id: 'main',
type: 'Directional', // 方向光
color: '#ffffff',
intensity: 1.5,
position: { x: 5, y: 10, z: 5 }
},
{
id: 'fill',
type: 'Directional', // 补光
color: '#ffffff',
intensity: 0.5,
position: { x: -5, y: 5, z: -5 }
}
]光源类型说明
Ambient（环境光）
- 均匀照亮所有物体
- 没有方向性
- 用于提供基础亮度
Directional（方向光）
- 模拟太阳光
- 有明确方向
- 产生阴影效果
Point（点光源）
- 从一点向四周发光
- 类似灯泡
- 有衰减效果
Spot（聚光灯）
- 锥形光束
- 可控制角度
- 适合特殊效果
后处理效果
后处理可显著提升视觉效果，但会消耗性能。目前仅内置 bloom（泛光）效果：
javascript
postprocessing: {
bloom: {
enabled: true, // 是否启用
strength: 1.2, // 强度
radius: 0.8, // 半径
threshold: 0.6, // 亮度阈值（超过该亮度的区域才会泛光）
resolutionScale: 0.5 // 效果渲染分辨率（0.25-1，越低越省性能）
}
}性能提示
移动端或大数据量场景建议关闭 bloom：
javascript
postprocessing: { bloom: { enabled: false } }更多细节见 后处理。
交互控制
通过 controlSettings 控制相机交互行为：
javascript
controlSettings: {
// 启用/禁用交互
enableRotate: true, // 旋转
enableZoom: true, // 缩放
enablePan: true, // 平移
// 旋转范围限制（弧度）
minPolarAngle: 0, // 最小俯仰角
maxPolarAngle: Math.PI, // 最大俯仰角
minAzimuthAngle: -Math.PI,
maxAzimuthAngle: Math.PI,
// 适配视口
fitToScreenFactor: 0.8, // 图表占视口比例（0-1，默认 0.8）
cameraDirection: { x: 1, y: 1.5, z: 1 } // 相机观察方向（y 越大俯角越大）
}完整字段说明见 交互。
完整示例
查看完整配置示例
javascript
const option = {
// 系列数据
series: [{
name: '销售额',
data: [120, 200, 150, 80, 70, 110, 130],
color: ['#42b883'],
barWidth: 1.5,
barDepth: 1.5,
itemStyle: {
metalness: 0.3,
roughness: 0.5,
emissive: '#000000',
emissiveIntensity: 0.0
}
}],
// 坐标轴
xAxis3D: {
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
},
yAxis3D: {
min: 0,
max: 200,
name: '销售额'
},
// 网格
grid3D: {
boxWidth: 20,
boxHeight: 10,
boxDepth: 10
},
// 后处理
postprocessing: {
bloom: {
enabled: true,
strength: 1.2
}
},
// 交互控制
controlSettings: {
enableRotate: true,
enableZoom: true,
enablePan: true
}
}下一步学习
现在您已了解图表配置的基础知识,根据您的需求选择:
深入配置系统
实践应用
API 参考
查看示例