JSAPIThree 加载 Mapbox 数据学习笔记：使用 Mapbox 矢量瓦片地图

作为一个刚开始学习 mapvthree 的小白，今天要学习加载 Mapbox 数据了！听说这个功能可以加载 Mapbox 的矢量瓦片地图，还能自定义样式！想想就期待！

第一次听说 Mapbox 数据加载

今天在文档里看到了"Mapbox"这个词。文档说 Mapbox 数据加载可以：

• 加载 Mapbox 官方地图
• 支持自定义 MVT 路径
• 需要配置 AccessToken

我的理解：简单说就是"用 Mapbox 的矢量瓦片地图"，让场景有 Mapbox 风格的地图底图！

第一步：配置 Mapbox AccessToken

作为一个初学者，我习惯先看看需要什么配置。文档说使用 Mapbox 服务需要配置 Mapbox AccessToken！

我的发现：Mapbox 需要 AccessToken 才能使用，这是必须的配置！

获取 Mapbox AccessToken

1. 访问 Mapbox Console 获取 accessToken
2. 在项目中配置

全局配置 AccessToken

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

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

// 配置 Mapbox accessToken
mapvthree.MapboxConfig.accessToken = '您的accessToken';

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

临时配置 AccessToken

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

const mapView = engine.add(new mapvthree.MapView({
    vectorProvider: new mapvthree.MapboxVectorTileProvider({
        accessToken: '您的accessToken', // 临时配置 Mapbox accessToken
    }),
}));

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

第二步：加载 MVT 地图

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

文档说可以用 MapboxVectorTileProvider 来加载 MVT 地图！

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

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

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

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

我的发现：MVT 地图是 Mapbox 标准的矢量瓦片地图，具有创建效率高、传输渲染速度快等特点！

我的理解：

• 优点：矢量瓦片，无级缩放不模糊，传输渲染速度快
• 缺点：需要 AccessToken
• 适用场景：需要 Mapbox 风格地图的场景

第三步：自定义 MVT 路径

看到可以加载 Mapbox 地图后，我想：能不能使用不同的地图样式？

文档说可以通过 style 参数来自定义 MVT 路径！

const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: null,
    vectorProvider: new mapvthree.MapboxVectorTileProvider({
        style: 'mapbox://styles/mapbox/streets-v9', // 自定义样式
    }),
}));

我的发现 ：可以通过 style 参数指定不同的 Mapbox 样式！

我的理解：

• mapbox://styles/mapbox/streets-v9：街道样式
• 可以使用其他 Mapbox 官方样式
• 也可以使用自定义样式

我的尝试：

// 使用不同的样式
const mapView1 = engine.add(new mapvthree.MapView({
    vectorProvider: new mapvthree.MapboxVectorTileProvider({
        style: 'mapbox://styles/mapbox/streets-v9', // 街道样式
    }),
}));

const mapView2 = engine.add(new mapvthree.MapView({
    vectorProvider: new mapvthree.MapboxVectorTileProvider({
        style: 'mapbox://styles/mapbox/satellite-v9', // 卫星样式
    }),
}));

我的发现：可以切换不同的地图样式，让地图更符合项目需求！

第四步：理解 MapView 结构

看到可以加载和修改样式后，我想：Mapbox 地图是怎么组织的？

文档说 MapView 是引擎中底图的容器，Mapbox 地图使用 VectorSurface 渲染。

我的理解：

• MapboxVectorTileProvider 是 VectorTileProvider
• 通过 vectorProvider 添加到 VectorSurface
• VectorSurface 渲染矢量数据时具备无级缩放不模糊的特点

我的发现：

• VectorSurface 会作为 3D 场景物体渲染
• 一般单个 VectorSurface 即可满足需求
• 多个 VectorSurface 叠加渲染时，需要注意图层之间的深度冲突

第五步：完整示例

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

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

// 全局配置 Mapbox accessToken
mapvthree.MapboxConfig.accessToken = '您的accessToken';

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

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

// 添加 Mapbox 矢量地图
const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: null,
    vectorProvider: new mapvthree.MapboxVectorTileProvider({
        style: 'mapbox://styles/mapbox/streets-v9', // 自定义样式
    }),
}));

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

第六步：踩过的坑

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

坑 1：地图不显示

原因：没有配置 Mapbox AccessToken，或者 AccessToken 配置错误。

解决：确保正确配置了 Mapbox AccessToken，可以全局配置或临时配置。

坑 2：样式不生效

原因：样式路径错误，或者 AccessToken 没有权限访问该样式。

解决：

1. 确保样式路径正确
2. 确保 AccessToken 有权限访问该样式

坑 3：地图显示空白

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

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

坑 4：性能问题

原因：创建了多个 MapView 实例，或者使用了复杂的样式。

解决：

1. MapView 性能开销较大，尽可能少创建 MapView 实例
2. 选择合适的地图样式，避免过于复杂

我的学习总结

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

1. 配置 Mapbox AccessToken：全局配置或临时配置
2. 加载 MVT 地图 ：使用 MapboxVectorTileProvider
3. 自定义 MVT 路径 ：通过 style 参数指定不同的样式
4. MapView 结构：理解 Mapbox 地图在 MapView 中的组织方式

我的感受：Mapbox 数据加载功能真的很强大！虽然配置有点复杂，但是用起来其实不难。关键是要理解 MVT 地图的特点，然后正确配置 AccessToken 和样式！

下一步计划：

1. 学习更多 Mapbox 样式的配置选项
2. 尝试创建自定义的 Mapbox 样式
3. 做一个完整的 Mapbox 地图展示项目

---

学习笔记就到这里啦！作为一个初学者，我觉得 Mapbox 数据加载虽然配置有点复杂，但是用起来其实不难。关键是要理解 MVT 地图的特点，然后正确配置 AccessToken 和样式！希望我的笔记能帮到其他初学者！大家一起加油！