3D 地图

3D 地图用于展示地理数据，支持加载任意 GeoJSON 数据源，并提供区域着色、地图钻取（省/市/区县三级联动）和多图层叠加（标记点、飞线、热力图、柱状棱柱等）。

快速开始

地图配置放在 option.map3D 中，区域数据放在 series 中：

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

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

const chartOption = ref({
  map3D: {
    geojsonUrl: 'https://geojson.raychart.cn/china.json', // 中国地图 GeoJSON
  },
  series: [
    {
      type: 'map3D',
      data: [
        { name: '北京', value: 100 },
        { name: '上海', value: 200 },
        { name: '广东', value: 300 },
      ],
    },
  ],
});
</script>

数据格式

series.data 中的 name 需要与 GeoJSON 特征的 name 属性一致（如"北京市"），value 用于区域着色和标签显示。

核心配置

地图配置（map3D）

属性	类型	默认值	说明
map3D.geojsonUrl	string	-	GeoJSON 数据地址（与 geojson 二选一）
map3D.geojson	object	-	直接传入 GeoJSON 数据（与 geojsonUrl 二选一）
map3D.center	[number, number]	自动计算	投影中心经纬度
map3D.scale	number	1	投影缩放比例
map3D.elevation	number	0	地图整体抬高高度
map3D.baseHeight	number	-	底面厚度
map3D.heightScale	number	0.02	区域高度缩放系数
map3D.pitch / rotation / zoom	number	-	初始相机角度和缩放
map3D.minPolarAngle / maxPolarAngle	number（弧度）	-π/4 / π/8	俯仰角限制范围（详见视角与视口限制）
map3D.minAzimuthAngle / maxAzimuthAngle	number（弧度）	-π/12 / π/12	方位角限制范围
map3D.viewRatio	number	0.8	地图包围盒占视口比例（0-1）
map3D.border	object	-	区域边界线：{ show, color, opacity }
map3D.label	object	-	区域名称标签样式（LabelStyle）

区域样式与颜色

series.color 设置区域默认调色板，data 项中的 itemStyle 可单独指定某个区域的颜色：

series: [
  {
    type: 'map3D',
    color: ['#5470c6', '#91cc75', '#fac858'], // 按数值分档的调色板
    data: [
      { name: '北京市', value: 100, itemStyle: { color: '#ff6b6b' } }, // 单独高亮
      { name: '上海市', value: 200 },
    ],
  },
],

地图钻取（map3D.drillDown）

属性	类型	默认值	说明
drillDown.enabled	boolean	false	启用钻取
drillDown.baseUrl	string	-	下级地图 GeoJSON 地址模板（{adcode} 会被替换）
drillDown.maxLevel	'country' | 'province' | 'city'	'city'	最大钻取级别
drillDown.allowAdcodes / denyAdcodes	string[]	-	允许 / 禁止钻取的行政区划代码

钻取行为

启用后点击区域会加载下一级地图（如点击"广东省"进入广东省地图），navigation 配置 { show: true } 可显示返回上一级的导航按钮。

图层（map3D.layers）

图层用于在地图上叠加数据可视化元素，data 项通过 coord: [经度, 纬度] 定位：

类型	说明
point	标记点，支持 colorRanges 分级着色和 pulse 脉冲动画
prism	柱状棱柱，heightScale 控制高度，常用来做柱状地图
label	自定义文本标签，支持 labelTypes 多种样式
billboard	立牌标签（文字 + 支柱）
line	普通折线
arc	弧线（飞线），curveHeight 控制弧度
flow	流动线（沿线流动的光点），支持 speed / tailCount 等
path	路径图层，统一管理 line / flow / arc 三种模式
heatmap	热力图，radius / intensity / gradient 控制效果
hex	六边形蜂窝热力图
ground	地面圆点

常见场景

区域高亮

通过 data 项的 itemStyle 单独着色：

<script setup>
const chartOption = ref({
  map3D: {
    geojsonUrl: 'https://geojson.raychart.cn/china.json',
  },
  series: [
    {
      type: 'map3D',
      data: [
        { name: '北京市', value: 100, itemStyle: { color: '#ff6b6b' } },
        { name: '上海市', value: 200, itemStyle: { color: '#4ecdc4' } },
        { name: '广东省', value: 300, itemStyle: { color: '#45b7d1' } },
      ],
    },
  ],
});
</script>

标记点 + 飞线

叠加 point 和 arc 图层，展示城市之间的数据流动：

<script setup>
const chartOption = ref({
  map3D: {
    geojsonUrl: 'https://geojson.raychart.cn/china.json',
    layers: [
      {
        type: 'point',
        data: [
          { coord: [116.4, 39.9], name: '北京', value: 100, color: '#ff6b6b', size: 1.2 },
          { coord: [121.47, 31.23], name: '上海', value: 80, color: '#4ecdc4', size: 1.0 },
        ],
        pulse: { enabled: true, speed: 1.5 }, // 呼吸动画
      },
      {
        type: 'arc',
        data: [
          { from: [116.4, 39.9], to: [121.47, 31.23], value: 60, curveHeight: 8 },
        ],
        speed: 0.5, // 飞线流动速度
      },
    ],
  },
  series: [{ type: 'map3D', data: [{ name: '北京市', value: 100 }] }],
});
</script>

地图钻取

<script setup>
const chartOption = ref({
  map3D: {
    geojsonUrl: 'https://geojson.raychart.cn/china.json',
    drillDown: {
      enabled: true,
      baseUrl: 'https://geojson.raychart.cn/province/{adcode}.json',
      maxLevel: 'city',
    },
    navigation: { show: true }, // 显示返回上级按钮
  },
  series: [{ type: 'map3D', data: [{ name: '广东省', value: 300 }] }],
});
</script>

地图编辑器

RayChart 提供了专门的地图编辑器，可以可视化地配置 3D 地图的样式、数据和图层：

使用地图编辑器

访问 地图编辑器 可视化配置地图，编辑器生成的配置可直接复制到项目中。

组件属性

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

相关文档

基础学习

• 快速上手 - 创建第一个图表
• 图表配置 - 了解完整的配置选项
• 简介 - 了解 RayChart 核心理念

进阶主题

• 交互控制 - 添加地图交互功能
• 材质系统 - 自定义地图材质效果
• 光照系统 - 地图光照配置
• 性能优化 - 大数据量地图优化

API 参考

• 组件 API - RayMap3D 组件属性和方法
• 配置项 API - 完整的配置项文档
• 事件系统 - 地图事件监听

其他图表类型

• 柱状图 - 展示数据对比
• 散点图 - 展示多变量关系
• 所有图表 - 浏览完整图表库

在线工具

• 地图编辑器 - 可视化配置地图样式
• 图表库 - 查看更多地图示例
• 在线编辑器 - 实时调试配置