3D 网格柱状图

3D 网格柱状图在三维空间中展示二维矩阵数据，通过 X 轴、Z 轴和柱高（Y 轴）展示多维度数据对比，适用于签到统计、传感器数据、多维度对比等场景。

快速开始

最简单的网格柱状图需要配置 X 轴、Z 轴和二维数组数据：

<template>
  <RayBar3DGrid :option="chartOption" />
</template>

<script setup>
import { ref } from 'vue';
import { RayBar3DGrid } from 'raychart';

const chartOption = ref({
  xAxis3D: {
    data: ['周一', '周二', '周三', '周四', '周五'],
    name: '星期',
  },
  zAxis3D: {
    data: ['数学', '语文', '英语'],
    name: '科目',
  },
  yAxis3D: {
    name: '签到人数',
  },
  series: [
    {
      type: 'bar3DGrid',
      data: [
        [45, 52, 48, 50, 55], // 数学
        [42, 48, 45, 47, 50], // 语文
        [40, 45, 43, 46, 48], // 英语
      ],
    },
  ],
});
</script>

智能默认值

自动配置柱体宽度、玻璃材质、标签位置和四点光照系统。

核心配置

坐标轴配置

属性	类型	默认值	说明
xAxis3D.data	string[]	-	X 轴数据（必填）
xAxis3D.name	string	-	X 轴名称
zAxis3D.data	string[]	-	Z 轴数据（必填）
zAxis3D.name	string	-	Z 轴名称
yAxis3D.name	string	-	Y 轴名称（数值轴）

数据配置

属性	类型	默认值	说明
series.data	number[][]	-	二维数组数据（必填）
series.name	string	-	系列名称

数据格式说明

series.data 是二维数组，每一行对应 Z 轴的一个类别，每行中的元素对应 X 轴的各个类别。

示例：

data: [
  [45, 52, 48],  // Z轴第1个类别在X轴各位置的值
  [42, 48, 45],  // Z轴第2个类别在X轴各位置的值
  [40, 45, 43],  // Z轴第3个类别在X轴各位置的值
]

样式配置

属性	类型	默认值	说明
series.color	string[]	内置 4 色调色板	颜色数组

标签配置（可选）

通过 series.label 配置柱顶标签（标签固定显示在柱顶上方，位置不可调）：

label: {
  show: true,                              // 显示标签
  formatter: '{value}',                    // 文本格式化（支持 {value} / {name}）
  fontSize: 11,                            // 字体大小
  fontWeight: '600',                       // 字体粗细
  color: '#333',                           // 字体颜色
  backgroundColor: 'rgba(255,255,255,0.95)', // 背景色
  padding: 6,                              // 内边距
  borderRadius: 4                          // 圆角
}

材质配置（进阶）

通过 series.itemStyle 配置柱体材质：

itemStyle: {
  opacity: 1.0,               // 不透明度（默认 1.0）
  roughness: 0.2,             // 粗糙度（默认 0.2）
  metalness: 0.3,             // 金属度（默认 0.3）
  clearcoat: 0.8,             // 清漆层强度（默认 0.8）
  clearcoatRoughness: 0.1,    // 清漆层粗糙度（默认 0.1）
  emissiveIntensity: 0.08     // 自发光强度（默认 0.08）
}

透传限制

网格柱状图的材质为半透明固色设计，transmission（透光度）固定为 0、transparent 固定为 false，配置这两项不会生效。

网格深度配置（进阶）

通过 grid3D.boxDepth 配置网格深度，控制 Z 轴方向的空间：

grid3D: {
  boxDepth: 6  // 网格深度（默认根据数据自动计算）
}

深度配置建议

• 如果地板延伸过长遮挡 X 轴标签，减小 boxDepth 值
• 如果柱体间距过小，增大 boxDepth 值
• 建议值范围：4-10

:::

常见场景

基础网格柱状图

展示签到统计数据：

<template>
  <RayBar3DGrid :option="chartOption" />
</template>

<script setup>
import { ref } from 'vue';
import { RayBar3DGrid } from 'raychart';

const chartOption = ref({
  xAxis3D: {
    data: ['周一', '周二', '周三', '周四', '周五', '周六', '周日'],
    name: '星期',
  },
  zAxis3D: {
    data: ['数学', '语文', '英语'],
    name: '科目',
  },
  yAxis3D: {
    name: '签到人数',
  },
  series: [
    {
      type: 'bar3DGrid',
      name: '签到统计',
      data: [
        [45, 52, 48, 50, 55, 49, 43], // 数学
        [42, 48, 45, 47, 50, 44, 40], // 语文
        [40, 45, 43, 46, 48, 42, 38], // 英语
      ],
      color: ['#667eea', '#f093fb', '#4facfe'],
      label: {
        show: true,
        fontSize: 11,
        color: '#333',
      },
    },
  ],
});
</script>

多城市销售对比

展示多个城市的季度销售数据：

<script setup>
const chartOption = ref({
  xAxis3D: {
    data: ['Q1', 'Q2', 'Q3', 'Q4', 'Q5', 'Q6'],
    name: '季度',
  },
  zAxis3D: {
    data: ['北京', '上海', '广州'],
    name: '城市',
  },
  yAxis3D: {
    name: '销售额（万元）',
  },
  series: [
    {
      type: 'bar3DGrid',
      name: '销售额',
      data: [
        [120, 150, 180, 200, 175, 190], // 北京
        [100, 130, 160, 190, 155, 170], // 上海
        [90, 110, 140, 170, 145, 160],  // 广州
      ],
      color: ['#5470c6', '#91cc75', '#fac858', '#ee6666'],
      itemStyle: {
        opacity: 0.95,
        roughness: 0.2,
        metalness: 0.3,
        clearcoat: 0.8,
        emissiveIntensity: 0.1,
      },
      label: {
        show: true,
        fontSize: 12,
        color: '#333',
      },
    },
  ],
});
</script>

传感器温度监测

展示传感器在不同时间点的温度数据：

<script setup>
const chartOption = ref({
  xAxis3D: {
    data: ['00:00', '04:00', '08:00', '12:00', '16:00', '20:00'],
    name: '时间',
  },
  zAxis3D: {
    data: ['传感器1', '传感器2', '传感器3'],
    name: '设备',
  },
  yAxis3D: {
    name: '温度（°C）',
  },
  series: [
    {
      type: 'bar3DGrid',
      name: '温度',
      data: [
        [18, 20, 25, 32, 30, 22], // 传感器1
        [19, 21, 27, 35, 31, 24], // 传感器2
        [17, 19, 24, 30, 28, 21], // 传感器3
      ],
      color: ['#4facfe', '#00f2fe', '#43e97b'],
      itemStyle: {
        opacity: 0.9,
        roughness: 0.15,
        metalness: 0.4,
        clearcoat: 1.0,
        clearcoatRoughness: 0.1,
      },
      label: {
        show: true,
        fontSize: 11,
        color: '#333',
      },
    },
  ],
});
</script>

自定义网格深度

通过配置 grid3D.boxDepth 控制 Z 轴空间：

<script setup>
const chartOption = ref({
  xAxis3D: {
    data: ['产品A', '产品B', '产品C', '产品D'],
    name: '产品',
  },
  zAxis3D: {
    data: ['线上', '线下'],
    name: '渠道',
  },
  yAxis3D: {
    name: '销量',
  },
  grid3D: {
    boxDepth: 6, // 设置网格深度为 6
  },
  series: [
    {
      type: 'bar3DGrid',
      data: [
        [120, 150, 180, 200], // 线上
        [100, 130, 160, 190], // 线下
      ],
      color: ['#5470c6', '#91cc75'],
    },
  ],
});
</script>

组件属性

属性	类型	默认值	说明
option	RayChartOption	-	图表配置对象（必填）
width	string | number	'100%'	图表宽度
height	string | number	'600px'	图表高度

相关文档

基础学习

• 快速上手 - 如果您是新手，从这里开始
• 图表配置 - 完整配置选项说明
• 坐标系统 - 理解 3D 坐标系

进阶主题

• 材质系统 - 自定义材质效果（金属度、粗糙度等）
• 光照系统 - 光照原理和配置
• 交互控制 - 相机控制和事件监听
• 性能优化 - 大数据量优化技巧

API 参考

• 组件 API - RayBar3DGrid 组件属性和方法
• 配置项 API - 完整的配置项文档
• 事件系统 - 事件监听和处理

其他图表类型

• 柱状图 - 展示数据对比
• 折线图 - 展示趋势变化
• 散点图 - 展示数据分布
• 查看所有图表 - 浏览完整图表库

在线示例

• 图表库 - 查看更多网格柱状图示例
• 在线编辑器 - 实时调试配置