RayChart

Appearance

视角与视口限制 ​

3D 地图（RayMap3D）内置了完整的视角与视口限定机制，确保用户始终处于合理的观察范围内，不会因过度旋转、缩放而丢失方向感。

相机角度限制 ​

角度限制通过 map3D 配置项控制，单位为弧度：

属性默认值说明
map3D.minPolarAngle-π/4（-45°）最小俯仰角，允许向上倾斜查看地图顶部
map3D.maxPolarAngleπ/8（+22.5°）最大俯仰角，防止地图过度"平躺"
map3D.minAzimuthAngle-π/12（-15°）最小方位角，限制向左旋转
map3D.maxAzimuthAngleπ/12（+15°）最大方位角，限制向右旋转
vue
<script setup>
import { ref } from 'vue';
import { RayMap3D } from 'raychart';

const chartOption = ref({
  map3D: {
    geojsonUrl: 'https://geojson.raychart.cn/china.json',
    // 自定义角度限制（弧度）
    minPolarAngle: -Math.PI / 6,    // -30°，允许向上倾斜查看
    maxPolarAngle: Math.PI / 6,     // +30°，比默认更宽松
    minAzimuthAngle: -Math.PI / 6,  // -30° 左右旋转范围
    maxAzimuthAngle: Math.PI / 6,
  },
  series: [{ type: 'map3D', data: [{ name: '北京', value: 100 }] }],
});
</script>

默认值的设计意图

  • 最大俯仰角限制为 +22.5°：避免地图接近水平视角（90° 即完全平躺）导致难以辨认，同时保持 3D 立体感
  • 方位角限制在 ±15°：保持地图方向一致，用户不会转晕
  • 需要更大自由度的场景（如大屏展示），可通过上述字段放宽限制

相机距离限制 ​

距离限制是自动计算的，不需要也无法手动配置：

  • 最近距离：最佳观察距离 × 0.6（允许适度放大查看细节）
  • 最远距离：当前行政区域包围盒对角线 × 1.2（防止缩小到看不清地图）

最佳观察距离由相机管理器根据地图包围盒、俯仰角、旋转、缩放等参数迭代计算，并随地图层级（国家 → 省份 → 城市）自动调整。切换层级或缩放地图时，限制会同步更新，视角始终聚焦在当前区域。

内置视口限定 ​

地图渲染时还会应用以下技术，用于提升视觉体验和渲染性能：

  • 雾效（Fog） - 远处的对象随距离逐渐淡化，创造深度感。雾效参数会跟随相机距离动态调整
  • 边界淡化 - 地图边界外区域平滑淡化直至透明，避免生硬的边缘

这些效果在渲染地图时自动生效，当前版本暂未开放配置接口。如果你有自定义需求（如调整淡化强度），请通过官网 raychart.cn 联系官方支持。

完整示例 ​

组合使用角度限制与视口比例：

vue
<template>
  <RayMap3D :option="chartOption" style="width: 100%; height: 600px" />
</template>

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

const chartOption = ref({
  map3D: {
    geojsonUrl: 'https://geojson.raychart.cn/china.json',
    center: [104, 36],        // 投影中心经纬度
    zoom: 1.2,                // 初始缩放
    pitch: 50,                // 初始俯仰角（度）
    viewRatio: 0.85,          // 地图占视口比例
    minPolarAngle: -Math.PI / 4,
    maxPolarAngle: Math.PI / 8,
    minAzimuthAngle: -Math.PI / 12,
    maxAzimuthAngle: Math.PI / 12,
  },
  series: [{
    type: 'map3D',
    data: [
      { name: '北京', value: 100 },
      { name: '上海', value: 200 },
      { name: '广东', value: 300 },
    ],
  }],
});
</script>

TIP

map3D.pitch（初始俯仰角）是度数，而 minPolarAngle / maxPolarAngle 等限制字段是弧度，注意区分。

常见问题 ​

Q: 为什么地图不能水平旋转？ ​

A: 默认方位角限制为 ±15°，这是刻意设计，用于保持地图方向一致。可通过 map3D.minAzimuthAngle / map3D.maxAzimuthAngle 调整范围。

Q: 为什么地图无法缩得很远？ ​

A: 最远距离被限制为当前区域对角线 × 1.2，防止地图缩小到失去可读性。这是自动行为，无法配置。

Q: 如何让地图完全平躺？ ​

A: 将 map3D.maxPolarAngle 设置为接近 π/2（90°）即可，但不建议，水平视角下地图难以辨认。

相关文档 ​