Leaflet 快速上手：从零搭建交互式地图的完整实战指南-创锋一号

Leaflet 快速上手：从零搭建交互式地图的完整实战指南

【免费下载链接】Leaflet🍃 JavaScript library for mobile-friendly interactive maps 🇺🇦项目地址: https://gitcode.com/gh_mirrors/le/Leaflet

本篇指南是 Leaflet 官方 Quick Start 教程的深度讲解版，对应仓库 docs/examples/quick-start.md（教程主体位于 docs/examples/quick-start/ 目录）。你将学会：如何在页面中引入 Leaflet 2.0 的 ESM 模块与样式、初始化一张带 OpenStreetMap 瓦片的地图、添加 Marker（标记）、Circle（圆）、Polygon（多边形）与 Popup（弹窗），并通过事件系统响应用户的点击交互。读完即可独立编写一个可运行、可扩展的 Leaflet 地图应用。

一、预备工作：在页面中引入 Leaflet

在编写任何地图代码之前，需要先完成页面层面的准备工作。Leaflet 的引入分为 CSS 与 JavaScript 两步，且顺序有严格要求。

1. 在`<head>`中引入 Leaflet CSS

地图容器的样式、控件外观（缩放按钮、图层控件、比例尺）以及 Marker 图标的默认外观都定义在dist/leaflet.css中，必须放在文档<head>部分：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@2.0.0-alpha.1/dist/leaflet.css" integrity="..." crossorigin=""/>

当前仓库版本为2.0.0-alpha.1（见 package.json），因此示例中以该版本号加载 CDN 资源。integrity与crossorigin用于子资源完整性校验（SRI），生产环境建议保留。

2. 在 CSS 之后引入 Leaflet JavaScript（ESM）

仓库以 ESM 方式组织源码：所有公开 API 统一从 src/Leaflet.js 导出（export * from './map/index.js'、export * from './layer/index.js'等），构建产物为dist/leaflet.js。官方教程推荐使用浏览器原生支持的importmap机制来引入，无需打包器即可使用具名导入：

<!-- Make sure you put this AFTER Leaflet's CSS --> <script type="importmap"> { "imports": { "leaflet": "https://cdn.jsdelivr.net/npm/leaflet@2.0.0-alpha.1/dist/leaflet.js" }, "integrity": { "https://cdn.jsdelivr.net/npm/leaflet@2.0.0-alpha.1/dist/leaflet.js": "..." } } </script>

importmap的作用：它允许在浏览器中直接定义模块标识符（import路径），而无需依赖 bundler 工具链。通过 importmap，你可以直接从 CDN 或本地文件使用具名导入，模块解析更灵活、代码可读性更高。注意此脚本必须放在 Leaflet 的 CSS之后。

3. 放置地图容器`div`

在你希望显示地图的位置放置一个带id的div：

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

4. 为容器设置高度

地图容器必须有明确高度，否则地图无法渲染。最直接的方式是写 CSS：

#map { height: 180px; }

也可以像仓库示例 docs/examples/quick-start/example.md 那样使用内联样式：<div id='map' style='width: 600px; height: 400px;'></div>。宽度不设时默认占满可用宽度，但高度必须显式给出。

完成以上四步，就可以初始化地图了。

二、设置地图：创建实例并加载瓦片

1. 初始化地图实例

以伦敦市中心为示例，初始化地图并把视图定位到目标经纬度与缩放级别：

<script type="module"> import {LeafletMap, TileLayer, Marker, Circle, Polygon, Popup} from 'leaflet'; const map = new LeafletMap('map').setView([51.505, -0.09], 13); // ... </script>

说明：

new LeafletMap('map')接收容器 id（或 DOM 元素），并返回地图实例；
默认情况下（未传任何 options），所有鼠标与触屏交互均已启用（拖拽、缩放等），并且地图自带缩放控件（zoom control）与归属信息控件（attribution control）；
.setView(center, zoom)用于设置中心点与缩放级别，同时该方法返回地图对象本身。setView是Map的核心方法（见 src/map/Map.js），Leaflet 中大部分方法在没有显式返回值时都会返回this，从而支持类似 jQuery 的链式调用。

2. 添加 TileLayer 瓦片图层

接下来添加一个 OpenStreetMap 瓦片图层。创建瓦片图层通常需要设置三样东西：瓦片图片的URL 模板、归属信息（attribution）与图层的最大缩放级别：

new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', { maxZoom: 19, attribution: '&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>' }).addTo(map);

关键点：

URL 模板中的{z}（缩放级别）、{x}、{y}（瓦片坐标）占位符会被实际值替换——getTileUrl在 src/layer/tile/TileLayer.js 中实现模板替换逻辑；
maxZoom：示例设为 19。注意 TileLayer.js 中默认值为 18，应根据瓦片服务商支持的最大级别显式设置；
attribution：归属信息会显示在地图角落。Leaflet 本身对 provider 无偏好，代码中不包含任何 provider 专属逻辑，你可以自由选择任意瓦片服务商。

合规提醒：只要基于 OpenStreetMap 数据，就必须按要求标注归属信息（见 OpenStreetMap 版权声明）。大多数其他瓦片服务商（如 Mapbox、Stamen、Thunderforest）同样要求 attribution。生产环境使用 OSM 瓦片前，请务必阅读其 Tile Usage Policy。

顺带一提，TileLayer的构造函数还支持在 URL 模板中追加额外查询参数占位符（如{foo}），并在 options 中提供对应值；仓库源码甚至会在未指定 attribution 时自动填入 OSM 默认归属信息（src/layer/tile/TileLayer.js）。

注意：所有代码必须在div容器与leaflet.js引入之后执行。至此，你已经拥有一张可交互的 Leaflet 地图了。

三、添加 Marker、Circle 与 Polygon

除了瓦片图层，还可以向地图添加标记、折线、多边形、圆与弹窗等覆盖物。

1. 添加标记（Marker）

const marker = new Marker([51.5, -0.09]).addTo(map);

Marker接收一个[纬度, 经度]坐标数组，addTo(map)将其挂载到地图上（Marker的实现见 src/layer/marker/Marker.js）。

2. 添加圆（Circle）

圆的写法与标记类似，不同之处在于：

需要指定以米为单位的半径；
通过最后一个参数传入 options 控制外观：

const circle = new Circle([51.508, -0.11], { color: 'red', // 描边颜色 fillColor: '#f03', // 填充颜色 fillOpacity: 0.5, // 填充不透明度 (0~1) radius: 500 // 半径，单位：米 }).addTo(map);

3. 添加多边形（Polygon）

多边形同样简单，传入一组顶点坐标数组即可：

const polygon = new Polygon([ [51.509, -0.08], [51.503, -0.06], [51.51, -0.047] ]).addTo(map);

4. 添加折线（Polyline）

教程中提到你还可以添加折线（Polyline），它与 Polygon 的差别仅在是否自动闭合，同样以坐标点数组作为参数构造。

四、使用 Popup 弹窗展示信息

Popup 通常用于把信息附加到地图上的特定对象。

1. 快捷方式：bindPopup

Leaflet 提供了非常方便的快捷方法，把 HTML 内容绑定到图层对象上：

marker.bindPopup("<b>Hello world!</b><br>I am a popup.").openPopup(); circle.bindPopup("I am a circle."); polygon.bindPopup("I am a polygon.");

bindPopup(content)：为对象附加一个包含指定 HTML 内容的弹窗，点击对象时弹窗出现；
openPopup()：仅对 Marker 有效，用于立即打开已绑定的弹窗。

从源码看，bindPopup会创建内部Popup实例并与其关联，Marker的相关逻辑见 src/layer/marker/Marker.js 附近的_initInteraction部分——当用户点击标记时自动触发弹窗打开（对应 src/layer/Popup.js 附近的点击处理）。

⚠️安全提示：Popup 内容以 HTML 形式渲染，切勿直接传入不受信任的用户输入，以免造成 XSS 注入风险。

2. 独立使用 Popup 作为图层

当你需要的不仅是"附加到对象"时，可以把 Popup 当作独立图层使用：

const popup = new Popup() .setLatLng([51.513, -0.09]) .setContent("I am a standalone popup.") .openOn(map);

setLatLng设置弹窗在地图上的锚点位置；
setContent设置弹窗 HTML 内容；
这里使用openOn(map)而不是addTo(map)，因为openOn会自动关闭此前已打开的弹窗再打开新弹窗（见 src/layer/Popup.js），这对交互体验更友好——同一时刻只显示一个弹窗。

五、事件系统：响应地图交互

Leaflet 中每次发生用户交互（如点击 Marker、地图缩放变化）时，对应对象都会派发一个事件，你可以用监听函数订阅它并做出响应。

1. 基础用法：map.on

function onMapClick(e) { alert("You clicked the map at " + e.latlng); } map.on('click', onMapClick);

要点：

每个对象都有自己的事件集合，详见官方 reference 文档（仓库中可查看 docs/reference.html）；
监听函数的第一个参数是事件对象e，其中包含本次事件的有用信息。例如地图点击事件对象的latlng属性，就是点击发生的经纬度位置。

2. 进阶：用 Popup 替代 alert

把上面的示例改进为点击地图时在弹窗中显示坐标：

const popup = new Popup(); function onMapClick(e) { popup .setLatLng(e.latlng) .setContent("You clicked the map at " + e.latlng.toString()) .openOn(map); } map.on('click', onMapClick);

这里复用了同一个popup实例：每次点击都通过setLatLng移动弹窗位置、setContent更新坐标文本，再以openOn打开。由于openOn会先关闭旧弹窗，连续点击时不会出现弹窗堆积。

完整示例代码可查看仓库 docs/examples/quick-start/example.md，该文件把上述所有内容（瓦片图层、Marker、Circle、Polygon、独立 Popup、点击事件）整合进一个可运行的完整页面；基础版与覆盖物版分别见 example-basic.md 与 example-overlays.md。

六、本地查看与运行示例

仓库中的示例页面是静态 HTML，可通过 HTTP 服务直接预览。在仓库根目录执行：

npm run debug

该命令由 package.json 中的"debug": "http-server -c-1"定义，会在本地启动一个禁用缓存的静态文件服务器，随后在浏览器中访问对应路径即可查看quick-start示例及其 iframe 内嵌的可交互地图。

七、小结

通过本篇指南，你已经掌握了 Leaflet 的核心基础能力：

页面准备：按顺序引入leaflet.css与 ESM 版leaflet.js（推荐 importmap），准备带高度的容器div；
地图初始化：new LeafletMap('map').setView([lat, lng], zoom)配合链式调用；
瓦片图层：TileLayer+ URL 模板 +maxZoom+attribution；
覆盖物：Marker、Circle（米制半径 + 样式 options）、Polygon（顶点数组）；
弹窗：bindPopup/openPopup快捷绑定，或独立Popup+openOn；
事件：map.on('click', handler)，事件对象携带latlng等上下文信息。

下一步可以继续研读仓库中的完整 reference 文档或浏览其他示例（GeoJSON、自定义图标、图层控件、缩放级别、WMS 等主题），在此基础上构建自己的地图应用。

【免费下载链接】Leaflet🍃 JavaScript library for mobile-friendly interactive maps 🇺🇦项目地址: https://gitcode.com/gh_mirrors/le/Leaflet

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析