浏览器自定义协议

独立浏览器 SDK 提供 addProtocol(name, handler) / removeProtocol(name)，调用形式参考 MapLibre addProtocol。SqsMap 使用自己的地图引擎与实现；以下是当前已实现的协议回调子范围，不能据此推断完整 MapLibre 插件兼容性。

最小用法

import { MapView, ResourceType, addProtocol, removeProtocol } from '@sqsmap/core';

const bytes = new Uint8Array(/* 自己提供的有效 PNG 编码字节 */);
addProtocol('memory', async (params, controller) => {
  controller.signal.throwIfAborted();
  if (params.url !== 'memory://images/icon.png') throw new Error('Unknown image');
  return { data: bytes };
});
const map = await MapView.create(document.querySelector('#map'), {
  worker: false,
  transformRequest: (url, type) =>
    url === 'https://assets.example/icon.png' && type === ResourceType.Image
      ? { url: 'memory://images/icon.png' } : undefined,
});
const image = await map.loadImage('https://assets.example/icon.png');
map.addImage('icon', image.data);
await map.flush();
// 有相应 symbol 图层才能显示该图标。
// 页面卸载时：map.destroy(); removeProtocol('memory');

完整 HTML/CSS/JavaScript 示例包含有效内置 PNG、真实图片解码、注册/移除/重复加载/销毁按钮及全部事件处理，可直接下载或复制；无在线底图或测试密钥。浏览器须能初始化 WebGPU/WebGL2。

13.6b已扩展共同资源规划及vector/raster/raster-dem瓦片模板，支持合法自定义协议真实地址；Style URL、TileJSON url、GeoJSON与媒体入口仍保持HTTP(S)。以下transformRequest方式继续兼容，直接瓦片地址见共同协议规划。相对资源地址仍相对原始 HTTP(S) 地址解析。浏览器宿主注册表按 JavaScript realm 隔离，最多16个协议，名称为1～32字符小写字母开头，可包含数字、加号、点和连字符；HTTP、WebSocket、本地与执行类保留协议不能覆盖。

此回调属于浏览器宿主代码，不是共同地图脚本的新方法；桌面、原生 C/QuickJS 与移动应用不接收 JavaScript 回调注册。三端共同配置仍使用资源策略中的可序列化接口。

主线程设置 transformRequest 后默认选择主线程渲染；显式严格 createWorker 与函数请求选项一起使用会返回 CAPABILITY_UNAVAILABLE。主线程注册不会自动传给 Worker。不要把本例称为 Worker 转发支持。

返回值、取消与错误

处理器参数为捕获的请求，包含规范化地址、期望解码类型、请求头和取消信号；第二参数是本请求的 AbortController。只接受 Promise<{ data }>，data 为 ArrayBuffer、Uint8Array 的精确视图或字符串。字符串以 UTF-8 字节计预算，返回值捕获独立副本。JSON对象、DOM图片、ImageBitmap、流及 cacheControl/expires 等额外响应字段会被拒绝。

协议回调共用地图的并发、总期限、单次期限和字节预算。替换资源、移除图层、外部取消或销毁地图会通知处理器的信号并拒绝等待。使用网络时把该信号传给 fetch；忽略信号的用户代码可能继续运行，但迟到结果不会写入地图。回调自行分配内存由使用方负责。

注册同名协议替换后续尝试的处理器；移除不存在的有效名称是幂等操作。已开始请求保留自己的处理器和控制器，不因移除注册被取消；销毁地图仍会取消它。处理器失败或超时不会自动重复执行用户代码，也不会转发到 HTTP 备用地址。自动接口令牌不会注入自定义协议；回调里的授权、缓存、HTTP错误/CORS与重试由使用方控制。

验证范围

真实 Rust/WASM 规划配合浏览器传输验证注册额度、UTF-8预算、切片、捕获、取消、超时和迟到结果；实际软件 GL 地图验证 PNG 解码、重复加载、移除/恢复与销毁。保留既有 HTTP 传输回归。这些是本机证据，不能代替公网服务、硬件、移动设备或正式 SDK 发布验收。

浏览器自定义协议

最小用法

地址与平台边界

返回值、取消与错误

验证范围