经纬志 看得懂 · 跑得起来
首页 / Leaflet

Leaflet

最轻的二维地图库,压缩后约四十二 KB。标记、弹窗、绘制、图层控制这些常规需求,用它能最快做完。

Leaflet 1.9.4 · 教程 13 篇 · API 40 个 · 示例 35 个

一句话概览:Leaflet 是体积最小的主流二维地图库,压缩后约 42 KB,API 直白:地图、图层、标记、事件四类对象就能覆盖大多数业务。它不处理投影变换,默认使用 Web 墨卡托,适合快速搭起可交互的地图界面。

教程13 篇

01

社区精选资源

Leaflet 核心很薄,能力大多来自插件,所以"找资源"实际上是在找可靠的插件与官方示例。 这一页按类别整理官方仓库、教程…

02

绘制与编辑

Leaflet 核心库不带绘制工具。搞清楚「点击加顶点、双击收尾、顶点可拖拽」这条主线, 自己实现一个够用的绘制器并不复杂,…

03

事件与交互

Leaflet 所有对象都继承同一套事件接口:on、off、once。 难点不在绑定,而在分辨事件从哪来、会不会冒泡、触发频…

04

GeoJSON 数据加载

GeoJSON 是 Web 地图最通用的矢量交换格式。Leaflet 用一个 L.geoJSON 就能把点、线、面转成图层,…

05

图层与图层组

Leaflet 里地图上没有「图形」这个概念,只有图层。瓦片、标记、线、面、弹窗都是图层。 单个图层各自 addTo(map…

06

Marker 与自定义图标

标记是 Leaflet 里唯一用 DOM 绘制的图层,这让它可以放任意 HTML, 也让它在几千个以上时成为性能瓶颈。图标本…

07

十分钟做出第一张地图

Leaflet 压缩后只有四十多 KB,本身不绑定任何地图服务。做出第一张地图只要三件事:给容器高度、 初始化地图、加一层瓦…

08

移动端适配

Leaflet 自带触摸支持,双击缩放、双指缩放、拖动惯性都不需要额外配置。 手机上真正要处理的是三件事:容器高度、手指的点…

09

性能与大量点

Leaflet 的默认矢量渲染器是 SVG,每个要素对应一个 DOM 节点。 超过几千个点,瓶颈就不再是网络,而是 DOM…

10

插件生态与选型

Leaflet 核心只做地图容器、瓦片与基础矢量,绘制、聚合、测量、矢量瓦片全部靠插件。 插件质量参差,判断标准不是功能列表…

11

弹窗与提示

Popup 是点击后弹出的浮层,Tooltip 是悬停或常驻的小标签。 两者都挂在某个坐标或某个图层上,区别在于触发方式、默…

12

瓦片图层与底图切换

底图是地图的第一层内容,Leaflet 把它抽象成 TileLayer: 给出一个带占位符的 URL 模板,剩下的按视野计算…

13

视图控制与坐标转换

地图的「视图」由中心点与缩放级别决定。切换视图有四个方法,动画与精度各不相同; 坐标转换则负责在屏幕像素与经纬度之间来回换算…

API 文档40 个

使用示例35 个

多底图切换的运行效果截图

多底图切换

三套公开瓦片之间切换,中心点、缩放级别和上层要素保持不变,版权信息随底图自动更换。

查看示例
基础地图与缩放控制的运行效果截图

基础地图与缩放控制

一张能拖能缩的地图,包含瓦片底图、缩放按钮、版权信息和圆形矢量。

查看示例
坐标拾取的运行效果截图

坐标拾取

鼠标移动时实时读出经纬度、Web 墨卡托米制坐标与容器像素,点击可落点并复制。

查看示例
自定义控件的运行效果截图

自定义控件

继承 L.Control,做一个带城市跳转、缩放级别和鼠标坐标的右上角面板。

查看示例
自定义投影的运行效果截图

自定义投影

用平面坐标系承载厂区平面图,坐标单位直接是米,右下角保留一张 Web 墨卡托对照图。

查看示例
DivIcon 图标的运行效果截图

DivIcon 图标

四种完全由 CSS 画出来的标记:编号徽章、文字标签、脉冲点、靶标。

查看示例
圆形绘制的运行效果截图

圆形绘制

点两次画出米制半径的圆,移动鼠标时实时显示半径,落定后标注面积。

查看示例
绘制多边形的运行效果截图

绘制多边形

点击落点、双击闭合、拖动顶点改形,面积按球面公式实时计算,全程只用 Leaflet 核心 API。

查看示例
事件调试的运行效果截图

事件调试

把地图触发的所有事件实时列出来,附带坐标、像素、图层 id,用来核对交互行为。

查看示例
地图导出图片的运行效果截图

地图导出图片

把当前视野的瓦片与矢量拼到一张 canvas 上,导出为 PNG 并自动下载。

查看示例
要素编辑的运行效果截图

要素编辑

拖动标记修改位置,用侧栏表单改名称与类别,最后把整组要素导出成 GeoJSON。

查看示例
动画飞线的运行效果截图

动画飞线

北京到五个城市的弧线,光点沿路径推进并拖出尾迹,循环播放,错峰启动。

查看示例
全屏的运行效果截图

全屏

把地图容器铺满视口,切换后重新计算尺寸,Esc 退出,三步就能避免半屏白块。

查看示例
GeoJSON 图层的运行效果截图

GeoJSON 图层

一份包含点、线、面的 GeoJSON,按等级上色,可过滤要素、强调重点并随时恢复视野。

查看示例
经纬网格的运行效果截图

经纬网格

根据缩放级别自动切换步长,只在当前视野内生成经纬线与边缘标注,拖动后即时重绘。

查看示例
热力图的运行效果截图

热力图

用 leaflet.heat 把 1400 个带权重的采样点渲染成热力面,半径与模糊两个参数可实时调整。

查看示例
图像叠加的运行效果截图

图像叠加

把一张栅格图片按经纬度范围铺在地图上,并支持调透明度、切帧与显隐。

查看示例
惯性拖拽的运行效果截图

惯性拖拽

切换四组惯性参数,甩动地图后量出松手到停下的滑行距离。

查看示例
图层控制面板的运行效果截图

图层控制面板

自定义面板勾选四组覆盖物,带图层数量、全选与全不选,面板操作不会干扰地图拖拽。

查看示例
聚合标记的运行效果截图

聚合标记

700 个点在低缩放级别自动聚成簇,放大后逐级散开,也可以一键关掉聚合看原始分布。

查看示例
标记与弹出窗口的运行效果截图

标记与弹出窗口

六个标记、自定义圆点图标、点击弹窗和图层组批量增删,附带点击坐标回显。

查看示例
边界限制的运行效果截图

边界限制

把地图锁在一块矩形范围内,拖到边缘会停住,飞到范围外的城市会被钳回边界。

查看示例
测距的运行效果截图

测距

点击落点连成折线,每段距离与总长同时显示,双击结束,支持撤销与重新测量。

查看示例
鹰眼图的运行效果截图

鹰眼图

右下角缩略图显示主图在更大范围中的位置,主图移动时矩形跟随,点击缩略图反向跳转。

查看示例
离线瓦片的运行效果截图

离线瓦片

用本地生成的瓦片模拟离线包,浏览过的区域进缓存,断网后只出已缓存的块。

查看示例
图层顺序的运行效果截图

图层顺序

三个重叠的面分别放在自定义 pane 里,点按钮把任意一个提到最上层。

查看示例
多边形编辑的运行效果截图

多边形编辑

拖动顶点改变面的形状,点击地图追加顶点,面积随编辑实时刷新。

查看示例
Popup 定位的运行效果截图

Popup 定位

把标记放在贴右边缘的位置,逐项切换气泡的平移、偏移与宽度选项。

查看示例
比例尺控件的运行效果截图

比例尺控件

切换公制、英制、双单位与窄版比例尺,并用 100 像素实测值核对显示是否合理。

查看示例
瓦片缓存的运行效果截图

瓦片缓存

在内存里缓存已下载的瓦片图片,重复查看同一区域时不再发起网络请求。

查看示例
瓦片滤镜的运行效果截图

瓦片滤镜

不改底图地址,只给瓦片容器加 CSS 滤镜,就得到灰度、夜间、暖色、高对比四种风格。

查看示例
轨迹回放的运行效果截图

轨迹回放

26 个轨迹点按累计距离插值推进,支持进度拖动、三档倍速和视角跟随。

查看示例
视频叠加的运行效果截图

视频叠加

把视频画面钉在地图范围上播放,可调透明度、暂停,并在老浏览器上自动降级。

查看示例
WMS 图层的运行效果截图

WMS 图层

把 GeoServer 一类的 WMS 服务按 GetMap 请求叠在底图上,并演示参数切换与失败降级。

查看示例
缩放滑块的运行效果截图

缩放滑块

在右上角放一条缩放滑块,拖动即时改级别,地图缩放时滑块也同步回写。

查看示例

常见问题

标记显示不出来,图标是破图?
Leaflet 默认图标按相对路径查找,打包工具或子目录部署时路径会错。显式设置 L.Icon.Default 的 iconUrl、iconRetinaUrl、shadowUrl 三个路径即可。用 CDN 引入时,把路径指向 unpkg 上的 images 目录最省事。
能接高德、天地图这类国内底图吗?
可以。它们多为 XYZ 瓦片服务,用 L.tileLayer 直接接。要注意坐标系差异:高德使用 GCJ-02,与 WGS-84 存在几十到上百米偏移,业务点数据必须先转换,否则整体错位。
几千个标记卡顿怎么处理?
默认每个标记都是一个 DOM 节点,数量上去后必然卡。可以改用 L.canvas 渲染的 circleMarker,或引入 markercluster 做聚合,只渲染可视范围内的点。上万级数据建议直接换 deck.gl 或 Canvas 图层。