Maplibre GL JS 中自定义协议加载 Sprite JSON 的解析问题解析

问题背景

在使用 Maplibre GL JS 进行地图开发时，开发者可能会遇到需要通过自定义协议加载 Sprite JSON 资源的情况。Sprite 是地图中用于显示图标的重要资源，包含图标的位置信息和对应的图片数据。

核心问题

当开发者使用 addProtocol 方法注册自定义协议（如 'internal'）来加载 Sprite JSON 时，可能会发现图标无法正常显示。这是因为 Maplibre GL JS 内部对通过自定义协议获取的 JSON 数据处理方式存在差异。

问题分析

在标准 HTTP 请求中，Maplibre 会自动处理 JSON 响应。但当使用自定义协议时，如果返回的是 ArrayBuffer 格式的数据，Maplibre 不会自动将其解析为 JSON 对象，而是直接使用原始数据，导致后续 Sprite 处理失败。

解决方案

方案一：修改协议处理逻辑

在自定义协议的实现中，根据请求类型进行区分处理：

maplibregl.addProtocol('internal', async (params, abortController) => {
    const fixedUrl = params.url.replace('internal://', 'https://')
    const t = await fetch(fixedUrl);
    if (t.status == 200 || t.status == 0) {
      if (fixedUrl.includes(".json")) {
        const text = await t.text();
        return {
            'data': JSON.parse(text)
        }
      } else {
        const buffer = await t.arrayBuffer();
        return {
            'data': buffer
        }
      }
    } else {
        throw new Error('got status: ' + t.status + ' ' + t.statusText + ' for: ' + params.url);
    }
});

这种方法在协议处理层就完成了 JSON 解析，确保返回给 Maplibre 的是已经解析好的对象。

方案二：修改 Maplibre 源码

另一种方案是修改 Maplibre 的 Sprite 加载逻辑，使其能够处理 ArrayBuffer 格式的 JSON 数据：

const jsonResponseData = (await jsonsMap[spriteName]).data;
var json
if (jsonResponseData instanceof ArrayBuffer) {
    json = JSON.parse(new TextDecoder().decode(jsonResponseData as ArrayBuffer));
} else {
    json = jsonResponseData;
}

这种方法更具通用性，但需要修改库的源代码，可能不适合所有项目。

最佳实践建议

1. 优先使用方案一：在协议处理层进行 JSON 解析更符合职责分离原则
2. 明确资源类型：在自定义协议实现中，根据文件扩展名或请求头明确区分资源类型
3. 错误处理：确保在 JSON 解析失败时有适当的错误处理机制
4. 性能考虑：对于大型 JSON 文件，可以考虑流式解析以避免内存问题

总结

Maplibre GL JS 的自定义协议功能为开发者提供了灵活性，但在处理不同类型资源时需要特别注意数据格式的转换。通过合理实现协议处理逻辑，可以确保 Sprite 等资源能够正确加载和显示。理解这一机制有助于开发者更好地利用 Maplibre 的强大功能，构建更丰富的地图应用。