首页 / MapLibre / API 文档

Style

先看结论

一份描述底图与图层的数据，可以是 JSON 对象，也可以是指向 JSON 的 URL。

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

new maplibregl.Map({ style: styleObjectOrUrl, … })

结构

字段	必需	说明
`version`	是	固定 8
`sources`	是	数据源，键名就是图层里引用的 source
`layers`	是	绘制顺序，后面的盖住前面的
`glyphs`	文本图层需要	字体切片模板，含 `{fontstack}` 与 `{range}`
`sprite`	图标图层需要	雪碧图 URL 前缀，对应 png 与 json
`center` / `zoom` / `bearing` / `pitch`	否	样式自带的初始视角

{
  "version": 8,
  "sources": {
    "osm": {
      "type": "raster",
      "tiles": ["https://tile.example.com/{z}/{x}/{y}.png"],
      "tileSize": 256,
      "attribution": "© 示例瓦片"
    }
  },
  "layers": [
    { "id": "osm", "type": "raster", "source": "osm" }
  ]
}

源类型

type	用途	关键字段
`vector`	矢量瓦片	`url` 或 `tiles` + `minzoom`
`raster`	栅格瓦片底图	`tiles`、`tileSize`、`attribution`
`geojson`	业务数据	`data`、`cluster`
`raster-dem`	高程瓦片，用于地形	`encoding`（terrarium / mapbox）
`image`	单张图片贴在地图上	`url`、`coordinates` 四角

操作样式的方法

方法	说明
`map.getStyle()`	返回当前样式对象，可用来查图层 id
`map.setStyle(style, {diff})`	替换样式，diff 默认为 true
`map.getSource(id)`	取回源对象
`map.setPaintProperty(layer, prop, value)`	改绘制属性
`map.setLayoutProperty(layer, prop, value)`	改布局属性
`map.moveLayer(id, beforeId)`	调整顺序

属性值可以是表达式

颜色、宽度、半径等属性既可以写常量，也可以写表达式数组，按缩放级别、属性值、要素状态动态计算。

map.setPaintProperty('route-line', 'line-width', [
  'interpolate', ['linear'], ['zoom'],
  3, 1.2,
  8, 4
]);

map.setPaintProperty('zones-fill', 'fill-color', [
  'match', ['get', 'level'],
  'high', '#c2410c',
  'low', '#1f5fd0',
  '#8a929f'
]);

整体切换

setStyle 之后，旧样式里的源和图层都不再存在。自定义图层要在 style.load 里重新添加。同一份样式之间切换时开启 diff，可复用未变化的资源，减少闪烁。

map.setStyle(nextStyleUrl, { diff: true });

map.on('style.load', function () {
  addBusinessLayers();
});

样式地址要能跨域访问。样式 JSON 自身、瓦片、字形、雪碧图是四类独立请求，任何一类被跨域拦截都会让地图残缺。逐类检查，比笼统说「地图没出来」快得多。

引用本文

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