从XYZ的tileUrlFunction迁移至TileImage的tileLoadFunction遇加载异常

OpenLayers最新文档标注XYZ源的tileUrlFunction已废弃，尝试迁移到TileImage并使用tileLoadFunction替代后，地图完全没有内容显示，且控制台中tileLoadFunction从未被调用。

旧版本可正常运行的代码 #

Number.prototype.mod = function (n) {
    return ((this%n)+n)%n;
};

var mylayer = new TileLayer({
    source: new XYZ({
        tileUrlFunction: function (tileCoord, pixelRatio, projection) {
            console.log("tileUrlFunction invoked");
            if (tileCoord === null) {
                return undefined;
            }

            var z = tileCoord[0];
            var x = tileCoord[1];
            var y = tileCoord[2];
            var zfactor = Math.pow(2, z);
            const url = "https://tile.openstreetmap.org/" + z + "/" + x.mod(zfactor) + "/" + y.mod(zfactor) + ".png";
            return url;
        },
        tileSize: 256,
        minZoom: 0,
        maxZoom: 19,
        attributions: '© OpenStreetMap contributors'
    })
});

新版本无法运行的代码（tileLoadFunction未触发） #

Number.prototype.mod = function (n) {
    return ((this%n)+n)%n;
};

var mylayer = new TileLayer({
    source: new TileImage({
        tileGrid: createXYZ({
            tileSize: 256,
            minZoom: 0,
            maxZoom: 19,
        }),
        tileLoadFunction: function (imageTile, src) {
            console.log("tileLoadFunction invoked");
            const tileCoord = imageTile.getTileCoord();
            if (!tileCoord) {
                console.log("Tile coordinate is null");
                imageTile.getImage().src = '';
                return;
            }

            const z = tileCoord[0];
            const x = tileCoord[1];
            const y = tileCoord[2];
            const zfactor = Math.pow(2, z);
            const url = "https://tile.openstreetmap.org/" + z + "/" + x.mod(zfactor) + "/" + y.mod(zfactor) + ".png";

            console.log("Loading URL for coordinates - " + z + "," + x + "," + y + " --> " + url);
            imageTile.getImage().src = url;
        },
        attributions: '© OpenStreetMap contributors'
    }),
});

问题原因与解决方案 #

问题核心：tileLoadFunction仅负责处理tile的加载行为，但TileImage需要通过tileUrlFunction或url属性获取tile的URL，才会触发加载请求。新版本代码未配置URL生成逻辑，导致tileLoadFunction从未被调用。

方案1：使用XYZ源的新API（推荐） #

XYZ源的tileUrlFunction废弃后，官方推荐直接将URL生成函数赋值给url属性，无需切换到TileImage：

Number.prototype.mod = function (n) {
    return ((this%n)+n)%n;
};

var mylayer = new TileLayer({
    source: new XYZ({
        url: function (tileCoord) {
            if (!tileCoord) return undefined;
            const z = tileCoord[0];
            const x = tileCoord[1];
            const y = tileCoord[2];
            const zfactor = Math.pow(2, z);
            return `https://tile.openstreetmap.org/${z}/${x.mod(zfactor)}/${y.mod(zfactor)}.png`;
        },
        tileSize: 256,
        minZoom: 0,
        maxZoom: 19,
        attributions: '© OpenStreetMap contributors'
    })
});

方案2：正确配置TileImage #

若坚持使用TileImage，需同时设置tileUrlFunction生成URL，tileLoadFunction可按需保留自定义加载逻辑：

Number.prototype.mod = function (n) {
    return ((this%n)+n)%n;
};

var mylayer = new TileLayer({
    source: new TileImage({
        tileGrid: createXYZ({
            tileSize: 256,
            minZoom: 0,
            maxZoom: 19,
        }),
        tileUrlFunction: function (tileCoord) {
            if (!tileCoord) return undefined;
            const z = tileCoord[0];
            const x = tileCoord[1];
            const y = tileCoord[2];
            const zfactor = Math.pow(2, z);
            return `https://tile.openstreetmap.org/${z}/${x.mod(zfactor)}/${y.mod(zfactor)}.png`;
        },
        tileLoadFunction: function (imageTile, src) {
            console.log("Loading tile: ", src);
            imageTile.getImage().src = src;
        },
        attributions: '© OpenStreetMap contributors'
    })
});

内容的提问来源于stack exchange，提问作者Jose Gómez