首页 / Leaflet / API 文档

TileLayer

先看结论

按 URL 模板加载栅格瓦片，是底图和叠加图层的基础类型。

最后验证 2026-11-03 · Leaflet 1.9.4 · 更新 2026-10-27 · 引用本文

L.tileLayer(urlTemplate, options) → TileLayer

URL 占位符

占位符	运行时替换为
`{z}`	瓦片缩放级别
`{x}`	列号
`{y}`	行号（TMS 服务需设 `tms: true` 翻转）
`{s}`	`subdomains` 中的一个字符
`{r}`	Retina 屏为 `@2x`，否则为空串

构造参数

参数	默认	说明
`minZoom`	0	低于该级别不显示此图层
`maxZoom`	18	高于该级别不请求瓦片；需与地图上限匹配
`subdomains`	'abc'	字符串或数组，替换 `{s}`
`errorTileUrl`	''	单张瓦片失败时的替代图片
`tileSize`	256	瓦片边长（像素）
`zoomOffset`	0	请求级别偏移，512 瓦片常配 −1
`zoomReverse`	false	反向编号的服务使用
`tms`	false	行号从南向北编号
`detectRetina`	false	高清屏自动减半 tileSize 并提高请求级别
`crossOrigin`	false	需要读取瓦片像素时开启
`noWrap`	false	禁止东西方向重复世界
`bounds`	—	仅在该 `LatLngBounds` 内请求瓦片
`keepBuffer`	2	视野外缓存圈数
`updateWhenIdle`	移动端 true	交互结束后才更新瓦片
`updateWhenZooming`	true	缩放动画过程中是否加载中间级别瓦片
`updateInterval`	200	更新瓦片的最小间隔（毫秒）
`opacity`	1	图层整体透明度
`zIndex`	1	同类型图层的堆叠顺序
`className`	''	附加到瓦片容器的类名
`attribution`	—	版权文字，显示在右下角

方法

方法	说明
`setUrl(url, noRedraw)`	替换模板，默认立即重绘
`setZIndex(n)`	调整层级
`setOpacity(n)`	设置透明度，0–1
`redraw()`	清空已加载瓦片并重新请求
`getContainer()`	返回瓦片容器 DOM 节点
`getTileUrl(coords)`	按 `{x,y,z}` 计算实际地址，调试模板时有用
`bringToFront()` / `bringToBack()`	在同级图层中前后移动
`addTo(map)` / `remove()`	加入或移除地图

事件

事件	触发时机	`e` 中的关键字段
`loading`	开始请求新瓦片	—
`load`	视野内瓦片全部就绪	—
`tileloadstart`	单张瓦片开始加载	`tile`、`coords`
`tileload`	单张瓦片加载完成	`tile`、`coords`
`tileerror`	单张瓦片失败	`tile`、`coords`、`error`
`tileunload`	瓦片被移出缓存	`tile`、`coords`

var tiles = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
  maxZoom: 19,
  attribution: '&copy; OpenStreetMap contributors',
  keepBuffer: 4
}).addTo(map);

tiles.on('load', function () {
  console.log('当前视野瓦片加载完成');
});

tiles.on('tileerror', function (e) {
  console.log('失败瓦片', e.coords, e.tile.src);
});

地图级别高于图层 maxZoom 时不会自动降级。 超出范围后 Leaflet 不再请求瓦片，画面保留上一次的内容并放大，看起来就是一片模糊。把地图的 maxZoom 一起限制住，或者选一个支持更高层级的底图。

运行时换源

setUrl 适合底图服务切换、或者给地址追加时间戳强制刷新。传入第二个参数 true 只改模板不重绘，等下一次视图变化时再生效，可以避免闪烁。

tiles.setUrl('https://tile.openstreetmap.org/{z}/{x}/{y}.png?v=2');
tiles.redraw();

引用本文

经纬志（2026）。《TileLayer》。https://www.jingweizhi.com/leaflet/api/tile-layer.html（访问日期 2026-11-03）。