首页 / OpenLayers / API 文档

XYZSource

先看结论

XYZ 瓦片源。按 {z}/{x}/{y} 规则拼接地址逐块请求，适用于各类标准切片服务。

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

new ol.source.XYZ(options)

构造参数

参数	说明
`url`	地址模板，占位符为 `{x}`、`{y}`、`{z}`，`{-y}` 表示反转的行号
`urls`	多个地址模板，按顺序轮流取用
`projection`	瓦片投影，默认 `'EPSG:3857'`
`tileGrid`	自定义瓦片网格，用于非标准切片方案
`tileSize`	瓦片边长像素，默认 256
`minZoom` / `maxZoom`	可用层级区间
`tilePixelRatio`	瓦片像素比，默认 1，高分屏素材可设 2
`crossOrigin`	跨域取值，导出图片时需要 `'anonymous'`
`wrapX`	是否横向循环世界，默认 true
`attributions`	版权文字，会汇总到版权控件
`transition`	新瓦片淡入时长毫秒，设 0 关闭过渡
`tileLoadFunction`	自定义瓦片装载函数，签名 `(tile, src)`

常用方法

方法	返回	说明
`setUrl(url)`	void	替换单一地址模板
`setUrls(urls)`	void	替换地址模板数组
`setTileUrlFunction(fn, key)`	void	用函数接管地址生成，签名 `(tileCoord, pixelRatio, projection)`
`getTileUrlFunction()`	function	取当前地址生成函数
`refresh()`	void	清空缓存并重新请求

var source = new ol.source.XYZ({
  url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
  projection: 'EPSG:3857',
  crossOrigin: 'anonymous',
  maxZoom: 19,
  attributions: '© OpenStreetMap contributors'
});

var layer = new ol.layer.Tile({ source: source });

// 换成 TMS 方案：行号自下而上
source.setUrl('https://example.com/tms/1.0.0/base/{z}/{x}/{-y}.png');
source.refresh();

注意事项

{z}/{x}/{y} 中的 y 自北向南增长；对接 TMS 服务要写成 {-y}，否则整幅影像上下颠倒。
地址里用 {a-c} 这类区间占位可以自动轮询子域名，但每个子域名都要能响应，缺一个就会间歇性 404。
不设 crossOrigin 时 map.once('rendercomplete') 导出的画布会被污染，无法取像素。
maxZoom 小于实际切片层级时，超出部分的请求会返回空白瓦片，表现为地图局部灰块。

引用本文

经纬志（2026）。《XYZSource》。https://www.jingweizhi.com/openlayers/api/xyz-source.html（访问日期 2026-11-03）。