首页 / MapLibre / API 文档

VectorSource

先看结论

矢量瓦片源，坐标与属性在客户端渲染，缩放时不会变糊，样式改动不需要重新切片。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-28 · 引用本文

map.addSource(id, { type: 'vector', tiles: [...], maxzoom: 6 })

参数

字段	默认	说明
`url`	—	TileJSON 地址，与 `tiles` 二选一
`tiles`	—	PBF 瓦片模板数组
`minzoom`	0	起始级别
`maxzoom`	22	数据实际切片的最大级别
`scheme`	`'xyz'`	或 `'tms'`
`bounds`	null	数据覆盖范围，越界不请求
`promoteId`	—	把某个属性提升为要素 id，供 `feature-state` 使用
`attribution`	—	来源声明
`volatile`	false	不保留瓦片缓存

成员

成员	说明
`setTiles(tiles)`	替换瓦片模板
`setUrl(url)`	改用 TileJSON 地址
`setSourceProperty(callback)`	直接改写内部属性，自行保证合法
`loaded()`	当前视野是否加载完成
`hasTile(tileID)`	瓦片是否已在缓存
`data` 事件	瓦片解析完成或状态变化
`error` 事件	PBF 解析失败或请求被拒

示例

map.addSource('world', {
  type: 'vector',
  tiles: ['https://demotiles.maplibre.org/tiles/{z}/{x}/{y}.pbf'],
  minzoom: 0,
  maxzoom: 6,
  attribution: 'MapLibre demo tiles'
});

map.addLayer({
  id: 'world-fill',
  type: 'fill',
  source: 'world',
  'source-layer': 'countries',
  paint: {
    'fill-color': '#dbe7f3',
    'fill-outline-color': '#8aa4bf'
  }
});

map.addLayer({
  id: 'world-name',
  type: 'symbol',
  source: 'world',
  'source-layer': 'centroids',
  layout: {
    'text-field': ['get', 'NAME'],
    'text-size': 11
  }
});

注意事项

矢量源本身不带几何样式，只有 source 不够，图层还必须写 source-layer，值来自瓦片内的图层名，不是源 id。名字对不上时图层安静地什么都不画，不报错。

maxzoom 要填数据真实切到的级别。底图只切到 6 级时写 22，放大到 14 级仍会请求 14 级的瓦片，服务端返回 404，而地图只会把 6 级的瓦片放大显示。

要素 id 与状态。想用 setFeatureState 做悬停高亮，瓦片里的要素必须自带 id，或者用 promoteId 指定属性。两者都没有时，状态写不进去也不报错。

引用本文

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