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

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

第一次听说天地图加载

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

文档说天地图加载可以：

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

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

第一步：配置天地图 Token

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

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

获取天地图 Token

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

全局配置 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 中叠加多个图层。

我的学习总结

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

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

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

下一步计划：

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

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