MapV Three 掩膜功能
一句话解释
TileMask 是 MapV Three 提供的区域掩膜功能，可以让地图瓦片只在指定的地理区域内显示，实现精准的区域限制效果。
为什么需要掩膜功能？
你有没有遇到过这样的需求：做一个湖南省的数据可视化项目，但地图总是会显示周边省份的内容？或者想做一个"显示除了某个区域以外的所有地图"这样的反向效果？
这就是掩膜功能要解决的问题！通过 TileMask，我们可以：
- ✅ 只显示特定省份或城市的地图内容
- ✅ 反向显示某个区域以外的地图
- ✅ 动态切换显示区域
- ✅ 让自定义的 3D 对象也遵循相同的掩膜规则
这个功能在做区域聚焦展示、行政区域对比、专题地图制作时特别实用！
📖 快速上手 TileMask
第一步：准备区域数据
首先，我们需要准备一个 GeoJSON 格式的区域数据。比如湖南省的边界数据：
const regionData = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
geometry: {
type: 'Polygon',
coordinates: [
[
[111.5, 28.0],
[112.0, 28.0],
[112.0, 29.0],
[111.5, 29.0],
[111.5, 28.0]
]
]
}
}
]
};
第二步：创建 TileMask
接下来就是创建掩膜对象了，这里有个特别重要的点！
// 1. 创建地图引擎
const engine = new mapvthree.Engine(document.getElementById('container'), {
map: { is3DControl: true },
rendering: { enableAnimationLoop: true }
});
// 2. 添加矢量地图
const vectorMap = new mapvthree.BaiduVectorMap();
engine.add(vectorMap);
// 3. 获取 TileProvider（重点来了！）
const vectorProvider = vectorMap.vectorSurface.tileProvider;
// 4. 创建 TileMask
const tileMask = engine.add(new mapvthree.TileMask({
targets: [vectorProvider], // 注意：这里是 TileProvider，不是 vectorMap！
region: regionData
}));
⚠️ ：TileMask 的 targets 参数需要传入 TileProvider 对象，而不是 MapView 或者其他对象！
掩膜的核心功能
创建好 TileMask 之后，我们就可以玩转各种掩膜效果了！
1. 启用和禁用掩膜
这个最简单，一行代码搞定：
// 启用掩膜
tileMask.enabled = true;
// 禁用掩膜
tileMask.enabled = false;
启用后，地图就只会显示湖南省边界内的内容了，其他区域都会被遮挡掉。
2. 动态更新掩膜区域
掩膜区域不是一成不变的，你可以随时切换到新的区域：
// 创建一个新的矩形区域
const newRegion = {
type: 'Feature',
geometry: {
type: 'Polygon',
coordinates: [[
[110.0, 27.0],
[113.0, 27.0],
[113.0, 30.0],
[110.0, 30.0],
[110.0, 27.0]
]]
}
};
// 更新掩膜区域
tileMask.region = newRegion;
比如做一个省份切换的功能，用户点击按钮就能切换到不同省份的掩膜效果，就是这样实现的！
🎨 让自定义对象也遵循掩膜规则
有时候我们不光想让地图瓦片遵循掩膜规则，还想让场景中的自定义 3D 对象也应用同样的掩膜效果。MapV Three 提供了两种方式：
方式一：注册整个对象
// 创建一个 Three.js 的盒子
const boxGeometry = new THREE.BoxGeometry(20, 20, 20);
const boxMaterial = new THREE.MeshBasicMaterial({
color: 0x00ff00,
transparent: true,
opacity: 0.5
});
const box = new THREE.Mesh(boxGeometry, boxMaterial);
// 将整个对象注册到掩膜系统
tileMask.addNeedsMaskedObject(box);
这种方式最简单，TileMask 会自动处理对象的材质。
方式二：直接注册材质
// 只注册材质
tileMask.addNeedsMaskedMaterial(boxMaterial);
这种方式更灵活，适合多个对象共用同一个材质的情况。
总结
总结一下 TileMask 的使用要点：
- 创建时机：在添加矢量地图后创建 TileMask
- targets 参数：必须传入
TileProvider - region 参数：使用 GeoJSON 格式的 Polygon 数据，确保坐标闭合
- enabled 属性：控制掩膜的启用和禁用
- 动态更新：可以随时修改 region 属性来切换掩膜区域
- 自定义对象：使用
addNeedsMaskedObject或addNeedsMaskedMaterial让自定义对象也应用掩膜
思考
TileMask 还可以用在哪些有趣的场景吗？比如：
- 动态的台风影响范围展示？
- 根据用户权限显示不同的地图区域？
- 结合时间轴做历史疆域变迁动画？
你在项目中有用过类似的区域限制功能吗？遇到过什么有趣的需求或者踩过什么坑？欢迎在评论区分享你的经验！
希望这篇文章能帮助你更好地理解和使用 MapV Three 的掩膜功能。如果你觉得有用，别忘了点赞收藏～下次见！👋
