MapLibre GL JS第33课：渲染世界副本

📌 学习目标

掌握渲染世界副本的实现方法
理解相关API的使用
能够独立完成类似功能开发

🎯 核心概念

在渲染单个世界和多个世界副本之间切换。

💻 完整代码

代码示例

js 复制代码

const map = new maplibregl.Map({
    container: 'map', // 地图容器id
    style: 'https://demotiles.maplibre.org/style.json', // 样式文件位置
    center: [179, 0], // 中心点位置
    zoom: 0.01 // 缩放
});

const renderOptions = document.getElementById('menu');
const inputs = renderOptions.getElementsByTagName('input');

function switchRenderOption(option) {
    const status = option.target.id;
    map.setRenderWorldCopies(status === 'true');
    map.panTo(map.getCenter());
}

for (let i = 0; i < inputs.length; i++) {
    inputs[i].onclick = switchRenderOption;
}

代码示例

html 复制代码

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Render world copies</title>
    <meta property="og:description" content="使用 setRenderWorldCopies 在渲染单个世界和渲染多个世界副本之间切换。" />
    <meta property="og:created" content="2023-06-27" />
    <meta charset='utf-8'>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel='stylesheet' href='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css' />
    <script src='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js'></script>
    <style>
        body { margin: 0; padding: 0; }
        html, body, #map { height: 100%; }
    </style>
</head>
<body>
<style>
    #menu {
        position: absolute;
        top: 0;
        left: 0;
        background: #fff;
        padding: 10px;
        font-family: 'Open Sans', sans-serif;
    }
</style>

<div id="map"></div>
<div id="menu">
    <div>Set <code>renderWorldCopies</code> to:</div>
    <div>
        <input type="radio" id="true" name="rtoggle" value="true" checked />
        <label for="true">true</label>
    </div>
    <div>
        <input type="radio" id="false" name="rtoggle" value="false" />
        <label for="false">false</label>
    </div>
</div>

<script>
    const map = new maplibregl.Map({
        container: 'map', // 容器ID
        style: 'https://demotiles.maplibre.org/style.json', // 样式表位置
        center: [179, 0], // 初始位置 [经度, 纬度]
        zoom: 0.01 // 初始缩放级别
    });

    const renderOptions = document.getElementById('menu');
    const inputs = renderOptions.getElementsByTagName('input');

    function switchRenderOption(option) {
        const status = option.target.id;
        map.setRenderWorldCopies(status === 'true');
        map.panTo(map.getCenter());
    }

    for (let i = 0; i < inputs.length; i++) {
        inputs[i].onclick = switchRenderOption;
    }
</script>
</body>
</html>

🔍 代码解析

初始化地图

使用 new maplibregl.Map() 创建地图实例，配置基本参数。本示例的核心特色是展示如何使用 setRenderWorldCopies() 方法在渲染单个世界和多个世界副本之间切换。

javascript 复制代码

const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json',
    center: [179, 0],  // 靠近180度经线
    zoom: 0.01
});

关键配置项

container: 地图容器的 DOM 元素 ID
style : 使用 MapLibre 官方样式 https://demotiles.maplibre.org/style.json
center : 地图初始中心点 [179, 0]，靠近180度经线，便于观察世界副本效果
zoom: 初始缩放级别为 0.01，接近全球视图

世界副本切换逻辑

javascript 复制代码

function switchRenderOption(option) {
    const status = option.target.id;
    map.setRenderWorldCopies(status === 'true');
    map.panTo(map.getCenter());  // 刷新视图
}

API 说明：

setRenderWorldCopies(true): 启用世界副本渲染，在主地图左右两侧显示重复的世界图像
setRenderWorldCopies(false): 禁用世界副本渲染，只显示单个世界，地图边缘会被截断

事件绑定

javascript 复制代码

const renderOptions = document.getElementById('menu');
const inputs = renderOptions.getElementsByTagName('input');

for (let i = 0; i < inputs.length; i++) {
    inputs[i].onclick = switchRenderOption;
}

遍历所有单选按钮，为每个按钮绑定点击事件处理函数。

HTML 控制界面

页面左上角有一个切换菜单（#menu），包含两个单选按钮：

true: 启用世界副本渲染，显示多个世界
false: 禁用世界副本渲染，只显示单个世界

html 复制代码

<div id="menu">
    <div>Set <code>renderWorldCopies</code> to:</div>
    <div>
        <input type="radio" id="true" name="rtoggle" value="true" checked />
        <label for="true">true</label>
    </div>
    <div>
        <input type="radio" id="false" name="rtoggle" value="false" />
        <label for="false">false</label>
    </div>
</div>

⚙️ 参数说明

地图初始化参数

参数	类型	必填	默认值	说明
container	string	是	-	地图容器元素的 ID
style	string/object	是	-	地图样式 URL 或内联样式对象
center	$number, number$	否	`[0, 0]`	初始中心点坐标，格式为 `[经度, 纬度]`
zoom	number	否	`0`	初始缩放级别，范围 0-22
renderWorldCopies	boolean	否	`true`	是否在初始化时启用世界副本渲染

setRenderWorldCopies 参数

参数	类型	必填	说明
render	boolean	是	是否渲染世界副本，`true` 启用，`false` 禁用

🎨 效果说明

运行代码后，页面显示一个交互式地图，左上角有世界副本切换控件（#menu）：

启用世界副本（true）：地图会在主世界的左右两侧显示重复的世界副本，用户可以无缝地跨越180度经线查看地图，就像地图是无限延伸的一样
禁用世界副本（false）：只显示单个世界，地图边缘会被截断，当拖拽到地图边缘时会遇到边界

地图默认显示全球视图（zoom: 0.01），中心位于179°E附近（靠近180度经线），便于观察世界副本效果。用户可以：

点击单选按钮切换世界副本渲染模式
鼠标拖拽移动地图，观察世界副本的连续性
滚轮缩放地图，查看不同缩放级别下的效果
右键旋转视角，调整观察角度

当启用世界副本时，从179°E向东拖拽地图，可以看到重复的世界图像，实现无缝的全球浏览体验。

💡 常见问题

Q1: 什么是世界副本渲染？

A: 世界副本渲染会在主地图的左右两侧显示重复的世界图像，让用户能够无缝地跨越180度经线查看地图，就像地图是无限延伸的一样。这对于需要连续浏览全球范围的应用非常有用。

Q2: 什么时候需要启用世界副本渲染？

A: 适用于需要查看跨越180度经线区域的场景，如：

太平洋地区的航线规划和可视化
跨越国际日期变更线的数据分析
全球范围的连续可视化展示
需要无缝拖拽浏览的全球地图应用

Q3: 启用世界副本会影响性能吗？

A: 会有一定的性能影响，因为需要渲染额外的瓦片（通常是主地图的2-3倍）。在低缩放级别（显示全球）或移动设备上，建议根据性能情况决定是否启用。

Q4: 如何在地图初始化时设置世界副本？

A: 在地图初始化时设置 renderWorldCopies 选项：

javascript 复制代码

const map = new maplibregl.Map({
    container: 'map',
    style: 'style.json',
    renderWorldCopies: true  // 初始启用世界副本
});

Q5: 世界副本渲染和 Globe 投影有什么关系？

A: Globe 投影是球面投影，本身就是连续的，不需要世界副本渲染。世界副本渲染主要用于 Web Mercator 等平面投影，让平面地图看起来是连续的。

Q6: 世界副本的数量有限制吗？

A: MapLibre GL JS 会根据地图视口自动计算需要渲染的世界副本数量，通常在左右两侧各渲染1-2个副本，具体取决于缩放级别和视口大小。

📝 练习任务

基础练习 ：修改 center 参数为 [0, 0]（非洲附近），观察世界副本效果的变化
进阶挑战：添加一个按钮，实现世界副本的平滑切换，并显示当前状态提示
拓展练习：添加缩放级别监听，当缩放级别大于5时自动禁用世界副本，小于等于5时自动启用
拓展思考：如何在 globe 投影模式下处理世界副本渲染？是否需要世界副本？

🌟 最佳实践

按需启用: 根据应用场景决定是否启用世界副本渲染，避免不必要的性能开销
用户控制: 提供用户界面让用户可以切换世界副本模式，提升用户体验
性能优化: 在移动设备或低性能设备上默认禁用世界副本，或根据设备性能动态调整
投影适配: Globe 投影模式下通常不需要世界副本渲染，因为球面本身是连续的
边界处理: 配合180度经线跨越处理，确保跨越180度的数据正确显示
测试验证: 在不同缩放级别和区域测试世界副本渲染效果
缩放控制: 在高缩放级别（如 zoom > 5）时禁用世界副本，因为此时用户关注的是局部区域
状态管理: 保存用户的世界副本偏好设置，下次访问时恢复

🔗 延伸阅读

Map API文档
MapLibre GL JS 官方文档
$下一课预告$ ：将继续学习地图图层的基础知识

本文是MapLibre GL JS实践课程系列的一部分，欢迎关注收藏

MapLibre GL JS第33课：渲染世界副本

📌 学习目标

🎯 核心概念

💻 完 整 代 码

代码示例

代码示例

🔍 代码解析

初始化地图

关键配置项

世界副本切换逻辑

事件绑定

HTML 控制界面

⚙️ 参数说明

地图初始化参数

setRenderWorldCopies 参数

🎨 效果说明

💡 常 见 问 题

📝 练习任务

🌟 最佳实践

🔗 延伸阅读

💻 完整代码

💡 常见问题