首页 / MapLibre / API 文档

MapDataEvent

先看结论

样式与数据加载过程中的统一事件对象，用来判断「底图到底加载完了没有」。

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

map.on('sourcedata', function (e) { if (e.isSourceLoaded) { … } })

事件类型

事件名	`dataType`	说明
`data`	`'source'` 或 `'style'`	样式或数据发生变化的总入口
`sourcedata`	`'source'`	单个数据源的瓦片、元数据或可见性变化
`styledata`	`'style'`	样式对象被修改或重新解析
`style.load`	—	样式加载完成，可安全添加图层
`idle`	—	没有待处理的渲染与请求，画面稳定

字段

字段	类型	说明
`type`	string	`'data'`、`'sourcedata'` 或 `'styledata'`
`dataType`	string	`'source'` 或 `'style'`
`isSourceLoaded`	boolean	该源已无未完成的网络请求
`sourceId`	string	发生变化的源 id
`source`	SourceSpecification	该源的样式规范片段
`sourceDataType`	string	`metadata`、`content`、`visibility`、`idle`
`tile`	object	与瓦片加载相关时携带该瓦片的信息

示例

var pending = {};

map.on('sourcedata', function (e) {
  if (e.dataType !== 'source') return;

  var id = e.sourceId;
  if (e.sourceDataType === 'metadata') {
    pending[id] = true;
  }

  if (e.isSourceLoaded) {
    delete pending[id];
    document.getElementById('loading').textContent =
      Object.keys(pending).length === 0 ? '底图就绪' : '仍在加载 ' + Object.keys(pending).join('、');
  }
});

map.on('styledata', function () {
  /* 样式变化时图层可能被重置，重新同步图例 */
  refreshLegend();
});

map.on('idle', function () {
  document.getElementById('loading').hidden = true;
});

注意事项

data 事件非常频繁，拖一次地图可能触发几十次。在其中做 DOM 查询或大范围重排会直接拖低帧率，只做轻量的状态记录。

isSourceLoaded 只代表该源当前视野内的请求完成，用户继续拖动时它又会变回 false。判断「首屏可交互」更适合用 idle 或首次 isSourceLoaded 为 true 时设一个标记，之后不再改。

别用 styledata 添加图层。样式重设过程中图层会被清空，此时 addLayer 可能报错。添加图层的时机是 load 或 style.load。

引用本文

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