JSAPIThree 加载天地图学习笔记：使用天地图影像服

作为一个刚开始学习 mapvthree 的小白，今天要学习加载天地图了！听说这个功能可以加载天地图的影像服务，作为场景的底图！想想就期待！

第一次听说天地图加载

今天在文档里看到了"天地图"这个词，一开始我还以为是某个地图库，结果查了一下才知道，原来这是国家基础地理信息中心提供的地图服务！

文档说天地图加载可以：

加载天地图影像服务
需要配置 token
可以作为场景的底图

我的理解：简单说就是"用天地图的影像服务"，让场景有天地图风格的地图底图！

第一步：配置天地图 Token

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

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

获取天地图 Token

访问天地图控制台获取 token
在项目中配置

全局配置 Token

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

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

// 配置天地图 token
mapvthree.TiandituConfig.tk = '您的token';

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

临时配置 Token

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

const mapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.TiandituImageryTileProvider({
        tk: '您的token', // 临时配置天地图 token
    }),
}));

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

第二步：加载天地图

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

文档说可以用 TiandituImageryTileProvider 来加载天地图！

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

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

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

// 添加天地图
const mapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.TiandituImageryTileProvider({
        // tk: '您的token', // 如果没有全局配置，可以在这里直接传入
    }),
}));

我的发现：天地图通过 imageryProvider 添加，作为影像图层使用！

我的理解：

优点：国家官方地图服务，数据权威
缺点：需要 token
适用场景：需要国家官方地图数据的场景

第三步：理解 MapView 结构

看到可以加载天地图后，我想：天地图是怎么组织的？

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

我的理解：

TiandituImageryTileProvider 是 ImageryTileProvider
通过 imageryProvider 添加到 RasterSurface
RasterSurface 能保证图层之间叠加顺序的正确性

我的发现：

RasterSurface 适合二维地图的渲染
多个 ImageryTileProvider 可以叠加渲染，并分层设置透明度
如果不设置地形，引擎内部会自动创建一个平面地形层

多个影像图层叠加

文档说可以同时加载多个影像图层：

const mapView = engine.add(new mapvthree.MapView({
    imageryProviders: [
        new mapvthree.TiandituImageryTileProvider({
            opacity: 1,
        }),
        // 可以添加其他影像图层
    ],
}));

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

第四步：完整示例

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

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

// 全局配置天地图 token
mapvthree.TiandituConfig.tk = '您的token';

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

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

// 添加天地图
const mapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.TiandituImageryTileProvider({
        // 使用全局配置的 token
    }),
}));

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

第五步：踩过的坑

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

坑 1：地图不显示

原因：没有配置天地图 token，或者 token 配置错误。

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

坑 2：地图显示空白

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

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

坑 3：token 过期

原因：天地图 token 可能过期。

解决：重新获取 token 并更新配置。

坑 4：性能问题

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

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

我的学习总结

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

配置天地图 Token：全局配置或临时配置
加载天地图：使用 TiandituImageryTileProvider
MapView 结构：理解天地图在 MapView 中的组织方式
图层叠加：可以同时加载多个影像图层

我的感受：天地图加载功能很实用！虽然配置有点复杂，但是用起来其实不难。关键是要理解 MapView 的结构，然后正确配置 token！

下一步计划：

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

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