百度地图 JSAPI Three 介绍与快速上手指南

原创已于 2025-11-14 17:41:02 修改 · 857 阅读

26 ·

CC 4.0 BY-SA版权

文章标签：

#前端 #数据可视化 #3d

于 2025-11-10 14:54:00 首次发布

学习百度地图JSAPIThree 专栏收录该内容

3 篇文章

订阅专栏

一、概述简介

JSAPI Three 是百度地图推出的一套 基于 Three.js 的三维数字孪生地图服务引擎
它能够支持 2D、2.5D、3D 各种地理投影和数据源加载。也就是说，既可以用于平面地图展示，又可以用于三维场景，甚至地球（球体）模式。
支持多种地理投影系统，例如 EPSG:3857、EPSG:4978、EPSG:4326 等不同的坐标 / 投影，可以把多个不同投影的数据整合到同一张图上。
它提供“真地球模式”，可以实现类似电子地球仪的效果（从地球模式到平面地图进行丝滑切换 / 变换视角），包括卫星场景展示。
所有组件之间互相兼容，3D 中的遮盖关系（遮挡）能够正确表现，视觉效果保持一致性。
渲染是基于 WebGL 容器完成的，性能开销较低，非常适合用于大屏展示。
同时具备丰富的环境表现形式，例如天空 /大气效果，可根据时间变化（日出 / 日落），支持晴天、阴天、雨、雪等天气状态切换，也可以渲染动态水系。

简而言之，JSAPI Three 是一个整合地图 + 三维渲染 +数字孪生能力的前端 / Web 地图引擎，非常适合需要三维可视化 /地理数据可视化 /三维模型的场景。

二、核心优势 / 特点

特性维度	说明
一体化能力	一套引擎即可支持平面 (2D)、倾斜 /浅 2.5D (有高程 /倾斜效果)、真正的 3D (三维模型、地形、建筑等) 场景展示。
多投影支持	支持不同投影 /坐标系统 (EPSG:3857 / 4978 / 4326) 等，可以把不同来源 /不同投影的数据整合到同一个视图里。
真地球 / 地球模式	能实现电子地球仪样式，从地球模式切换到平面地图，并且可以展示卫星影像场景。
组件兼容与遮挡关系	在三维环境里，组件（模型 /覆盖物 /地形 /建筑等）之间遮挡 /遮盖关系可以正确显示，不会混乱。
性能 /大屏体验	使用 WebGL 容器渲染，性能开销比某些复杂渲染低，更适合大屏展示或复杂三维场景。
环境表现丰富	支持天空 /大气 /时间变化（日夜变化） /多种天气 (晴 /阴 /雨 /雪) /水系动态效果等，可用于更真实 /沉浸式的三维环境。

三、安装 / 引入方式

根据官方文档 “Install” 指南 (教程)，可以这样快速引入 /安装 JSAPI Three：

1. npm 安装

官方提供 npm 包：@baidumap/mapv-three，配合 three.js 使用。
示例

npm i -S @baidumap/mapv-three
安装完成后，就可以在前端项目（如 React / Vue /Vanilla JS）中 import 使用。

2. 静态资源 /静态资源配置

安装包中可能包含静态资源 (assets / 模型 /贴图等) 需要拷贝到项目的静态目录。这样地图 /三维模型 /贴图 /GLB 模型等资源可以被访问。
在构建配置里（如 webpack / vite /其他打包工具）可以通过 copy plugin 或静态目录配置将这些 assets 拷贝或复制到输出目录。示例中有将 mapvthree/dist/assets 拷贝到输出静态目录。

3. 配置百度地图 AK（密钥）

使用 JSAPI Three 之前，需要先在百度地图开放平台申请开发者密钥 (AK)。
在项目中将密钥配置到 mapvthree.BaiduMapConfig.ak 或其他配置对象中。比如示例中使用 mapvthree.BaiduMapConfig.ak = '您的AK'。
确保资源 (静态资源 /脚本) 在加载前已经配置好 AK，以保证能够正常加载地图 /数据。

四、Hello World 示例 / 快速上手 Demo

下面是一个简单的 “Hello World” 示例流程：

示例流程

在 html 或前端环境中引入 mapv-three + three.js，并配置 AK。
创建一个地图 /引擎 (Engine) 实例，指定初始化参数 (例如中心点 /投影 /视角 /pitch /heading /range 等)。
渲染一个简单的三维场景 (例如地图底图、地球模式或平面模式) 作为起始场景。
可以添加基本元素，例如点 (point) /模型 (3D model) /覆盖物 (覆盖几何体) 以验证是否成功加载。

示例代码

import * as mapvthree from '@baidumap/mapv-three';
import * as THREE from 'three';

mapvthree.BaiduMapConfig.ak = '你的AK';

const engine = new mapvthree.Engine(document.getElementById('container'), {
  map: {
    provider: new mapvthree.BaiduVectorTileProvider(), // 矢量底图 provider
    center: [116.404, 39.915, 0],  // 经纬度 + 高度 (示例)
    pitch: 0,
    heading: 0,
    range: 100,
    projection: 'EPSG:4326'       // 示例投影
  },
  rendering: {
    enableAnimationLoop: true
  }
});

// 添加简单 3D 模型或覆盖物
const model = new mapvthree.SimpleModel({
  name: 'demo-model',
  point: [116.404, 39.915, 0],
  scale: 1,
  object: 'path/to/model.glb'
});
engine.add(model);

注意事项

容器 (如 div#container) 必须设置好宽高，使得地图 /渲染容器可见。
引擎 /地图初始化参数如中心点 /投影 /视角需根据实际需求设定。
模型 /静态资源路径需正确配置 assets，否则模型 /纹理可能加载失败。

五、小结 /使用建议

如果你的项目需要丰富的三维可视化 (比如三维建筑 /倾斜摄影 /模型 /几何体 /高程 /天气 /水系效果等)，JSAPI Three 是非常合适的选择，因为它提供整合地图 + 三维模型 +环境渲染的能力。
如果仅仅是平面地图 /2D地图 /移动端简单应用，也可以考虑使用 JSAPI 的其他版本 (如 GL 或普通 3.0 / 2D 地图引擎)。官方文档也指出 JSAPI Three 与其他版本是并行的引擎，不能简单通过替换 script /命名空间进行升级。
对于前端开发者 /可视化项目，也可以把静态资源 /三维模型 /数据加载整合在你的可视化 pipeline 中，效果会比较丰富。