首页 / MapLibre / API 文档

addSprite

先看结论

给样式追加一套 sprite 图标表。v4 支持多套共存，用 id 前缀区分来源。

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

map.addSprite(id, url, options?) → this

添加后触发 style 事件，图标的引用方式随之扩展。

参数

参数	类型	说明
`id`	string	sprite 的名称，不能与已有 sprite 冲突
`url`	string	图标表地址，同时加载 `.json` 与 `.png`
`options.validate`	boolean	是否校验样式资源，默认开启

多套图标前缀

sprite 的 id 会作为图标名前缀。给 roadsigns 加一套图标后，其中的 parking 要写成 roadsigns:parking。不带前缀的名字仍然指向样式里原有的默认 sprite。

map.addSprite('roadsigns', 'https://cdn.example.com/sprites/roadsigns');

map.addLayer({
  id: 'signs',
  type: 'symbol',
  source: 'signs',
  layout: {
    'icon-image': ['concat', 'roadsigns:', ['get', 'icon']],
    'icon-size': 0.8
  }
});

样式里的等价写法

sprite 字段既接受单个 URL 字符串，也接受 { id, url } 数组。初始化时就确定图标表的情况，直接写在样式中更简单：

var style = {
  version: 8,
  sprite: [
    { id: 'base', url: 'https://cdn.example.com/sprites/base' },
    { id: 'roadsigns', url: 'https://cdn.example.com/sprites/roadsigns' }
  ],
  sources: {},
  layers: []
};

map.setStyle(style);

运行期才决定的图标表用 addSprite，例如按区域加载不同的行业图标。

地址约定

文件	作用
`{url}.json`	图标索引，记录每个图标的位置、尺寸与像素比
`{url}.png`	图标合并图，所有图标排在一张位图上
`{url}@2x.json` / `@2x.png`	高分屏版本，由 MapLibre 按像素比自动选择

URL 里不要带 .json 或 .png 后缀，否则会拼出错误的地址。

图标缺失的表现

icon-image 指向不存在的名字时，该符号不会绘制，也不会报错。排查时先用 map.hasImage('roadsigns:parking') 确认图标已加载，再检查前缀是否写错。

跨域 sprite 需要正确的 CORS 头。 JSON 与 PNG 都要允许跨域读取，否则图标表加载失败、style 事件照样触发。本地调试时打开网络面板看资源状态，比等图标不显示再猜要快。

引用本文

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