SuperAPI AI 工具集

maplibre-sprites-icons

前端与建站

查看项目

更新于 10-16 22:21

技能介绍

用途

本技能面向在 MapLibre GL JS 地图上处理图标的场景,帮助判断图标应当以何种方式绘制,并解决图标不渲染、路线盾牌显示残缺等问题。

主要能力

三种图标方式的取舍

判断顺序分两步:图标是地图的一部分还是悬浮其上;若是符号图层,图像来自样式还是运行时。

  • 作为地图一部分:由符号图层的 icon-image 绘制,与标注一同排布、发生碰撞时隐藏、按图层顺序绘制,适合任意规模的图层点数据集。
  • 悬浮在地图上:Marker 是地图画布之上的 HTML 元素,位于样式之外,绘制在所有图层(含标注)之上,不参与碰撞检测,适合少量可拖拽或需要自定义 HTML 的注记。
  • 运行时注册:应用自身在运行时添加的图层(如 GeoJSON 源),图像不在任何图集中时使用 addImage。每张图像是独立请求与独立调用,而 sprite 以一张 PNG 加一个 JSON 到达。

Sprite(精灵图)

样式的 sprite 值是不含文件扩展名的基址 URL,MapLibre 自行追加 .json、.png 及 @2x 变体。符号图层在 icon-image 中命名 sprite 图像(其他图层用其 *-pattern 属性),名称必须与 sprite JSON 索引中的 ID 完全一致,否则图标不绘制。

多个 sprite 图集:自 MapLibre GL JS 3.0(#1805)起,sprite 也接受 {id, url} 对象数组,样式的自有图标可与底图提供方的图集并存。规则包括:通过 id:image-name 引用图像,如 "icon-image": "my-icons:cafe";不带前缀的名称只在 default 图集中解析;default 这一 id 是例外,其图像不带前缀,这使既有样式的 icon-image 值在由字符串改为数组形式后仍可解析;所有 id 与所有 URL 必须唯一,重复是校验错误而非后者覆盖;每个 URL 仍不含扩展名。代码侧可用 map.addSprite('my-icons', 'https://example.com/sprites/poi') 在样式加载后添加图集。

自托管 sprite:可从样式或瓦片提供方复制 sprite 目录(PNG 加 JSON 及 @2x 文件)托管到自有域名,将样式 sprite 指向其基址 URL,但重新发布前须检查提供方许可并按需署名。应将 sprite 资源托管在自有静态主机上,不要在生产样式指向 raw.githubusercontent.com。

从 SVG 构建 sprite:可用 spritezero、spreet 或 Martin 等工具从 SVG 目录生成;常用图标来源包括 Maki 与 Temaki,重新发布派生资源前须检查各仓库许可。

运行时图像 addImage

应用在运行时添加的图层,需在样式加载后为每张图像注册 ID,再在图层的 icon-image 中引用。先用 hasImage() 检查 ID,对已存在的 ID 调用 addImage 会报错而非替换。

PNG/WebP/JPEG 可经 map.loadImage() 加载(返回 Promise);SVG 需通过 Image 元素光栅化,并设置 crossOrigin,否则 addImage 会抛出跨域错误。注意 map.loadImage(url, callback) 的回调形式在 GL JS 4.0.0 已移除;map.loadImage() 不接受 SVG;对普通 SVG 设置 sdf: true 会把多色图标变成单色剪影,且不设 sdf 时 icon-color 与 icon-halo-* 不生效。

符号图层默认隐藏碰撞图标,由 symbol-sort-key 决定保留哪一个;打开 icon-allow-overlap(或 icon-overlap: "always")会绘制全部图标并堆叠。addImage 的选项接受与 sprite 索引相同的逐图像元数据:pixelRatio、sdf、stretchX、stretchY、content、textFitWidth、textFitHeight。

Marker

Marker 是地图画布之上的 HTML 元素,绘制于所有图层之上,不参与碰撞检测。每次相机移动都会重新定位该 DOM 元素,适合少量注记;点数据集应放入 GeoJSON 源并以符号图层绘制。

图标不渲染的排查

GL JS 会报告每张找不到的图像:地图触发 styleimagemissing,控制台对每个图像 ID 警告一次。load 事件之后用 map.hasImage(id) 区分两类原因:sprite JSON 中确有该 ID 而 hasImage() 为 false,说明图集未加载,需检查样式是否设置 sprite、URL 是否无扩展名、其 .json 与 .png 是否返回 200 以及 CORS;其他 sprite ID 返回 true 而该 ID 为 false,说明图集已加载但无此 ID,需比对 icon-image 值与 sprite JSON 的键(含非默认图集的 id: 前缀),map.listImages() 返回地图拥有的全部 ID。

路线盾牌损坏

盾牌数字是文本(字体),通常能正常渲染;其后的徽章是来自 sprite 的 icon-image。诊断顺序:先确认字形加载(向字形服务器探测确切的 text-font 名称并期望 HTTP 200);再确认 sprite 带有盾牌图像(OSM Bright 的美国网络图层使用 icon-image: "{network}{ref_length}",如 us-interstate_2、us-highway_3、us-state_2,其他 ref 用 road{ref_length};OSM Liberty 使用 default_{ref_length}),缺失的图标会被省略,可 grep sprite JSON 中的这些键。

盾牌是路线编号之后的徽章图像,尺寸有两种方式:OSM Bright 与 OSM Liberty 按 ref 长度选取预先绘制的徽章,使用 OpenMapTiles 的 ref_length 属性选择正确的徽章;也可用一张可拉伸徽章适配所有长度,在徽章 sprite JSON 条目中 stretchX/stretchY 列出可拉伸的像素范围,content 是文本必须容纳的范围,盾牌图层设置 icon-text-fit 为 "both" 或 "width" 并配 icon-text-fit-padding。

读取样式的 layout 值时不能假定其为字符串:任何符号 layout 值都可能是表达式(数组),OSM Bright 的三个盾牌图层与 OSM Liberty 的一个图层还用带 stops 的旧式缩放函数设置 symbol-placement,因此形如 layer.layout['symbol-placement'] === 'point' 的判断对这些图层会为 false,比较前须先判断值是字符串、缩放函数还是表达式。

适用场景

  • 在 Marker、sprite 与 addImage 之间为地图图标做选择
  • 符号图层的图标不渲染
  • 在无法控制其 sprite 的样式上添加自有图标图集
  • 设置、自托管或从 SVG 构建 sprite
  • 为应用运行时添加的图层注册图像(含 SVG)
  • 路线盾牌显示为裸露数字或缺失徽章
  • 编写读取或生成符号图层、需要识别盾牌的工具

限制

  • RAW.githubusercontent.com 不适合作为生产资源:匿名请求会被限流,实际用户会看到间歇性 HTTP 429;缓存固定为五分钟且无法控制;无 SLA;私有仓库 URL 对非协作者返回 404。
  • https://demotiles.maplibre.org/styles/osm-bright-gl-style/sprite 可用于测试,但不要用于生产。
  • 本技能为快照,当一手来源(文中所列参考、MapLibre 当前文档或实际运行行为)与其矛盾时以一手来源为准,并报告分歧及所用 MapLibre 版本。