首页 / MapLibre / API 文档

setStyle

先看结论

整体替换地图样式：换底图、换配色、换数据源集合，运行期切主题都靠它。

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

map.setStyle(style, options?) → this

style 可以是样式 JSON 对象，也可以是样式文件的 URL。

参数

参数	默认	说明
`style`	—	样式对象或 URL
`options.diff`	`true`	为真时只应用新旧样式的差异，为假时整体重载
`options.localIdeographFontFamily`	本地字体族	用系统字体渲染中日韩文字，省掉字形请求
`options.transformStyle`	—	回调，接收 `(previous, next)` 两个样式对象，返回修改后的样式

切换底图

var themes = {
  light: '/styles/light.json',
  dark: '/styles/dark.json'
};

function switchTheme(name) {
  map.setStyle(themes[name]);
}

样式加载完成前地图会保留上一帧的内容，不会闪白。新样式就绪时触发 style.load，这是重新添加自定义图层的唯一可靠时机。

样式切换后补回自定义图层

var customLayers = [
  { id: 'district-fill', type: 'fill', source: 'districts',
    paint: { 'fill-color': '#1f5fd0', 'fill-opacity': 0.25 } },
  { id: 'district-line', type: 'line', source: 'districts',
    paint: { 'line-color': '#1f5fd0', 'line-width': 1 } }
];

map.on('style.load', function () {
  if (!map.getSource('districts')) {
    map.addSource('districts', { type: 'geojson', data: districtData });
  }

  customLayers.forEach(function (layer) {
    if (!map.getLayer(layer.id)) {
      map.addLayer(layer);
    }
  });
});

新样式里没有这些源和图层，不加回来就会「样式换了、业务数据消失」。用 getLayer 判重可以避免重复添加抛错。

用 transformStyle 统一改样式

map.setStyle('/styles/vendor.json', {
  transformStyle: function (previous, next) {
    next.layers.forEach(function (layer) {
      if (layer.type === 'fill' && layer['source-layer'] === 'water') {
        layer.paint['fill-color'] = '#0b3d5c';
      }
    });
    return next;
  }
});

回调在样式解析后、应用前执行，适合替换第三方样式的配色与字体，不必维护一份完整副本。

相关事件

事件	触发时机
`style.load`	新样式解析完成，源与图层已建立
`styledata`	样式数据每次变化，触发频繁
`error`	样式 URL 404、JSON 非法或图层校验失败
`idle`	当前视野渲染完毕且无待处理任务

diff: true 只比较图层，不比较源。 数据源仍会重建，缓存的 getSource 结果可能失效；要素状态（feature-state）也会丢失。切换主题后需要重新设置高亮状态。

引用本文

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