精灵图

加载精灵图可以通过MapLibre样式表根级别的可选sprite属性来完成；

精灵图中包含的图像可以在其他样式属性中引用（background-pattern、fill-pattern、line-pattern、fill-extrusion-pattern和icon-image）；

用法

你需要传递一个可以从中加载精灵图的URL；

"sprite": "https://demotiles.maplibre.org/styles/osm-bright-gl-style/sprite"

这将通过附加.png加载图像，并通过附加.json加载精灵图所需的元数据。你可以自己查看：

下一节将提供有关这些文件格式的确切要求的更多详细信息；

提供精灵图后，你可以在样式表的其他部分引用精灵图中的图像。例如，创建带有布局属性"icon-image": "poi"的符号图层。或者使用标记化的值"icon-image": "{icon}"和带有值为poi的icon属性的矢量瓦片要素；

多个精灵图源

你也可以提供一个{ id: '...', url: '...' }对象数组来加载多个精灵图：

"sprite": [
    {
        "id": "roadsigns",
        "url": "https://example.com/myroadsigns"
    },
    {
        "id": "shops",
        "url": "https://example2.com/someurl"
    },
    {
        "id": "default",
        "url": "https://example2.com/anotherurl"
    }
]

如你所见，每个精灵图都有一个id。精灵图中包含的所有图像也都有一个id。当使用多个精灵图时，你需要在图像的id前加上它所在精灵图的id作为前缀，后跟冒号。例如，要引用roadsigns精灵图上的stop_sign图像，你需要使用roadsigns:stop_sign；

id为default的精灵图比较特殊，因为你不需要为其中包含的图像添加前缀。例如，要引用上面默认精灵图中id为airport的图像，你可以简单地使用airport；

精灵图源格式

有效的精灵图源必须提供两种类型的文件：

  • 图像文件，这是包含精灵图数据的PNG图像；
  • 索引文件，这是一个JSON文档，包含对精灵图中每个图像的描述。此文件的内容必须是一个JSON对象，其键形成标识符，用作上述样式属性的值，其值是描述图像尺寸（width和height属性）、像素比（pixelRatio）及其在精灵图中的位置（x和y）的对象。例如，包含单个图像的精灵图可能具有以下索引文件内容：
{
    "poi": {
        "width": 32,
        "height": 32,
        "x": 0,
        "y": 0,
        "pixelRatio": 1
    }
}
SDK支持MapLibre GL JSMapLibre Native AndroidMapLibre Native iOS
基本功能✅✅✅
textFitWidth, textFitHeight4.2.011.4.06.6.0

可选属性

除了这些必需的属性外，还支持以下可选属性：

  • content：四个数字的数组，前两个指定左上角，后两个指定右下角。如果存在，并且图标使用icon-text-fit，符号的文本将适应内容框；
  • stretchX：由两个元素数组组成的数组，包含两个数字，表示可以拉伸的区域的_起始_位置和_结束_位置；
  • stretchY：与stretchX相同，但用于垂直方向；
  • sdf：布尔值。如果为true，则图像被处理为符号距离场（SDF），其颜色可以在运行时使用icon-color和icon-halo-color属性设置。默认为false；
  • textFitWidth：TextFit枚举，值为stretchOrShrink（或未定义）、stretchOnly、proportional，描述当由于'icon-text-fit': 'both'而缩放精灵图时，水平方向的行为；
  • textFitHeight：与textFitWidth相同，但用于垂直方向；

拉伸属性

以下图像提供了有关拉伸属性的更多信息：

{
    "shield": {
        "width": 25,
        "height": 30,
        "x": 0,
        "y": 0,
        "stretchX": [[5, 10], [15, 20]]
        "stretchY": [[5, 20]]
        "pixelRatio": 1
    }
}

红色高亮部分是Y轴上拉伸发生的地方，蓝色高亮部分是X轴上拉伸发生的地方；

文本适应属性

textFitWidth和textFitHeight属性改变了缩放精灵图时精灵图内容矩形如何映射到其内容。这些属性使用TextFit枚举定义，可能有以下值：

  • stretchOrShrink（或省略）
  • stretchOnly
  • proportional

主要感兴趣的用例是：

  1. 两个属性都未定义或为stretchOrShrink

内容矩形精确缩放以包含其内容；

  1. textFitWidth = stretchOnly和textFitHeight = proportional

内容矩形缩放以精确包含其内容的高度，但宽度不会缩小到小于原始内容矩形的纵横比。这主要用于盾牌，如果其内容较窄（如数字"1"），不应变得太窄；

  1. textFitWidth = proportional和textFitHeight = stretchOnly

内容矩形缩放以精确包含其内容的宽度，但高度不会缩小到小于原始内容矩形的纵横比。这可能对第2种情况有用，但用于垂直书写的脚本（使用"text-writing-mode": ["vertical"]）；

高DPI设备

在高DPI设备上，会在上述URL后附加@2x。例如，如果你指定了"sprite": "https://example.com/sprite"，渲染器将加载https://example.com/sprite.json和https://example.com/sprite.png，或者https://example.com/sprite@2x.json和https://example.com/sprite@2x.png；

生成精灵图

有一些工具可以从SVG文件生成精灵图，如spreet和spritezero；