🎈 大家好，我是河豚
🌍 个人博客：河豚的前端之路
这里不是官方文档，是我个人翻译的中文文档，官方文档请移步MapLibre GL JS。
如果本文档有错误，欢迎到博客联系我！将会及时修复。

介绍

MapLibre GL JS 是一个TypeScript库，它使用WebGL在浏览器中从矢量瓦片渲染交互式地图。地图的自定义符合MapLibre样式规范。它是MapLibre生态系统的一部分，其对应的Android、iOS和其他平台版本称为MapLibre Native;

快速开始

<div id="map"></div>
<script>
    var map = new maplibregl.Map({
        container: 'map', // 容器id
        style: 'https://demotiles.maplibre.org/style.json', // 样式URL
        center: [0, 0], // 起始位置 [经度, 纬度]
        zoom: 1 // 起始缩放级别
    });
</script>

阅读本文档

本文档分为几个部分:

主要部分 - 主要部分包含以下类
- Map对象是页面上的地图。它允许您访问方法和属性来与地图的样式和图层交互，响应事件，并通过相机操作用户视角;
- 全局函数让您设置全局属性和选项，您可能在初始化地图或访问其状态信息时需要这些属性和选项;
标记和控件 - 本节描述了可以添加到地图中的用户界面元素。本节中的项目存在于地图的canvas元素之外。这包括Marker、Popup和所有控件;
地理和几何 - 本节包括与处理和操作地理信息或几何图形相关的通用工具和类型;
用户交互处理器 - 本节中的项目与地图响应用户输入的方式相关;
数据源 - 本节描述了MapLibre GL JS可以处理的源类型，除了MapLibre样式规范中描述的类型之外;
事件相关 - 本节描述了MapLibre GL JS可以引发的不同类型的事件;

每个部分描述类或对象及其属性、参数、实例成员和相关事件。许多部分还包括内联代码示例和相关资源;

在示例中，我们使用来自Demo tiles仓库和MapTiler的矢量瓦片。如果您想在项目中使用MapTiler数据，请获取您自己的API密钥;

NPM

通过NPM安装MapLibre GL JS包;

npm install maplibre-gl

然后您可以在项目中导入MapLibre GL JS模块;

<div id="map"></div>

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new maplibregl.Map({
    container: 'map', // 容器id
    style: 'https://demotiles.maplibre.org/style.json', // 样式URL
    center: [0, 0], // 起始位置 [经度, 纬度]
    zoom: 1 // 起始缩放级别
});

CSP指令

作为跨站脚本和其他类型的Web安全漏洞的缓解措施，您可以使用内容安全策略(CSP)为您的网站指定安全策略。如果您这样做，MapLibre GL JS需要以下CSP指令:

worker-src blob: ;
child-src blob: ;
img-src data: blob: ;

对于没有启用worker-src blob: ; child-src blob:的严格CSP环境，有一个单独的MapLibre GL JS包(maplibre-gl-csp.js和maplibre-gl-csp-worker.js)，它需要手动设置worker的路径:

<script>
maplibregl.setWorkerUrl("${urls.js().replace('.js', '-csp-worker.js')}");
...
</script>

MapLibre CSS

快速入门中引用的CSS用于设置MapLibre代码创建的DOM元素的样式。没有CSS，弹出窗口和标记等元素将无法工作;

通过UNPKG CDN在文档头部使用<link>包含CSS是最简单和最容易提供CSS的方式，但它也被捆绑在MapLibre模块中，这意味着如果您有一个可以处理CSS的打包工具，您可以从maplibre-gl/dist/maplibre-gl.css导入CSS;

还要注意，如果CSS在第一次渲染时不可用，一旦提供CSS，依赖于此CSS的DOM元素应该会恢复;

CDN

MapLibre GL JS也通过UNPKG分发。我们的最新版本可以通过在html的<head>中添加以下标签来安装。关于如何选择特定版本和semver范围的更多说明可以在unpkg.com上找到;

<script src="https://unpkg.com/maplibre-gl@^5.5.0/dist/maplibre-gl.js"></script>
<link href="https://unpkg.com/maplibre-gl@^5.5.0/dist/maplibre-gl.css" rel="stylesheet" />