经纬志 看得懂 · 跑得起来
首页 / MapLibre GL JS

MapLibre GL JS

Mapbox GL JS v2 的 BSD-3 开源分支,API 基本一致但没有授权费用,也不需要账号。样式规范、矢量瓦片、表达式驱动样式都在。

MapLibre 4.x · 教程 13 篇 · API 45 个 · 示例 60 个

一句话概览:MapLibre GL JS 是 Mapbox GL JS v2 的开源分支,用 WebGL 渲染矢量瓦片地图。它保留了样式规范与表达式语法,API 与 Mapbox GL 高度一致,但以 BSD-3 许可发布,不需要账号或授权费用,适合自建瓦片服务的项目。

教程13 篇

01

相机与动画

MapLibre 的相机有六个自由度:中心点、缩放、旋转、倾斜。切换相机有四个方法, 动画由内部的缓动函数驱动,不是 CSS…

02

聚合与热力图

几万个点直接画圆,屏幕会糊成一片,性能也会掉下来。聚合把邻近的点折叠成带计数的圆, 热力图把点密度渲染成颜色渐变。两者解决同…

03

社区精选资源

MapLibre 是 Mapbox GL JS 的开源分支,资料常与 Mapbox 混在一起,版本与 API 前缀容易看串。…

04

表达式与属性驱动样式

样式里的颜色、宽度、半径都可以写成表达式,让同一个图层按要素属性或缩放级别自动变化。 表达式是 JSON 数组,第一个元素是…

05

GeoJSON 数据源

业务数据大多是 GeoJSON。加一个 source、配一个图层, 数据就上了图;后续更新只改 source 的 data,…

06

交互与控件

控件是加在容器上的 DOM 按钮,交互是地图对鼠标与触摸的响应。 MapLibre 把每个交互做成可独立开关的 handle…

07

与 Mapbox GL JS 的差异

MapLibre GL JS 是 Mapbox GL JS 1.x 的合法开源分支,采用 BSD-3 许可, 不需要 acc…

08

第一个 MapLibre 地图

MapLibre GL JS 用 WebGL 渲染矢量瓦片,交互、旋转、俯仰都是内置的。 起步只有两件事:给容器一个高度,再…

09

数据源类型

图层不直接持有数据,它引用 sources 里的一个键。数据源决定数据的组织形式与缩放行为, 选错类型通常表现为「图层画不出…

10

图标与字体

符号图层画两种东西:图标与文字。图标来自雪碧图(sprite)或运行时添加的图片, 文字来自字体切片(glyphs)。两者都…

11

样式与图层

MapLibre 里没有「往地图上画一个图形」这种操作,只有数据源和图层。 样式 JSON 描述的就是这两者的组合,运行时改…

12

样式规范 Style Spec

样式规范是一份 JSON 约定,规定地图应该长什么样:数据从哪来、按什么顺序画、 每个图层用什么颜色和尺寸。MapLibre…

13

3D 与地形

MapLibre 不是三维引擎,它的三维能力集中在三件事:用高程数据抬起地表、 用晕渲表现坡向、用拉伸把面变成柱体。三者都建…

API 文档45 个

使用示例60 个

线条流动动画的运行效果截图

线条流动动画

虚线间隔周期性轮换,视觉上形成沿线前进的流动感。这是最省资源的一种线条动画。

查看示例
标记沿路线移动的运行效果截图

标记沿路线移动

车辆标记沿配送路线匀速前进,进度实时显示。核心是把路线重采样成等距点。

查看示例
基础地图的运行效果截图

基础地图

一张可拖动、可旋转、可倾斜的矢量地图,带缩放按钮与比例尺, 底图使用 MapLibre 官方 demo 样式,不需要…

查看示例
框选要素的运行效果截图

框选要素

按住 Shift 拖出一个框,松手后框内要素全部选中并标红,数量实时统计。

查看示例
Canvas 动态栅格源的运行效果截图

Canvas 动态栅格源

把一块 canvas 当作栅格图层贴到地图上,每帧重绘,适合雷达扫描、热力动画这类实时画面。

查看示例
点击符号居中的运行效果截图

点击符号居中

点击城市标签,地图带动画飞过去并放大到城市级别。

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

点聚合

320 个点在低缩放时合并成圆簇,数字表示数量,点击后自动放大到能看清单点的级别。 聚合全部在浏览器里完成,不需要服…

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

自定义控件

左上角三个按钮:复位、放大、缩小。控件只是返回一个 DOM 元素, 加上约定的类名就能沿用内置样式。

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

自定义图标

水滴图标由 canvas 画出,注册进样式后作为 icon-image 使用。 不依赖图片文件,也不受跨域限制。

查看示例
属性驱动的线样式的运行效果截图

属性驱动的线样式

路网宽度读车道数,颜色读道路等级,一份数据画出层次分明的路网。

查看示例
禁用地图旋转的运行效果截图

禁用地图旋转

只允许平移和缩放,右键拖拽、双指旋转、键盘旋转全部关闭,视角始终朝北。

查看示例
可拖动标记的运行效果截图

可拖动标记

标记可以按住拖动,拖动过程中实时回读经纬度,松手后弹窗显示落点与相对中心的偏移。

查看示例
拖动 GeoJSON 点的运行效果截图

拖动 GeoJSON 点

不是 DOM 标记,而是源里的一个点要素。按住圆点拖动时改写坐标并 setData,底图保持不动。

查看示例
画圆的运行效果截图

画圆

点击定圆心,半径可调,圆环按球面公式逐点算出,缩放时形状保持正确。

查看示例
动态改样式的运行效果截图

动态改样式

同一份矢量瓦片,三套配色在按钮间即时切换。改的是绘制属性, 不是整份样式,图层的顺序、过滤与数据都不受影响。

查看示例
查询指针下的要素的运行效果截图

查询指针下的要素

指针移到色块上,侧栏列出该位置命中的所有要素,重叠区域会同时返回多个。

查看示例
3D 挤出的运行效果截图

3D 挤出

49 个面按属性拉成体块,高度与颜色都由 height 决定。 高度倍数滑块改变整体观感,不触碰数据。

查看示例
按输入过滤符号的运行效果截图

按输入过滤符号

输入城市名或拼音首字母,圆点与文字同时过滤,计数实时更新。

查看示例
缩放到范围的运行效果截图

缩放到范围

给定一个矩形,fitBounds 自动选择缩放级别与中心, 留出边距后让范围完整可见。这是数据上图后最常用的定位方式…

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

飞行动画

跨越半个地球的视角切换用 flyTo,缩放会先拉远再推近, 比直接跳转更容易让观看者建立方位感。

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

GeoJSON 线

一条从北京经南京、上海到海口的路线,虚线样式, 六个节点用 circle 图层单独绘制。

查看示例
绘制 GeoJSON 点的运行效果截图

绘制 GeoJSON 点

站点用圆点表示,大小读客流、颜色读类型,再用文字层补名称。

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

GeoJSON 面

两个示意范围的矩形面,颜色来自要素属性。 填充与边界分两个图层,边界可以单独开关。

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

热力图

点太密时改用密度着色。热力图的半径是像素单位, 所以同一份数据在不同缩放下呈现的聚集范围会变化。

查看示例
悬停高亮的运行效果截图

悬停高亮

指针移入圆点时半径变大、颜色变橙,移出恢复。状态写在 feature-state 里,不重建数据源。

查看示例
影像源的运行效果截图

影像源

单幅图片按四角坐标铺到地图上,适合规划图、历史地图与范围固定的影像。 换图与移动都在同一个源上完成,图层不需要重建。

查看示例
标注避让的运行效果截图

标注避让

150 个编号标注挤在同一个区域,默认只画出互不遮挡的那部分。 勾选「允许重叠」后全部绘出,顶部数字实时对比两种策略…

查看示例
按钮改图层颜色的运行效果截图

按钮改图层颜色

四个色板按钮切换片区填充色,带 300ms 过渡,不闪跳。

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

图层切换

京广、京沪、陇海三条线路分别放在独立图层。 复选框只改布局属性,不重建图层,切换没有闪烁。

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

图层显隐

一个数据源挂三个图层,勾选框分别控制面、线与标注。 显隐只改布局属性,数据与图层都留在内存里,切回来立即出现。

查看示例
线渐变色的运行效果截图

线渐变色

一条线从起点到终点渐变着色,颜色沿线的进程推进,适合表达方向或累计量。

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

线图层

一条线路三层画法:深色描边打底、渐变主线表示进度、虚线区分规划段。 线宽滑块同时改主线与描边,保持比例。

查看示例
实时更新数据的运行效果截图

实时更新数据

每 700 毫秒推送一个新位置,轨迹线增长、车辆点前移。 数据更新只调用 setData,地图视角和图层都保持不变。

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

地图截图

点一下按钮,把当前视角连同图层导出成 PNG,右侧立即出现缩略图与下载链接。 关键开关只有一个:preserveDr…

查看示例
添加标记的运行效果截图

添加标记

六个城市各放一个标记,颜色区分,点击后读取名称与坐标。 标记是 DOM 元素,适合数量不多但需要交互的场景。

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

边界限制

地图被锁在中国范围内的矩形里,往外拖会被拉回。 点「跳到范围外」可以看到目标中心被自动夹取后的结果。

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

量测距离

逐点点击落位,实时显示累计球面距离,支持撤销与清空。

查看示例
读取鼠标经纬度的运行效果截图

读取鼠标经纬度

指针移动时显示经纬度与屏幕坐标,右下角常驻一个等宽字体读数面板。

查看示例
多地图联动的运行效果截图

多地图联动

左右两幅地图同源,左侧可操作,右侧自动跟随。 四组视角参数逐帧同步,缩放差始终显示为 0.00。

查看示例
不可交互的地图的运行效果截图

不可交互的地图

一张纯展示的静态地图,所有手势关闭,只保留程序控制的跳转与弹窗。

查看示例
离线缓存的运行效果截图

离线缓存

瓦片请求先经过 Cache API,命中就直接返回,未命中才走网络并顺手存一份。 预制当前视野后,同样的画面不再产生…

查看示例
用内边距偏移消失点的运行效果截图

用内边距偏移消失点

右侧有 280px 面板时,让目标点落在剩余区域正中,而不是被面板压住。

查看示例
路径动画的运行效果截图

路径动画

橙色轨迹沿折线向前生长,头部圆点始终压在末端,右侧进度与里程同步跳动。 全程只在两处小数据上调用 setData。

查看示例
性能优化的运行效果截图

性能优化

同一份 8000 点数据,热力图与圆点两种画法切换,右上角实时显示帧率。 「重建数据」按钮给出一次 setData…

查看示例
设置俯仰与朝向的运行效果截图

设置俯仰与朝向

俯仰控制地平线进入画面的程度,朝向决定正北在屏幕上的方向。两个滑块加三个预设,读数双向同步。

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

面图层

20 个网格单元按数值分级着色,鼠标移上去透明度提高并显示数值。 高亮用的是要素状态,不重建数据,移动鼠标不会卡顿。

查看示例
多边形图案填充的运行效果截图

多边形图案填充

面图层用斜纹、圆点、网格三种图案填充,切换时只改一个属性名。

查看示例
弹窗的运行效果截图

弹窗

点击地图任意位置,弹窗显示该点的经纬度与当前缩放。 弹窗复用一个实例,关闭后再打开不会残留旧节点。

查看示例
弹出卡片的运行效果截图

弹出卡片

点击橙色站点,弹出一张带标题、数值条与时间的卡片。 内容用 DOM 节点构建,不是拼接字符串,数值变化时也能直接复用…

查看示例
点击弹窗的运行效果截图

点击弹窗

点击告警点打开详情弹窗,点地图空白处关闭。弹窗实例只有一个,内容按要素属性替换。

查看示例
悬停弹窗的运行效果截图

悬停弹窗

指针移到网点上,弹窗跟着指针走,移出图层立即消失。

查看示例
栅格瓦片的运行效果截图

栅格瓦片

一张张正射或扫描瓦片直接铺在画布上,配一个透明度滑块与明暗切换, 就能验证瓦片地址、尺寸与跨域是否都对。

查看示例
实时数据流的运行效果截图

实时数据流

每 0.9 秒推入一个新的观测点,缓冲满 40 条后丢弃最早的。 颜色与半径按数值分级,越新的点序号越大。

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

天空层

白天天蓝、黄昏地平线偏暖、夜间整体压暗,三套预设只改一组颜色与混合系数。 天空在俯仰为 0 时不可见,倾斜后才进入视…

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

符号图层

城市点位配英文名,字号随缩放连续变大,滑块再乘一个系数。 符号图层同时负责文字与图标,碰撞检测是它默认开启的能力。

查看示例
地形与晕渲的运行效果截图

地形与晕渲

高程瓦片让地面真正起伏,晕渲图层在没有影像时也能读出山谷走向。 夸张系数与晕渲强度分开控制,便于比较真实比例与视觉表…

查看示例
3D 地形倾斜的运行效果截图

3D 地形倾斜

地图倾斜到 62 度,叠加高程瓦片后山脊有了起伏。 夸张系数控制在 1 附近最接近真实比例,调得过高会显得像沙盘。

查看示例
切换交互开关的运行效果截图

切换交互开关

六个复选框分别控制平移、缩放、旋转、双击、框选和键盘,随时开关。

查看示例
矢量瓦片的运行效果截图

矢量瓦片

同一份 PBF 瓦片,用三个图层分别画面、边界与国名。 换颜色、改字号都不需要重新切片,这是矢量瓦片与栅格瓦片最实在…

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

视频源

视频按四角坐标铺成图层,暂停、播放、查询时长都由 source 对象控制。 浏览器拦截自动播放时,第一帧仍会显示,点…

查看示例

常见问题

MapLibre 和 Mapbox GL JS 差在哪?
渲染能力与样式规范基本一致,主要差别在服务与授权:MapLibre 不绑定 Mapbox 账号,也不使用 Mapbox 的托管瓦片,底图与数据源要自己提供。API 层面命名空间从 mapboxgl 换成 maplibregl,少量方法有差异。
底图必须用 Mapbox 的瓦片吗?
不需要。任何符合矢量瓦片规范的服务都能接,包括自建的 TileServer、开源的 demotiles,以及国内的矢量切片服务。只要在 style 的 sources 里写对 tiles 模板和 source-layer 即可。
样式里的表达式不生效?
先确认表达式写在支持它的属性上,例如 paint 的图层属性,而不是 layout 中不接受表达式的项。其次检查数据类型:表达式里的 get 取值是字符串还是数字,类型不匹配时会静默失效。最后确认 style 版本号与表达式语法匹配。