Leaflet 简介

本文档全面介绍 Leaflet 库，涵盖其设计目标、架构原则、核心组件以及 2.0 版本中引入的重大现代化改进。本页聚焦于系统整体设计和入口点，帮助开发者理解 Leaflet 的组织方式以及如何高效使用。

如需了解特定组件的详细信息，请参阅核心架构、图层系统、用户交互或插件系统页面。

什么是 Leaflet

Leaflet 是一个领先的开源 JavaScript 库，用于构建交互式 Web 地图。它仅约 42 KB（gzipped）的 JavaScript 加上 4 KB 的 CSS，提供了一个完整的地图解决方案，专注于简洁性、性能和可用性。该库在所有主流桌面和移动平台上都能高效运行，同时保持简洁、文档完善的 API。

Leaflet 采用模块化架构，核心的 Map 类协调多个专门的子系统，包括图层（layers）、控件（controls）、事件处理和渲染。该库旨在处理大多数开发者需要的核心地图功能，同时通过丰富的插件生态系统保持可扩展性。

主入口点和模块结构

100%

核心系统概览

架构原则

Leaflet 围绕几个关键的架构原则构建，这些原则指导其设计和实现：

模块化 ESM 设计

从 2.0 版本开始，Leaflet 已过渡到完全模块化的 ES Module (ESM) 架构。该库不再使用单一的全局 L 对象，而是导出可以按需导入的各个类和工具函数：

// 现代 ESM 方式 (v2.0+)
import {Map, TileLayer, Marker} from 'leaflet';

// 传统方式 (v1.x)
const map = L.map('mapId');

基于类的架构

该库使用具有层次继承结构的 ES6 类。基础的 Class 提供了通用功能，如选项处理和初始化钩子（initialization hooks），而专门的类如 Layer、Control 和 Handler 则扩展了这一基础。

核心类层次结构

100%

事件驱动通信

Evented 基类在整个库中提供了一致的事件系统。事件从低层级的 DOM 交互流经图层和控件到达地图实例，实现了组件之间的松耦合。

核心组件

Leaflet 的功能被组织成几个主要的子系统，每个子系统处理地图的特定方面：

Map 组件

Map 类充当中央协调器，管理视图状态、坐标转换，并编排图层、控件和处理器（handlers）之间的交互。

图层系统（Layer System）

图层代表不同类型的地图内容，包括：

• TileLayer: 基于栅格瓦片的图层（例如 OpenStreetMap）
• Marker: 带图标的点状覆盖物
• Vector Layers: 几何形状，如折线（polylines）和多边形（polygons）
• LayerGroup: 作为单元管理的图层集合

控件和交互（Controls and Interaction）

用户界面组件，如缩放控件、图层切换器和版权归属（attribution），以及用于拖拽、缩放和键盘导航的事件处理器。

渲染管线（Rendering Pipeline）

独立的 Canvas 和 SVG 渲染器用于矢量图形，地图会根据浏览器能力和性能要求自动选择合适的渲染器。

组件关系

100%

2.0 版本现代化

Leaflet 2.0 代表了一项重大的现代化工作，使该库符合现代 JavaScript 实践，同时保持其核心设计理念：

破坏性变更（Breaking Changes）

领域	变更	影响
模块系统	UMD → 仅 ESM	需要 import 语句，无全局 L 对象
类系统	自定义类 → ES6 类	现代语法，更好的工具支持
事件	Mouse/Touch → Pointer Events	统一的输入处理
工厂方法	L.marker() → new Marker()	直接构造函数调用
浏览器支持	放弃 IE 支持	仅支持现代常青浏览器

迁移路径

从 v1.x 到 v2.0 的过渡需要更新代码模式：

// v1.x 模式
<script src="leaflet.js"></script>
<script>
  const map = L.map('map').setView([51.505, -0.09], 13);
  const tiles = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png')
    .addTo(map);
</script>

// v2.0 模式  
<script type="module">
  import {Map, TileLayer} from 'leaflet';
  
  const map = new Map('map').setView([51.505, -0.09], 13);
  const tiles = new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png')
    .addTo(map);
</script>

遗留兼容性

对于需要向后兼容的应用，Leaflet 提供了 leaflet-global.js，它恢复了全局 L 对象，同时还有社区 polyfills 可用于简化迁移。

开始使用 Leaflet

安装选项

Leaflet 可以通过多种方式集成到项目中：

包管理器（推荐）

npm install leaflet

使用 Import Maps 的 CDN

<script type="importmap">
{
  "imports": {
    "leaflet": "https://cdn.jsdelivr.net/npm/leaflet@2.0.0-alpha.1/dist/leaflet.js"
  }
}
</script>

直接下载 分发文件包括 leaflet.js（压缩版）、leaflet-src.js（可读版）、leaflet.css 和相关的 source maps。

基本使用模式

每个 Leaflet 应用都遵循类似的初始化模式：

1. 创建 Map 实例：使用容器和选项初始化地图
2. 添加基础图层：通常是用于地图背景的瓦片图层
3. 添加内容：标记、覆盖物和其他交互元素
4. 配置交互：根据需要设置事件处理器和控件

文件结构概览

Leaflet 源代码被组织成与主要系统组件相对应的逻辑目录：

源码目录结构

100%

目录	用途	关键文件
core/	基础类和工具函数	Class.js, Events.js, Browser.js
layer/	所有图层类型和渲染	Layer.js, tile/TileLayer.js
map/	核心地图功能	Map.js
control/	UI 控件和部件	Control.js, Control.Zoom.js
dom/	DOM 工具和事件处理	DomEvent.js, DomUtil.js
geometry/	几何数据结构	Point.js, Bounds.js
geo/	地理坐标系统	LatLng.js, CRS.js

这种模块化组织使开发者能够系统地理解代码库，并有助于 Leaflet 的可维护性和可扩展性。