Mapbox: style样式规范——图层篇

Mapbox的style是定义地图视觉效果的文档，决定了地图绘制什么样的数据，以怎样的顺序绘制，以及以怎样的样式绘制。

样式文件的layers属性表罗列出了该文件中所有可以操作的图层。每个图层的类型由”type”属性指定，包括以下几种类型：background, fill, line, symbol, raster, circle, fill-extrusion, heatmap, hillshade, sky.

除了backgroud或者sky属性以外，每个图层必须引用一个source.图层从此数据源处获取到数据，以及用于过滤条件的字段属性，之后才可以决定如何绘制这些特征对象。

图层属性

id

必须是字符串

图层名称不可重复

type

必须是"fill", "line", "symbol", "circle", "heatmap", "fill-extrusion", "raster", "hillshade", "background", "sky".其中之一。

决定了图层的渲染类型。

“fill”

被填满的多边形，可选边界

“line”

可绘制线

“symbol”

绘制图标或者是文字标签

“circle”

绘制被填满的圆圈

“heatmap”

绘制热点图

“fill-extrusion”

绘制3D多边形

“raster”

栅格地图纹理例如卫星影像图

“hillshade”

基于DEM数据的客户端山体阴影可视化。目前仅支持Mapbox Terrain RGB和Mapzen Terrarium瓦片。

“background”

设置地图的背景颜色和模式

“sky”

围绕地图周围的球形圆顶，永远在其他图层之后渲染。

filter

可使用“expression”表达式指定源要素的条件。只有符合过滤条件的要素才会展示在地图上。缩放表达式仅可作用于整数层级。feature-state不支持过滤条件表达式。

layout

图层的布局属性

maxzoom

可选0-24之间的数值。

表示了该图层可缩放到的最大层级。如果缩放层级等于或超出某图层的最大层级，该图层将会被隐藏。

minzoom

可选0-24之间的数值。

表示了该图层可缩放到的最小层级。如果缩放层级等于或小于某图层的最小层级，该图层将会被隐藏。

metadata

用于跟踪图层的随意属性，不影响渲染。该属性需要添加前缀以避免冲突，比如“mapbox:”。

paint

图层的默认绘制属性

source

字符串类型

描述图层所用到数据源的名称。对除了background以外的所有图层类型是必选属性。

source-layer

字符串类型

图层所用到的矢量瓦片源。仅矢量瓦片数据源需要该属性，包括GeoJSON在内的其他数据源类型均不需要。

图层的次属性

图层包括两个次属性决定了图层如何渲染：layout和paint。

布局属性包含在图层的“layout”对象中。这个属性首先应用在渲染过程中，决定了所使用的数据传递到GPU的方式。对布局属性的更改需要异步。

绘制属性包含在“paint”对象中。这个属性后应用于渲染程序中。更改绘制属性比较便利，且不需要异步。

background

visibility

决定图层是否可见。属于布局属性。可选值为”visibility”,”none”.”visibility”为可见，”none”为不可见。

background-color

绘制的颜色，属于绘制属性。可选值为颜色。默认是#000000.当设置了background-pattern属性时失效。

background-pattern

接收的参数是雪碧图中用于绘制背景的图像的名称。对于无缝模式，图像宽度必须是2的系数（2、4、8、…、512）。请注意，缩放相关表达式将仅在整数缩放级别进行计算。属于绘制属性。

background-opacity

决定背景绘制的透明度。属于绘制属性。可选值在0到1之间。默认值为1.

fill

visibility

决定图层是否可见。属于布局属性。可选值为”visibility”,”none”。”visibility”为可见，”none”为不可见。

fill-antialias

是否应对填充进行抗锯齿处理。属于绘制属性。默认值为true。

fill-opacity

决定整个填充面的透明度，与fill-color不同的是该属性会影响填充面周围1像素的范围。属于绘制属性。可选值在0到1之间。默认值为1.

fill-color

决定填充面的颜色。该颜色可以指定为带有alpha分量的rgba.。属于绘制属性。可选值为颜色。默认是#000000.当设置了background-pattern属性时失效。

fill-outline-color

面元素的边界颜色。如果不指定颜色则与fill-color保持一致。属于绘制属性。当设置fill-pattern时失效。需要fill-antialia设置为true。

fill-translate

几何体的平移量。属于绘制属性。接收的参数是一个数组[x，y] ，其中负数分别表示左和上 。单位是像素,默认值是[0,0]。

fill-translate-anchor

决定fill-translate的参考系。属于绘制属性。可选值有”map”,”viewport”.默认值是map

“map”表示该线相对于地图平移。”viewport”表示相对于视窗平移。

Fill-pattern

接收的参数是雪碧图中用于填充面的图像的名称。对于无缝模式，图像宽度必须是2的系数（2、4、8、…、512）。请注意，缩放相关表达式将仅在整数缩放级别进行计算。属于绘制属性。

Line

line-cap

决定线段末端的展示方式，属于布局属性，可选值为：”butt”,”round”,”square”.

默认值为”butt”。

“butt”:线段的精确端点的有一个方形开口。

“round”:在线段端点以外，以线条宽度的一半为半径，端点为圆心绘制半圆。

“square”:在线段端点超出线段宽度一半处，绘制方形开口

Line-join

决定线段交汇处的绘制方式，属于布局属性，可选值为：”bevel”,”round”,”miter”

默认值为”miter”

“bevel” : 一种有一个正方形的端点的连接，它被画在线的端点之外，距离为线宽度的一半。

"round":一种端点为圆形的连接，画在线条端点以外，半径为线条宽度的一半，以线条端点为中心。

"miter":有一个尖角的连接点，它的外侧在路径的端点之外，直到它们相遇为止。

Line-miter-limit

对于锐角情况自动将miter转换为bevel.属于布局属性。接收数字类型的参数，默认值为2.

需要line-join属性为”miter”。

line-round-limit

对于浅角度情况，自动将round转换为miter。属于布局属性。默认值为1.05.需要line-join属性设置为”round”.

visibility

决定图层是否可见。属于布局属性。可选值为”visibility”,”none”.”visibility”为可见，”none”为不可见。

line-opacity

线数据绘制的透明度。属于绘制属性。可选值在0到1之间。默认值为1.

line-color

绘制的颜色，属于绘制属性。可选值为颜色。默认是#000000.当设置了line-pattern属性时失效。

line-translate

几何体的平移量。属于绘制属性。接收的参数是一个数组[x，y] ，其中负数分别表示左和上 。单位是像素,默认值是[0,0]。

line-translate-anchor

决定line-translate的参考系。属于绘制属性。可选值有”map”,”viewport”.默认值是map

“map”表示该线相对于地图平移。”viewport”表示相对于视窗平移。

line-width

线的粗细。属于绘制属性。可选值为大于0的数字。单位是像素，默认值是1.

line-gap-width

在线的实际路径之外绘制描边时，该值指示内部间隙的宽度。属于绘制属性。可选值为大于0的数字。单位是像素，默认值是1.

line-offset

线的偏移量。对于线性要素，正值相对于线的方向向右偏移，负值向左偏移。对于多边形特征，正值表示向内偏移，负值表示向外偏移。线偏移了。可选值为大于0的数字。单位是像素，默认值是1.

line-blur

以像素为单位,应用于线条模糊。属于绘制属性，可选值为大于等于0的数。默认值为0.

line-dasharray

指定虚线的实线和间隙的长度。属于绘制属性，可选值为大于等于0的数。单位是线宽（line-width）。如果要将短划线长度转换为像素，请将长度乘以当前线宽。另请注意，缩放相关表达式将仅在整数缩放级别进行计算。当设置line-pattern属性时失效。

line-pattern

接收的参数是雪碧图中用于绘制图像线的图像的名称。对于无缝模式，图像宽度必须是2的系数（2、4、8、…、512）。请注意，缩放相关表达式将仅在整数缩放级别进行计算。属于绘制属性。

Symbol

symbol-placement

决定标签相对于几何体的位置。属于布局属性。可选值”point””line””line-center”默认值为”point”

“point”: 标签放置在几何图形所在的点上。

"line":标签沿几何图形的直线放置。只能用于线和多边形几何图形。

"line-center":标签放置在几何图形线的中心。只能用于线型和多边形几何体。

symbol-spacing

决定两个符号中心点之间的距离。属于布局属性。可选值大于等于1.单位是像素。默认值为250.需要symbol-placement属性设置为”line”

symbol-avoid-edges

若该值true，为了避免碰撞，符号将不会穿过瓦片边缘。建议在矢量瓦片中没有足够的填充来防止冲突的图层中使用，或者如果是放置在线符号层之后的点符号层中使用。属于布局属性默认值为false.

symbol-z-order

控制渲染同一层中重叠符号的顺序。属于布局属性，可选值为”auto”,”viewpoprt-y”,”source”

默认值为”auto”

"auto":如果设置了符号排序键，则根据该键进行排序。否则，按符号相对于视口的y位置对符号进行排序。

"viewport-y":按符号相对于视口的y位置对符号进行排序。

"source":符号将以与源数据相同的顺序呈现，而不应用排序。

icon-allow-overlap

如果为true，则即使图标与以前绘制的其他符号冲突，图标也将可见。属于布局属性。默认值为false.需要icon-image

icon-ignore-placement

如果为true，则即使其他符号与图标发生碰撞，也可以看到它们。属于布局属性，默认值为false.需要icon-image

icon-optional

如果为true，则当图标与其他符号冲突但文本没有冲突时，将显示文本而不显示相应的图标。属于布局属性。默认值为false.同时需要icon-image，text-field属性。

icon-rotation-alignment

结合symbol-placement，确定图标的旋转。属于布局属性。可选值为”map”,”viewport”,”auto”

“map” 将symbol placement设定为point时，图标将东西向对齐。当symbol placement设置为“line”或“line-center”时，将图标x轴与直线对齐。

“viewport” 生成其x轴与视口的x轴对齐的图标，而不考虑symbol-placement的值。

"auto":当“symbol-placement”设置为“点”时，效果等同于viewport。当“symbol-placement”设置为“line”或“line-center”时，效果等同于“map”。

icon-size

按提供的因子缩放图标的原始大小。图像的新像素大小将是原始像素大小乘以icon-size。例如1为原尺寸；3为原始图像放大三倍。属于布局属性，可选值大于等于1，默认值为1，需要icon-image属性。

icon-text-fit

缩放图标以适应相关文本。属于布局属性，可选值有”none”,”width”,”height”,”both”.默认值为”none”。需要 icon-image，text-field属性。

"none":图标以其固有的纵横比显示。

"width":图标在x维中缩放以适应文本的宽度。

"height":图标在y维度中缩放以适应文本的高度。

"both":图标在x和y两个维度上都进行缩放。

icon-text-fit-padding

添加到由图标文本匹配确定的尺寸的附加区域的大小，按顺时针顺序：顶部、右侧、底部、左侧。属于布局属性，接收数组形式的参数。单位是像素。默认值是[0,0,0,0].需要icon-image，text-field.icon-text-fit设为”both”,or “width”,”height”

icon-image

接收参数为雪碧图中用于绘制图像背景的图像的名称。属于布局属性。

icon-rotate

顺时针转动图标的角度。属于布局属性，参数为数字，单位为角度。默认值是0。需要icon-image属性。

icon-padding

用于检测符号冲突的图标边界框周围的附加区域的大小。属于布局属性。可选值大于等于1.单位是像素默认值为1.需要icon-image

icon-keep-upright

如果为true，则翻转图标以防止其颠倒呈现。属于布局属性，默认值为false.需要icon-image，需要icon-rotation-alignment设置为”map”。需要symbol-placement设置为”line”或者”line-center”

icon-offset

图标与其锚点的偏移距离。正值表示向右和向下，负值表示向左和向上。将每个组件乘以icon-size的值以获得以像素为单位的最终偏移。当与图标旋转相结合时，偏移将视旋转方向为向上。属于布局属性。接收参数为一个数组。默认值为[0,0]需要icon-image。

icon-anchor

决定图标锚定的位置。属于布局属性。可选值有"center", "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right"。默认值为“center”需要icon-image属性。

icon-pitch-alignment

决定地图倾斜时图标的方向。属于布局属性。可选值有”map”,”viewport”,”auto”.默认值是”auto”。

“map” 图标与地图平面对齐。

"viewport":图标与视口平面对齐。

"auto":根据icon-rotation-alignment的值自动匹配。

text-pitch-alignment

决定地图倾斜时文本的方向。属于布局属性。可选值有”map”,”viewport”,”auto”.默认值是”auto”.

“map” 文本与地图平面对齐。

"viewport":文本与视口平面对齐。

"auto":根据text-rotation-alignment的值自动匹配。

text-rotation-alignment

结合symbol-placement，确定形成文本的各个图示符的旋转行为。属于布局属性。可选值为”map”,”viewport”,”auto”。需要text-field.

“map” 将symbol placement设定为point时，文本将东西向对齐。当symbol placement设置为“line”或“line-center”时，将文本x轴与直线对齐。

“viewport” 生成其x轴与视口的x轴对齐的文本，而不考虑symbol-placement的值。

"auto":当“symbol-placement”设置为“点”时，效果等同于viewport。当“symbol-placement”设置为“line”或“line-center”时，效果等同于“map”。

text-field

用于文本标签的值。属于布局属性，如果提供了纯字符串，它将被视为使用默认/继承格式选项格式化的字符串。

text-font

用于显示文本的字体堆栈。属于布局属性。接收的参数为字符串组成的数组。默认值为 ["Open Sans Regular","Arial Unicode MS Regular"]，需要text-field

text-size

文本字体大小。属于布局属性。可选值大于等于0单位为像素。默认值为16.需要text-field.

text-max-width

文本换行的最大线宽。属于布局属性。可选值为大于等于的数。单位为ems.默认值为10.需要text-field

text-line-height

多行文本的文本前导值。属于布局属性。参数为数值型。单位为字符。默认值为1.2需要text-field。

text-letter-spacing

文本跟踪量。属于布局属性。参数为数值型。单位是字符。默认值为0.需要text-field。

text-justify

文本对齐选项。属于布局属性。可选值为"auto", "left", "center", "right".默认值为“center”需要text-field。

"auto":文本与定位点位置对齐。

"left":文本左对齐

"center":文本居中对齐

"right":文本右对齐

text-radial-offset

文字在符号定位方向上的径向偏移。与text-variable-anchor结合使用非常有用。属于布局属性。参数为数值型。单位为字符。默认值为0.当设置text-offet时失效。

text-variable-anchor

要增加在地图上放置高优先级标签的机会，可以提供一个文本锚定位置数组：渲染将按顺序在每个位置放置标签，然后再移动到下一个标签。。属于布局属性，可选值为数组，可选的值有"center", "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right"。需要symbol-placement为“point”.当设置text-anchor.text-offset时无效.若要使用偏移，请使用text-radial-offset，而不是text-offset。

text-anchor

决定文本锚定的位置。属于布局属性。可选值有"center", "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right".默认值为“center”需要text-field。

text-max-angle

相邻字符之间的最大角度变化。属于布局属性。参数为数值型，单位是角度。默认值为45°。需要text-field，并且需要symbol-placement设置为”line”或”line-center”。

text-rotate

文本顺时针旋转的角度。属于布局属性。可选值为数数值型。单位为角度.默认值为0.需要text-field属性。

text-padding

文本边界框周围用于检测符号冲突的附加区域的大小。属于布局属性。可选值大于等于0.单位是像素，默认值为2。需要text-field属性。

text-keep-upright

如果为true，则翻转text以防止其颠倒呈现。属于布局属性，默认值为true.需要text-field，需要text-rotation-alignment设置为”map”。需要symbol-placement设置为”line”或者”line-center”。

text-transform

指定如何将文本大写，类似于CSS text-transform属性。属于布局属性。可选值为"none", "uppercase", "lowercase"默认值为"none"。需要text-field。

text-offset

文本与其锚点的偏移距离。正值表示向右和向下，负值表示向左和向上。属于布局属性。接收参数为一个数组。默认值为[0,0]需要text-field。设置text-radial-offset时失效。

text-allow-overlap

如果为true，则即使文本与以前绘制的其他符号冲突，文本也将可见。属于布局属性。默认值为false。需要text-field。

text-ignore-placement

如果为true，则即使其他符号与文本冲突，也可以看到它们。属于布局属性。默认值为false.需要text-field。

text-optinal

如果为true，则当文本与其他符号冲突且图标没有冲突时，图标将显示而不显示相应的文本。属于布局属性。默认值为false.需要icon-image。

visibility

决定图层是否可见。属于布局属性。可选值为”visibility”,”none”.”visibility”为可见，”none”为不可见。

Icon-opacity

图标绘制的透明度。属于绘制属性。可选值在0到1之间。默认值为1.需要icon-image。

icon-color

只用于sdf图标，决定了图表的颜色。属于绘制属性，默认值为"#000000".需要icon-image。

icon-halo-color

仅用于SDF图标，决定图标光圈的颜色。属于绘制属性，默认值为"rgba(0, 0, 0, 0)"。需要icon-image。

icon-halo-width

光圈到图标轮廓的距离。参数为大于等于0的数值型。单位为像素。默认值为0.需要icon-image。

icon-halo-blur

往外淡出光环。属于绘制属性。参数为大于等于0的数值型。单位为像素。默认值为0.需要icon-image。

icon-translate

图标的定位点从其原始位置移动的距离。正值表示向右和向下，负值表示向左和向上。属于绘制属性。接收数值型组成的数组。单位为像素。默认值为[0,0]需要icon-image。

icon-translate-anchor

控制icon-translatede的参考系。属于绘制属性。可选值有”map”,”viewport”。默认值是map。

“map”表示该线相对于地图平移。”viewport”表示相对于视窗平移。

text-color

文本绘制的颜色。属于绘制属性。默认值为"#000000"，需要text-field。

text-halo-color

文本的光圈的颜色，有助于在背景上突出显示。属于绘制属性，默认值为"rgba(0, 0, 0, 0)"。需要text-field。

text-halo-width

光圈到字体轮廓的距离。光圈最大宽度不能超过字体的四分之一。属于绘制属性。参数为大于等于0的数值型。单位为像素。默认值为0。需要text-field。

text-halo-blur

光环向外逐渐消失的距离。属于绘制属性。参数为大于等于0的数值型。单位为像素。默认值为0.需要text-field。

text-translate

文本的定位点从其原始位置移动的距离。正值表示向右和向下，负值表示向左和向上。属于绘制属性，接收数值型组成的数组。单位为像素。默认值为[0,0]。需要text-filed。

text-translate-anchor

控制text-translatede的参考系。属于绘制属性。可选值有”map”,”viewport”。默认值是map。

“map”表示该线相对于地图平移。”viewport”表示相对于视窗平移。

fill-extrusion

visibility

决定图层是否可见。属于布局属性。可选值为”visibility”,”none”.”visibility”为可见，”none”为不可见。

fill-extrusion-opacity

整个填充延申图层的不透明度。这是按层而不是按要素渲染的，数据无法操控样式。属于绘制属性。可选值为0到1之间的数。默认值是1。

fill-extrusion-color

延申填充的基础颜色。拉伸的曲面将根据此颜色和根灯光设置进行不同的着色。如果将此颜色指定为带有alpha分量的rgba，则将忽略alpha分量。属于绘制属性。默认值是#000000.当设置fill-extrusion-pattern时失效。

fill-extrusion-translate

几何体的偏移。值为[x，y]，其中负数分别表示左和上（在平面上）。属于绘制属性。接收数值型组成的数组，默认值为[0,0]，单位为像素。

fill-extrusion-translate-anchor

决定fill-extrusion -translate的参考系。属于绘制属性。可选值有”map”,”viewport”.默认值是map

“map”表示该线相对于地图平移。”viewport”表示相对于视窗平移。

fill-extrusion-pattern

接收的参数是雪碧图中用于填充面的图像的名称。对于无缝模式，图像宽度必须是2的系数（2、4、8、…、512）。请注意，缩放相关表达式将仅在整数缩放级别进行计算。属于绘制属性。

fill-extrusion-height

填充面延申的高度。属于绘制属性。参数为大于等于0的数值型。单位是米，默认值是0。

fill-extrusion-vertical-gradient

是否向填充延申图层的侧面应用垂直渐变。如果为true，则在靠下方的位置，侧面的阴影将略暗。