JSAPIThree 加载百度地图学习笔记：让地图成为场景的底图这是一篇关于 JSAPIThree（mapvthree）

作为一个刚开始学习 mapvthree 的小白，今天要学习加载百度地图了！听说这个功能可以让百度地图成为场景的底图，还能加载实时路况！想想就实用！

第一次听说百度地图加载

今天在文档里看到了"百度地图"这个词，一开始我还以为是百度地图 API，结果查了一下才知道，原来这是用来在 3D 场景中加载百度地图底图的功能！

文档说百度地图加载可以：

加载百度矢量地图
加载百度栅格地图
加载百度实时路况
支持个性化地图样式
支持图层叠加

我的理解：简单说就是"把百度地图放到 3D 场景里当底图"，让场景有真实的地图背景！

第一步：配置百度地图 AK

作为一个初学者，我习惯先看看需要什么配置。文档说使用百度地图需要配置百度地图开发者密钥（AK）！

我的发现：百度地图需要 AK 才能使用，这是必须的配置！

获取百度地图 AK

访问百度地图开放平台，登录您的百度账号
在控制台页面点击"创建应用"
填写应用名称，选择应用类型为"浏览器端"
创建完成后，您将获得一个 AK 密钥

全局配置 AK

获取 AK 后，在项目的入口处进行配置，全局执行一次即可：

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

// 配置百度地图 AK
mapvthree.BaiduMapConfig.ak = '您的AK密钥';

我的理解：全局配置后，使用百度地图的所有服务都不需要再配置了！

临时配置 AK

如果没有全局配置，可以在构造函数参数中临时配置：

const mapView = engine.add(new mapvthree.MapView({
    vectorProvider: new mapvthree.BaiduVectorTileProvider({
        ak: '您的AK密钥', // 临时配置百度地图AK
    }),
}));

我的发现：可以全局配置，也可以临时配置，根据需求选择！

第二步：理解 MapView 结构

看到需要配置 AK 后，我想：怎么加载地图？

文档说 MapView 是引擎中底图的容器，负责底图的创建、更新、销毁等操作。

我的理解：MapView 是地图的容器，所有的地图图层都在这里面！

MapView 的结构

MapView 包含两种 Surface：

RasterSurface：负责栅格图的渲染
VectorSurface：负责矢量图的渲染

我的发现：

RasterSurface：适合二维地图的渲染，能保证图层之间叠加顺序的正确性
VectorSurface：会作为 3D 场景物体渲染，无级缩放不模糊，但需要更多性能开销

我的注意：MapView 性能开销较大，请尽可能少创建 MapView 实例！

第三步：加载百度矢量地图

看到 MapView 后，我想：怎么加载百度矢量地图？

文档说可以用 BaiduVectorTileProvider 来加载百度矢量地图！

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

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [120.359, 30.223],
        range: 10000,
        provider: null, // 设置为 null，稍后手动添加
        projection: 'EPSG:3857',
    },
});

// 添加百度矢量地图
const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: null,
    vectorProvider: new mapvthree.BaiduVectorTileProvider({
        // ak: '您的AK密钥', // 如果没有全局配置AK，可以在这里直接传入
    }),
}));

我的发现：矢量地图会作为 3D 场景物体渲染，无级缩放不模糊！

我的理解：

优点：无级缩放不模糊，适合 3D 场景
缺点：需要更多性能开销
适用场景：3D 场景展示

第四步：加载百度栅格地图

看到矢量地图后，我想：能不能加载栅格地图？

文档说可以用 Baidu09ImageryTileProvider 来加载百度栅格地图！

// 添加百度栅格地图
const mapView = engine.add(new mapvthree.MapView({
    imageryProviders: [
        new mapvthree.Baidu09ImageryTileProvider({
            opacity: 1,
            // ak: '您的AK密钥', // 如果没有全局配置AK，可以在这里直接传入
        }),
    ],
}));

我的发现：栅格地图通过 imageryProviders 数组添加，可以设置透明度！

我的理解：

优点：性能好，适合二维地图
缺点：缩放会模糊
适用场景：二维地图展示

第五步：加载百度实时路况

看到栅格地图后，我想：能不能加载实时路况？

文档说可以用 BaiduTrafficTileProvider 来加载百度实时路况！

// 添加百度实时路况
const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: null,
    vectorProvider: new mapvthree.BaiduTrafficTileProvider({
        // ak: '您的AK密钥', // 如果没有全局配置AK，可以在这里直接传入
    }),
}));

我的发现：实时路况也是通过 vectorProvider 添加的！

我的理解：实时路况可以显示当前的道路拥堵情况，很实用！

第六步：图层叠加

看到可以加载不同类型的地图后，我想：能不能同时加载多个图层？

文档说可以同时加载多个影像图层，并分层设置透明度！

// 通过构造函数创建多个影像图层
const mapView = engine.add(new mapvthree.MapView({
    imageryProviders: [
        new mapvthree.Baidu09ImageryTileProvider({
            opacity: 1,
        }),
        new mapvthree.BaiduTrafficTileProvider({
            opacity: 0.5, // 路况图层设置为半透明
        }),
    ],
}));

我的发现：可以同时加载多个图层，通过 opacity 控制透明度！

我的理解：

多个 ImageryTileProvider 可以叠加渲染
可以分层设置透明度
VectorTileProvider 也可以作为 ImageryTileProvider 使用，引擎内部会先将矢量图层渲染为栅格图

动态添加图层

文档说可以在之后动态添加影像图层：

const mapView = engine.add(new mapvthree.MapView({}));

// 动态添加影像图层
mapView.rasterSurface.addImageryProvider(new mapvthree.Baidu09ImageryTileProvider({}));

我的发现：可以动态添加图层，不需要在初始化时全部配置好！

第七步：个性化地图样式

看到可以加载地图后，我想：能不能自定义地图样式？

文档说可以设置个性化地图样式，通过百度地图个性化编辑器获取个性化样式配置！

const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: null,
    vectorProvider: new mapvthree.BaiduVectorTileProvider(),
}));

// 设置个性化地图样式
mapView.getTileProvidersByName('BaiduVectorTileProvider')[0].setMapStyle({
    styleJson: [
        {
            "featureType": "land",
            "elementType": "geometry",
            "stylers": {
                "color": "#fffff9ff"
            }
        },
        {
            "featureType": "water",
            "elementType": "geometry",
            "stylers": {
                "color": "#69b0acff"
            }
        },
        // ... 更多样式配置
    ]
});

我的发现：可以自定义地图的颜色、样式等，让地图更符合项目需求！

我的理解：

通过 setMapStyle 设置样式
样式配置是一个数组，每个元素定义一种地图元素的样式
可以通过百度地图个性化编辑器生成样式配置

第八步：完整示例

我想写一个完整的示例，把学到的都用上：

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

// 全局配置百度地图 AK
mapvthree.BaiduMapConfig.ak = '您的AK密钥';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [120.359, 30.223],
        range: 10000,
        provider: null, // 设置为 null，稍后手动添加
        projection: 'EPSG:3857',
    },
});

// 添加百度矢量地图
const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: null,
    vectorProvider: new mapvthree.BaiduVectorTileProvider(),
}));

// 或者添加栅格地图和路况图层叠加
const mapView2 = engine.add(new mapvthree.MapView({
    imageryProviders: [
        new mapvthree.Baidu09ImageryTileProvider({
            opacity: 1,
        }),
        new mapvthree.BaiduTrafficTileProvider({
            opacity: 0.5,
        }),
    ],
}));

我的感受：写一个完整的示例，把学到的都用上，感觉很有成就感！

第九步：踩过的坑

作为一个初学者，我踩了不少坑，记录下来避免再犯：

坑 1：地图不显示

原因：没有配置百度地图 AK，或者 AK 配置错误。

解决：确保正确配置了百度地图 AK，可以全局配置或临时配置。

坑 2：地图显示空白

原因：在引擎初始化时设置了 provider，但没有正确配置。

解决：如果手动添加 MapView，需要将 provider 设置为 null。

坑 3：图层叠加顺序不对

原因：多个图层叠加时，顺序设置不对。

解决：imageryProviders 数组中的顺序决定了图层的叠加顺序，后面的图层在上层。

坑 4：个性化样式不生效

原因：样式配置格式错误，或者没有正确获取 TileProvider。

解决：

确保样式配置格式正确
使用 getTileProvidersByName 正确获取 TileProvider

坑 5：性能问题

原因：创建了多个 MapView 实例。

解决：MapView 性能开销较大，尽可能少创建 MapView 实例，尽量在一个 MapView 中叠加多个图层。

我的学习总结

经过这一天的学习，我掌握了：

配置百度地图 AK：全局配置或临时配置
MapView 结构：包含 RasterSurface 和 VectorSurface
百度矢量地图：使用 BaiduVectorTileProvider，无级缩放不模糊
百度栅格地图：使用 Baidu09ImageryTileProvider，性能好
百度实时路况：使用 BaiduTrafficTileProvider，显示道路拥堵情况
图层叠加：可以同时加载多个图层，设置透明度
个性化样式：通过 setMapStyle 自定义地图样式

我的感受：百度地图加载功能真的很实用！虽然配置有点复杂，但是用起来其实不难。关键是要理解 MapView 的结构，然后根据需求选择合适的图层类型！

下一步计划：

学习更多地图图层的配置选项
尝试创建复杂的图层叠加效果
做一个完整的地图展示项目

学习笔记就到这里啦！作为一个初学者，我觉得百度地图加载虽然配置有点复杂，但是用起来其实不难。关键是要理解 MapView 的结构，然后根据需求选择合适的图层类型！希望我的笔记能帮到其他初学者！大家一起加油！