MapLibre：为何map.on('load',()=>{})回调有时无法触发？

原因分析 #

• 数据源加载超时或静默失败：当数据源体积过大、网络环境较差时，部分资源可能加载超时，或加载失败但未抛出明确错误，导致地图内部的加载完成判断逻辑无法识别“所有资源加载完毕”，进而不触发on-load回调。
• 图层与数据源加载时序不匹配：如果先初始化图层再加载对应数据源，地图的on-load触发判断可能在数据源开始加载前就已执行，后续大资源加载完成后不会再次触发事件。
• 内部加载状态判断的边界漏洞：MapLibre GL JS的on-load事件默认监听预定义的图层、数据源加载状态，但如果加载过程中出现非预期的资源加载中断（比如部分瓦片加载失败），可能导致状态判断逻辑卡住，无法触发回调。
• 动态资源加载的事件遗漏：如果在地图初始化完成后再动态添加大数据量的数据源/图层，此时on-load事件已经触发过，后续资源加载完成不会再次触发该事件，容易被误认为是事件未触发。

解决建议 #

• 用data事件补充或替代load事件：data事件会在地图加载任何资源时触发，可以结合map.loaded()方法判断是否所有资源加载完成，示例代码：

map.on('data', () => {
  if (map.loaded()) {
    // 执行原本on-load中的业务逻辑
    map.off('data', arguments.callee); // 移除监听避免重复执行
  }
});

• 定时检查加载状态：通过定时器周期性检查map.loaded()，确认加载完成后执行回调并清除定时器，示例：

const loadChecker = setInterval(() => {
  if (map.loaded()) {
    clearInterval(loadChecker);
    // 执行你的回调逻辑
  }
}, 500);

• 优化数据源加载方式：对大数据量的GeoJSON等数据源进行切片处理，改用矢量瓦片格式加载，或分批次加载数据，降低单次加载的资源压力，减少加载异常概率。
• 严格控制图层与数据源加载顺序：确保先完成数据源加载再添加对应图层，可以监听数据源的加载状态事件，示例：

map.addSource('big-data-source', { type: 'geojson', data: '/path/to/large-data.geojson' });
map.on('data', (event) => {
  if (event.sourceId === 'big-data-source' && event.isSourceLoaded) {
    map.addLayer({
      // 图层配置参数
      id: 'big-data-layer',
      source: 'big-data-source',
      type: 'fill'
    });
  }
});

• 监听加载异常排查问题：通过error事件捕获地图加载过程中的异常，及时定位是否存在资源加载失败的情况，示例：

map.on('error', (err) => {
  console.error('地图加载异常:', err);
  // 根据异常类型执行兜底逻辑
});

内容的提问来源于stack exchange，提问作者lei qin