Leaflet Wiki

简体中文

English

简体中文

English

Appearance

Leaflet 快速入门指南 ​

这份分步指南将快速帮助你入门 Leaflet 基础知识，包括设置 Leaflet 地图、使用标记（markers）、折线（polylines）和弹出框（popups），以及处理事件。

准备你的页面 ​

在编写任何地图代码之前，你需要在页面上完成以下准备步骤：

  • 在你的文档 head 部分引入 Leaflet CSS 文件：

    html
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@{{ site.latest_leaflet_version}}/dist/leaflet.css"
	integrity="{{site.integrity_hash_css}}"
	crossorigin=""/>

  • 在 Leaflet CSS 之后引入 Leaflet JavaScript 文件：

    html
    <!-- 确保将此代码放在 Leaflet CSS 之后 -->
<script type="importmap">
{
	"imports": {
		"leaflet": "https://cdn.jsdelivr.net/npm/leaflet@{{ site.latest_leaflet_version}}/dist/leaflet.js"
	},
	"integrity": {
		"https://cdn.jsdelivr.net/npm/leaflet@{{ site.latest_leaflet_version}}/dist/leaflet.js": "{{site.integrity_hash_uglified}}"
	}
}
</script>

    importmap 允许在浏览器中定义模块标识符（import 路径），而无需依赖打包工具。它支持直接从 CDN 或本地文件使用命名导入，使模块解析更加灵活和可读。

  • 在你想要显示地图的位置放置一个带有特定 id 的 div 元素：

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

  • 确保地图容器有定义的高度，例如在 CSS 中设置：

#map { height: 180px; }

现在你可以初始化地图并开始使用它了。

设置地图 ​

让我们创建一个以伦敦市中心为中心的地图，使用漂亮的 OpenStreetMap 瓦片。从现在开始，我们将在 JavaScript 中工作。首先初始化地图并将其视图设置为我们选定的地理坐标和缩放级别：

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

	// ...
</script>

默认情况下（因为我们在创建地图实例时没有传递任何选项），地图上启用了所有鼠标和触摸交互，并具有缩放和版权归属（attribution）控件。

注意 setView 调用也返回地图对象 —— 大多数 Leaflet 方法在不返回显式值时都会这样，这允许方便的类似 jQuery 的方法链式调用。

接下来，我们将向地图添加一个瓦片图层，这里使用的是 OpenStreetMap 瓦片图层。创建瓦片图层通常需要设置瓦片图像的 URL 模板、版权归属文本和图层的最大缩放级别。OpenStreetMap 瓦片适合用于编程开发你的 Leaflet 地图，但如果在生产环境中使用这些瓦片，请阅读 OpenStreetMap 的 瓦片使用政策。

javascript
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);

确保所有代码都在引入 div 和 leaflet.js 之后调用。就是这样！你现在有了一个可以工作的 Leaflet 地图。

值得注意的是，Leaflet 是与供应商无关的（provider-agnostic），这意味着它不强制要求使用特定的瓦片提供商。而且，Leaflet 甚至不包含任何特定于供应商的代码行，所以如果需要，你可以自由使用其他提供商。

无论何时使用基于 OpenStreetMap 的内容，根据版权声明，attribution（版权归属）是强制性的。大多数其他瓦片提供商（如 Mapbox、Stamen 或 Thunderforest）也需要版权归属。确保在适当的地方给予致谢。

标记（Markers）、圆形和多边形 ​

除了瓦片图层外，你可以轻松地向地图添加其他元素，包括标记、折线、多边形、圆形和弹出框。让我们添加一个标记：

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

添加圆形也是一样的（除了以米为单位指定半径作为第二个参数），但允许你在创建对象时通过传递选项来控制其外观：

javascript
const circle = new Circle([51.508, -0.11], {
	color: 'red',
	fillColor: '#f03',
	fillOpacity: 0.5,
	radius: 500
}).addTo(map);

添加多边形同样简单：

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

使用弹出框（Popups） ​

弹出框通常用于当你想向地图上的特定对象附加一些信息时。Leaflet 为此提供了一个非常方便的快捷方式：

javascript
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 方法将一个带有指定 HTML 内容的弹出框附加到你的标记上，这样当你点击该对象时弹出框就会出现，而 openPopup 方法（仅用于标记）会立即打开附加的弹出框。

你也可以将弹出框作为图层使用（当你需要的不只是向对象附加弹出框时）：

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

这里我们使用 openOn 而不是 addTo，因为它会自动处理打开新弹出框时关闭之前打开的弹出框，这对用户体验很有好处。

处理事件 ​

每当 Leaflet 中发生某些事情时，例如用户点击标记或地图缩放改变，相应的对象会发送一个事件，你可以用函数订阅它。这允许你响应用户交互：

javascript
function onMapClick(e) {
	alert("You clicked the map at " + e.latlng);
}

map.on('click', onMapClick);

每个对象都有自己的一组事件 —— 详情请参见文档。监听器函数的第一个参数是事件对象 —— 它包含有关发生的事件的有用信息。例如，地图点击事件对象（上面示例中的 e）具有 latlng 属性，即点击发生的位置。

让我们通过使用弹出框代替 alert 来改进我们的示例：

javascript
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);

尝试点击地图，你将在弹出框中看到坐标。查看完整示例 →

现在你已经学会了 Leaflet 的基础知识，可以立即开始构建地图应用了！别忘了查看详细的文档或其他示例。

Copyright © 2026 LZUGIS