[feature]L.TiledLayer支持视野范围外预加载瓦片

AI-GEN: 70% Cursor

Author: luoxiao-supermap

src/leaflet/core/Base.js

@@ -4,6 +4,7 @@
 import L from "leaflet";
 import './Proj4Leaflet';
 import './TileLayerCache';
+import './TileLayerBuffer';
 import Attributions from './Attributions';
 
 L.Control.Attribution.include({

src/leaflet/core/TileLayerBuffer.js

@@ -0,0 +1,28 @@
+/* Copyright© 2000 - 2026 SuperMap Software Co.Ltd. All rights reserved.
+ * This program are made available under the terms of the Apache License, Version 2.0
+ * which accompanies this distribution and is available at http://www.apache.org/licenses/LICENSE-2.0.html.*/
+import L from 'leaflet';
+
+/**
+ * 扩展 Leaflet `L.TileLayer`，在视野外预加载若干圈同级瓦片，减少平移时的空白块。
+ * `_getTiledPixelBounds` 定义在 `L.GridLayer`，TileLayer 继承该方法；此处覆盖后仅对 TileLayer 及其子类生效。
+ *
+ * @param {number} [options.bufferTiles=0] - 视野外预加载的瓦片圈数。默认 0 表示不预加载；为 1 时上下左右各多加载一圈。支持小数。
+ */
+var originalGetTiledPixelBounds = L.GridLayer.prototype._getTiledPixelBounds;
+
+L.TileLayer.mergeOptions({
+    bufferTiles: 0
+});
+
+L.TileLayer.include({
+    _getTiledPixelBounds: function (center) {
+        var pixelBounds = originalGetTiledPixelBounds.call(this, center);
+        var bufferTiles = this.options.bufferTiles;
+        if (bufferTiles > 0) {
+            var pad = this.getTileSize().multiplyBy(bufferTiles);
+            pixelBounds = new L.Bounds(pixelBounds.min.subtract(pad), pixelBounds.max.add(pad));
+        }
+        return pixelBounds;
+    }
+});

src/leaflet/core/TileLayerCache.js

@@ -4,7 +4,7 @@
 import L from 'leaflet';
 
 /**
- * 扩展 Leaflet `L.TileLayer`，提供与 Mapbox GL 类似的瓦片填充：
+ * 扩展 Leaflet `L.TileLayer`：
  * 1. 放大时沿用原生父级瓦片占位，不提前拆掉原级别。
  * 2. 额外保留邻近缩放级别的已加载瓦片（含放大前四周的瓦片）。
  * 3. 被裁掉的瓦片进入内存缓存；再次需要时立刻复用，缺失的再发请求。

src/leaflet/mapping/BaiduTileLayer.js

@@ -18,6 +18,7 @@ import Attributions from '../core/Attributions'
  * @param {L.LatLngBounds} [options.bounds=L.latLngBounds([-85.0511287798, -180],[85.0511287798, 180])] - 显示范围。
  * @param {L.Browser} [options.retina=L.Browser.retina] - 浏览器显示分辨率。
  * @param {string} [options.tileProxy] - 服务代理地址。
+ * @param {number} [options.bufferTiles=0] - 视野外预加载的瓦片圈数。默认 0 表示不预加载；为 1 时上下左右各多加载一圈，可减少平移时的空白块。支持小数。
  * @param {boolean} [options.tileCache=false] - 是否启用客户端瓦片内存缓存。开启后，缩放时优先使用已缓存瓦片填充（放大后再缩小可避免空白块），再按需请求新瓦片。
  * @param {number} [options.tileCacheZoomRange=5] - 动态缓存相对当前视野的缩放范围倍数。缓存上限为视野瓦片数 × tileCacheZoomRange。
  * @param {number} [options.maxOverzooming=8] - 缩放时保留父级（更低级别）瓦片的深度，用于放大过程中的占位填充。

src/leaflet/mapping/CloudTileLayer.js

@@ -18,6 +18,7 @@ import Attributions from '../core/Attributions'
  * @param {number} [options.minZoom=3] - 最小缩放级别。
  * @param {number} [options.maxZoom=18] - 最大缩放级别。
  * @param {string} [options.mapName='quanguo'] - 地图名称。
+ * @param {number} [options.bufferTiles=0] - 视野外预加载的瓦片圈数。默认 0 表示不预加载；为 1 时上下左右各多加载一圈，可减少平移时的空白块。支持小数。
  * @param {boolean} [options.tileCache=false] - 是否启用客户端瓦片内存缓存。开启后，缩放时优先使用已缓存瓦片填充（放大后再缩小可避免空白块），再按需请求新瓦片。
  * @param {number} [options.tileCacheZoomRange=5] - 动态缓存相对当前视野的缩放范围倍数。缓存上限为视野瓦片数 × tileCacheZoomRange。
  * @param {number} [options.maxOverzooming=8] - 缩放时保留父级（更低级别）瓦片的深度，用于放大过程中的占位填充。

src/leaflet/mapping/ImageTileLayer.js

@@ -26,6 +26,7 @@ import { SecurityManager } from '@supermapgis/iclient-common/security/SecurityMa
  * @param {string} [options.format='png'] - 瓦片表述类型，瓦片格式目前支持 png、jpg 和 webp 三种格式。
  * @param {boolean} [options.transparent=true] - 瓦片是否透明。默认透明。
  * @param {boolean} [options.cacheEnabled=true] - 是否启用服务端缓存。
+ * @param {number} [options.bufferTiles=0] - 视野外预加载的瓦片圈数。默认 0 表示不预加载；为 1 时上下左右各多加载一圈，可减少平移时的空白块。支持小数。
  * @param {boolean} [options.tileCache=false] - 是否启用客户端瓦片内存缓存。与 cacheEnabled（服务端缓存）不同；开启后缩放时优先使用已缓存瓦片填充（放大后再缩小可避免空白块），再按需请求新瓦片。
  * @param {number} [options.tileCacheZoomRange=5] - 动态缓存相对当前视野的缩放范围倍数。缓存上限为视野瓦片数 × tileCacheZoomRange。
  * @param {number} [options.maxOverzooming=8] - 缩放时保留父级（更低级别）瓦片的深度，用于放大过程中的占位填充。

src/leaflet/mapping/TiandituTileLayer.js

@@ -23,6 +23,7 @@ import Attributions from '../core/Attributions';
  * @param {Array.<number>} [options.subdomains=[0, 1, 2, 3, 4, 5, 6, 7]] - 子域名数组。
  * @param {string} [options.attribution='Map Data <a href='https://www.tianditu.gov.cn' target='_blank'><img style='background-color:transparent;bottom:2px;opacity:1;' src='https://api.tianditu.gov.cn/img/map/logo.png' width='53px' height='22px' opacity='0'></a>'] - 版权描述信息。
  * @param {string} [options.noWrap=true] - 图层是否 X 方向平铺。
+ * @param {number} [options.bufferTiles=0] - 视野外预加载的瓦片圈数。默认 0 表示不预加载；为 1 时上下左右各多加载一圈，可减少平移时的空白块。支持小数。
  * @param {boolean} [options.tileCache=false] - 是否启用客户端瓦片内存缓存。开启后，缩放时优先使用已缓存瓦片填充（放大后再缩小可避免空白块），再按需请求新瓦片。
  * @param {number} [options.tileCacheZoomRange=5] - 动态缓存相对当前视野的缩放范围倍数。缓存上限为视野瓦片数 × tileCacheZoomRange。
  * @param {number} [options.maxOverzooming=8] - 缩放时保留父级（更低级别）瓦片的深度，用于放大过程中的占位填充。

src/leaflet/mapping/TileLayer.WMTS.js

@@ -26,6 +26,7 @@ import { Util as CommonUtil } from '@supermapgis/iclient-common/commontypes/Util
  * @param {string} [options.version='1.0.0'] - 版本。
  * @param {string} [options.attribution] - 版权描述信息。
  * @param {string} [options.noWrap=true] - 图层是否 X 方向平铺。
+ * @param {number} [options.bufferTiles=0] - 视野外预加载的瓦片圈数。默认 0 表示不预加载；为 1 时上下左右各多加载一圈，可减少平移时的空白块。支持小数。
  * @param {boolean} [options.tileCache=false] - 是否启用客户端瓦片内存缓存。开启后，缩放时优先使用已缓存瓦片填充（放大后再缩小可避免空白块），再按需请求新瓦片。
  * @param {number} [options.tileCacheZoomRange=5] - 动态缓存相对当前视野的缩放范围倍数。缓存上限为视野瓦片数 × tileCacheZoomRange。
  * @param {number} [options.maxOverzooming=8] - 缩放时保留父级（更低级别）瓦片的深度，用于放大过程中的占位填充。

src/leaflet/mapping/TiledMapLayer.js

@@ -40,6 +40,7 @@ import Attributions from '../core/Attributions';
  * @param {Array.<number>|Array.<string>} [options.subdomains] - 子域名数组。
  * @param {ChartSettingS57|ChartSettingS100} [options.chartSetting] - 海图显示参数设置类，用于管理海图显示环境，包括海图的显示模式、显示类型名称、颜色模式、安全水深线等各种显示风格。
  * @param {number} [options.overflowTiles = 0] - 绘制超出图层范围的瓦片圈数。常用于位于地图边缘的要素符号显示不全的场景。默认值为0，表示不绘制超出图层范围的瓦片。当 options.noWrap 为 true 时，overflowTiles有效。
+ * @param {number} [options.bufferTiles=0] - 视野外预加载的瓦片圈数。默认 0 表示不预加载；为 1 时上下左右各多加载一圈，可减少平移时的空白块。支持小数。
  * @param {boolean} [options.tileCache=false] - 是否启用客户端瓦片内存缓存。与 cacheEnabled（服务端缓存）不同；开启后缩放时优先使用已缓存瓦片填充（放大后再缩小可避免空白块），再按需请求新瓦片。
  * @param {number} [options.tileCacheZoomRange=5] - 动态缓存相对当前视野的缩放范围倍数。缓存上限为视野瓦片数 × tileCacheZoomRange。
  * @param {number} [options.maxOverzooming=8] - 缩放时保留父级（更低级别）瓦片的深度，用于放大过程中的占位填充。

test/leaflet/core/TileLayerBufferSpec.js

@@ -0,0 +1,97 @@
+import '../../../src/leaflet/core/Base';
+import { tiledMapLayer } from '../../../src/leaflet/mapping/TiledMapLayer';
+import { baiduTileLayer } from '../../../src/leaflet/mapping/BaiduTileLayer';
+import { wmtsLayer } from '../../../src/leaflet/mapping/TileLayer.WMTS';
+import L from 'leaflet';
+
+var PIXEL =
+    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
+
+describe('TileLayerBuffer', () => {
+    var testDiv, map;
+
+    beforeAll(() => {
+        testDiv = document.createElement('div');
+        testDiv.style.width = '256px';
+        testDiv.style.height = '256px';
+        document.body.appendChild(testDiv);
+        map = L.map(testDiv, {
+            fadeAnimation: false,
+            zoomAnimation: false,
+            markerZoomAnimation: false,
+            center: [0, 0],
+            zoom: 2,
+            maxZoom: 18
+        });
+    });
+
+    afterEach(() => {
+        map.eachLayer(function (layer) {
+            map.removeLayer(layer);
+        });
+        map.setView([0, 0], 2, { animate: false });
+    });
+
+    afterAll(() => {
+        map.remove();
+        document.body.removeChild(testDiv);
+    });
+
+    function pixelBoundsSize(layer) {
+        var bounds = layer._getTiledPixelBounds(map.getCenter());
+        return L.point(bounds.max.x - bounds.min.x, bounds.max.y - bounds.min.y);
+    }
+
+    function tileRange(layer) {
+        return layer._pxBoundsToTileRange(layer._getTiledPixelBounds(map.getCenter()));
+    }
+
+    it('L.TileLayer 默认关闭视野外预加载', () => {
+        var layer = L.tileLayer(PIXEL);
+        expect(layer.options.bufferTiles).toBe(0);
+    });
+
+    it('mapping 下 TileLayer 子类继承 bufferTiles 默认值', () => {
+        var tiled = tiledMapLayer('http://localhost/map');
+        var baidu = baiduTileLayer();
+        var wmts = wmtsLayer('http://localhost/wmts', { layer: 'test', tilematrixSet: 'c' });
+        expect(tiled.options.bufferTiles).toBe(0);
+        expect(baidu.options.bufferTiles).toBe(0);
+        expect(wmts.options.bufferTiles).toBe(0);
+    });
+
+    it('bufferTiles 为 0 时不扩展像素范围', () => {
+        var layer = L.tileLayer(PIXEL, { bufferTiles: 0 }).addTo(map);
+        var size = map.getSize();
+        var boundsSize = pixelBoundsSize(layer);
+        expect(Math.abs(boundsSize.x - size.x)).toBeLessThan(1);
+        expect(Math.abs(boundsSize.y - size.y)).toBeLessThan(1);
+    });
+
+    it('bufferTiles 为 1 时四边各扩展一圈瓦片', () => {
+        var layer0 = L.tileLayer(PIXEL, { bufferTiles: 0 }).addTo(map);
+        var layer1 = L.tileLayer(PIXEL, { bufferTiles: 1 }).addTo(map);
+        var tileSize = layer1.getTileSize();
+        var size0 = pixelBoundsSize(layer0);
+        var size1 = pixelBoundsSize(layer1);
+        expect(size1.x).toBe(size0.x + tileSize.x * 2);
+        expect(size1.y).toBe(size0.y + tileSize.y * 2);
+
+        var range0 = tileRange(layer0);
+        var range1 = tileRange(layer1);
+        expect(range1.min.x).toBe(range0.min.x - 1);
+        expect(range1.max.x).toBe(range0.max.x + 1);
+        expect(range1.min.y).toBe(range0.min.y - 1);
+        expect(range1.max.y).toBe(range0.max.y + 1);
+    });
+
+    it('bufferTiles 支持小数圈数', () => {
+        var layer0 = L.tileLayer(PIXEL, { bufferTiles: 0 }).addTo(map);
+        var layerHalf = L.tileLayer(PIXEL, { bufferTiles: 0.5 }).addTo(map);
+        var tileSize = layerHalf.getTileSize();
+        var size0 = pixelBoundsSize(layer0);
+        var sizeHalf = pixelBoundsSize(layerHalf);
+        expect(sizeHalf.x).toBe(size0.x + tileSize.x);
+        expect(sizeHalf.y).toBe(size0.y + tileSize.y);
+    });
+});