Atlaslog / Field Notes / Tiles
Field note · Tiles
Zoom jumps from 17 straight to 19, skipping two levels
Quick answer
One wheel notch advances two zoom levels, and those skipped levels never render. `zoomDelta` was set to 2 while `zoomSnap` is 0.5, so every gesture moves two levels and the intermediate tile requests never happen.
Symptom
- `zoomend` logs 15, then 17, then 19 with each wheel step
- `map.options.zoomSnap` is `0.5` and `map.options.zoomDelta` is `2`
- Tile requests for z17 and z18 never appear and those levels stay grey
- A pinch gesture can jump from 15 to 18 at once
Checklist
- Log `map.getZoom()` inside `zoomend` to measure the step size
- Print `map.options.zoomSnap` and `map.options.zoomDelta`
- Search for runtime code that mutates `map.options`
- Call `map.setZoom(18)` and see whether the map can rest at 18
- Check `maxNativeZoom` against `maxZoom` for missing levels
Fix
Keep `zoomDelta` at 1 and never below `zoomSnap` (`zoomSnap: 0.5, zoomDelta: 1, wheelPxPerZoomLevel: 120`); when the tile set ends at 17, use `maxNativeZoom: 17, maxZoom: 19` so Leaflet upscales instead of skipping levels.
Code
map.on('zoomend', () => console.log(map.getZoom()));
console.log(map.options.zoomSnap, map.options.zoomDelta);
// 0.5 2 <- zoomDelta 为 2,滚轮一次跨两级const map = L.map('map', {
center: [39.909, 116.397],
zoom: 15,
minZoom: 10,
maxZoom: 19,
zoomSnap: 0.5, // 允许半级缩放
zoomDelta: 1, // 滚轮一次一级
wheelPxPerZoomLevel: 120
});
L.tileLayer('/tiles/{z}/{x}/{y}.png', {
minZoom: 10,
maxNativeZoom: 17,
maxZoom: 19
}).addTo(map);
Watch out
- Raising `maxZoom` to reach higher levels when tiles stop at 17, which leaves the missing levels grey
- Setting `zoomSnap: 0` without `wheelDebounceTime`, so one wheel event triggers several zoom changes
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Zoom jumps from 17 straight to 19, skipping two levels. https://www.jingweizhi.com/en/cookbook/minzoom-maxzoom-jump.html (accessed 2026-11-03).