3D 热力图

3D 热力图通过柱体高度和颜色映射展示二维矩阵数据的密度分布，直观呈现数据在两个维度上的分布特征，适用于时间分布、地理热力、温度分布等场景。

快速开始

最简单的 3D 热力图需要配置 X 轴、Z 轴和数据：

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

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

const chartOption = ref({
  xAxis3D: {
    data: ['周一', '周二', '周三', '周四', '周五'],
    name: '星期',
  },
  zAxis3D: {
    data: ['数学', '语文', '英语'],
    name: '科目',
  },
  yAxis3D: {
    name: '分数',
  },
  series: [
    {
      type: 'heatmap3D',
      data: [
        { x: '周一', z: '数学', value: 85 },
        { x: '周二', z: '数学', value: 92 },
        { x: '周三', z: '数学', value: 78 },
        { x: '周一', z: '语文', value: 75 },
        { x: '周二', z: '语文', value: 82 },
        // ... 更多数据点
      ],
    },
  ],
});
</script>

智能默认值

自动配置颜色映射、柱体高度、标签显示和光照效果。

核心配置

坐标轴配置

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

数据配置

属性	类型	默认值	说明
series.data	Array<{x: string, z: string, value: number}>	-	热力数据（必填）
series.name	string	-	系列名称

数据格式说明

series.data 是对象数组，每个对象包含三个字段：

• x: X 轴的类别值（必须与 xAxis3D.data 中的值匹配）
• z: Z 轴的类别值（必须与 zAxis3D.data 中的值匹配）
• value: 数值，决定柱体高度和颜色

示例：

data: [
  { x: '周一', z: '数学', value: 85 },
  { x: '周二', z: '数学', value: 92 },
  { x: '周一', z: '语文', value: 75 },
]

样式配置

属性	类型	默认值	说明
series.tileHeight	number	0.15	色块基础高度
series.colorGradient	Array<{stop, color}>	内置 8 色冷→暖渐变	自定义颜色映射（stop 为 0-1 的渐变位置）
series.itemStyle.roughness	number	0.4	色块粗糙度
series.itemStyle.metalness	number	0.05	色块金属度

数据格式

series.data 支持三种格式：

• 对象数组：[{ x: '周一', z: '数学', value: 85 }]
• 索引数组：[[0, 0, 85], [1, 0, 92]]（x/z 轴类别由轴配置提供）
• 二维数组：[[85, 92, 78], [75, 82, 88]]（行对应 Z 轴、列对应 X 轴）

网格配置（可选）

通过 grid3D 配置三维空间尺寸：

grid3D: {
  show: true,       // 显示网格边框
  boxWidth: 20,     // 宽度
  boxHeight: 10     // 高度
}

常见场景

基础热力图

展示每周各科成绩分布：

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

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

const xLabels = ['周一', '周二', '周三', '周四', '周五', '周六', '周日'];
const zLabels = ['数学', '语文', '英语', '物理', '化学'];

// 生成随机成绩数据
const data = [];
zLabels.forEach((subject) => {
  xLabels.forEach((day) => {
    const value = Math.round(60 + Math.random() * 40);
    data.push({ x: day, z: subject, value });
  });
});

const chartOption = ref({
  grid3D: {
    show: true,
    boxWidth: 20,
    boxHeight: 10,
  },
  xAxis3D: {
    data: xLabels,
    name: '星期',
  },
  zAxis3D: {
    data: zLabels,
    name: '科目',
  },
  yAxis3D: {
    name: '分数',
  },
  series: [
    {
      type: 'heatmap3D',
      name: '成绩热力图',
      data,
      tileHeight: 0.15,
      label: {
        show: true,
        fontSize: 10,
        color: '#333',
      },
    },
  ],
});
</script>

时段活跃度分布

展示一周各时段的活跃度：

<script setup>
const days = ['周一', '周二', '周三', '周四', '周五', '周六', '周日'];
const hours = ['0时', '3时', '6时', '9时', '12时', '15时', '18时', '21时'];

// 模拟活跃度数据
const data = [];
days.forEach((day, zi) => {
  hours.forEach((hour, xi) => {
    // 工作日白天活跃，周末全天活跃
    const isWeekend = zi >= 5;
    const isWorkHour = xi >= 3 && xi <= 6;
    const base = isWeekend ? 60 : isWorkHour ? 80 : 20;
    const value = Math.round(base + Math.random() * 30);
    data.push({ x: hour, z: day, value });
  });
});

const chartOption = ref({
  grid3D: {
    show: true,
    boxWidth: 20,
    boxHeight: 10,
  },
  xAxis3D: {
    data: hours,
    name: '时段',
  },
  zAxis3D: {
    data: days,
    name: '星期',
  },
  yAxis3D: {
    name: '活跃度',
  },
  series: [
    {
      type: 'heatmap3D',
      name: '活跃度',
      data,
      label: {
        show: false, // 数据点多时隐藏标签
      },
    },
  ],
});
</script>

城市温度分布

展示多个城市的月均温度：

<script setup>
const months = ['1月', '2月', '3月', '4月', '5月', '6月', '7月', '8月', '9月', '10月', '11月', '12月'];
const cities = ['哈尔滨', '北京', '上海', '广州', '海口'];

// 各城市月均温度
const temps = [
  [-18, -14, -4, 6, 14, 20, 23, 21, 13, 3, -7, -15], // 哈尔滨
  [-3, 0, 6, 14, 20, 25, 27, 26, 20, 13, 4, -1],     // 北京
  [4, 6, 10, 16, 21, 25, 28, 28, 24, 18, 12, 6],     // 上海
  [14, 15, 19, 24, 28, 29, 30, 30, 28, 25, 20, 15],  // 广州
  [18, 19, 22, 26, 29, 29, 29, 29, 28, 26, 23, 19],  // 海口
];

const data = [];
cities.forEach((city, zi) => {
  months.forEach((month, xi) => {
    data.push({
      x: month,
      z: city,
      value: temps[zi][xi],
    });
  });
});

const chartOption = ref({
  grid3D: {
    show: true,
    boxWidth: 20,
    boxHeight: 10,
  },
  xAxis3D: {
    data: months,
    name: '月份',
  },
  zAxis3D: {
    data: cities,
    name: '城市',
  },
  yAxis3D: {
    name: '温度(°C)',
  },
  series: [
    {
      type: 'heatmap3D',
      name: '月均温度',
      data,
      label: {
        show: true,
        fontSize: 9,
      },
    },
  ],
});
</script>

自定义柱体高度

通过 tileHeight 调整柱体基础高度：

<script setup>
const chartOption = ref({
  xAxis3D: {
    data: ['产品A', '产品B', '产品C', '产品D'],
    name: '产品',
  },
  zAxis3D: {
    data: ['线上', '线下', '代理'],
    name: '渠道',
  },
  yAxis3D: {
    name: '销量',
  },
  series: [
    {
      type: 'heatmap3D',
      data: [
        { x: '产品A', z: '线上', value: 120 },
        { x: '产品A', z: '线下', value: 100 },
        { x: '产品A', z: '代理', value: 80 },
        { x: '产品B', z: '线上', value: 150 },
        { x: '产品B', z: '线下', value: 130 },
        { x: '产品B', z: '代理', value: 90 },
        // ... 更多数据
      ],
      tileHeight: 0.2, // 增大柱体基础高度
      label: {
        show: true,
        fontSize: 11,
        color: '#333',
      },
    },
  ],
});
</script>

组件属性

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

相关文档

基础学习

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

进阶主题

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

API 参考

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

其他图表类型

• 3D 网格柱状图 - 展示矩阵数据
• 3D 曲面图 - 展示连续曲面
• 3D 散点图 - 展示空间分布
• 查看所有图表 - 浏览完整图表库

在线示例

• 图表库 - 查看更多 3D 热力图示例
• 在线编辑器 - 实时调试配置