Mapbox Style 规范

Mapbox （ 中文官网 ）致力于打造全球最漂亮的个性化地图。

这里记录下其 Web 端 API Mapbox GL JS 的地图样式规范 Style 的各个配置项：

必填项会加上 <code>*</code> ，方便根据目录进行查看

<code>version</code>：版本号（<code>必填</code>，且值必须为 <code>8</code>）

<code>name</code>：名称（<code>可选</code>，用于给 <code>style</code> 取名，方便阅读）

<code>metadata</code>：元数据（<code>可选</code>，用于给 <code>style</code> 附加一些任意属性。为避免冲突，为避免冲突，建议添加前缀，如 <code>mapbox:</code>）

<code>center</code>：地图的默认中心点（<code>可选</code>，由 <code>经度</code> 和 <code>纬度</code> 构成）

<code>zoom</code>：地图的默认缩放层级（<code>可选</code>，值越大，越靠近地表。<code>mapbox</code> 采用的是无极缩放，范围一般为 <code>0 ~ 24</code>）

<code>bearing</code>：地图的默认方位角（<code>可选</code>，表示 <code>地图视口正上方中心点</code> 在地图上 <code>北偏东</code> 的角度。默认值为 <code>0</code>）

<code>pitch</code>：地图的默认倾斜角度（<code>可选</code>，默认值为 <code>0</code>，范围为 <code>0 ~ 60</code>）

<code>sprite</code>：雪碧图（<code>可选</code>，用来指定获取雪碧图及其元数据的 URL）

<code>sprite</code> 的音译是 <code>雪碧</code>，直译是 <code>精灵</code>，表示不受地图旋转缩放影响的图标等，类似精灵漂浮在空中。

当有 <code>layer</code> 使用了 <code>background-pattern</code>、<code>fill-pattern</code>、<code>line-pattern</code>、<code>fill-extrusion-pattern</code>、<code>icon-image</code> 等属性时，<code>sprite</code> 必填。

当指定了 <code>sprite</code> 后，<code>mapbox</code> 会自动生成雪碧图的完整请求地址，分别如下：

如果浏览器进行了缩放，则会加上缩放 DPI 因子 <code>@2x</code>，如下：

<code>glyphs</code>：字形符号（<code>可选</code>，用来指定加载以 PBF 格式设置的 <code>有向距离场</code> 字形的 URL 模板）

URL 模板必须带有占位符 <code>{fontstack}</code> 和 <code>{range}</code>。

当有 <code>layer</code> 使用了 <code>text-field</code> 属性时，<code>glyphs</code> 必填。

<code>transition</code>：全局的过渡动画属性（<code>可选</code>，用来作为所有过渡动画属性的默认值）

<code>light</code>：全局的光源（<code>可选</code>）

<code>sources</code>：数据源集合（<code>必填</code>，用于包含一系列数据源 <code>source</code>，这些数据源提供了在地图上显示的数据）

<code>sources</code> 是对象 <code>{}</code> 的形式，其属性名就是 <code>数据源的名称</code>（或者说 <code>数据源的 id</code>），这样可以根据 <code>数据源的名称</code>（或者说 <code>数据源的 id</code>）快速获取数据源的信息。

每个数据源 <code>source</code> 都有一个 <code>type</code> 属性，用于指定其具体的类型：

<code>vector</code>：矢量

<code>raster</code>：栅格

<code>raster-dem</code>：栅格化的数字高程模型

<code>geojson</code>：GeoJSON 数据源

<code>image</code>：图片

<code>video</code>：视频

<code>vector</code>：矢量切片数据源

<code>raster</code>：栅格切片数据源（相比 <code>vector</code> 多了一个属性 <code>tileSize</code>）

<code>raster-dem</code>：栅格化的数字高程模型（相比 <code>raster</code> 多了一个属性 <code>encoding</code>）

<code>geojson</code>：GeoJSON 数据源（数据必须通过 <code>data</code> 属性指定，<code>data</code> 属性值就是一个 <code>GeoJSON</code> 或者 <code>GeoJSON</code> 的请求地址）

<code>image</code>：图片数据源

<code>video</code>：视频数据源

<code>layers</code>：图层集合（<code>必填</code>，包含了一系列图层 <code>layer</code>，这些图层指定了如何渲染数据源提供的数据）

每个图层 <code>layer</code> 都有 <code>id</code>（具有唯一性）和 <code>type</code> 属性，其中 <code>type</code> 属性指定了其具体的渲染类型：

<code>fill</code>：填充

<code>line</code>：线

<code>circle</code>：圆点

<code>symbol</code>：符号

<code>background</code>：背景

<code>heatmap</code>：热力图

<code>hillshade</code>：坡面阴影

<code>fill-extrusion</code>：三维填充

<code>fill</code>：填充（用于给多边形 <code>polygon</code> 进行填充和描边）

<code>line</code>：线（用于绘制成一条条线）

<code>circle</code>：圆点（用于绘制成一个个圆点）

<code>symbol</code>：符号（用于绘制成一个个图标或者文本标签等）

<code>background</code>：背景（用于绘制成整个地图的背景或者图案）

<code>raster</code>：栅格（用于绘制栅格地图，比如卫星影像）

<code>heatmap</code>：热力图（用于绘制成热力图的效果）

<code>hillshade</code>：坡面阴影（基于 <code>DEM</code> 数字高程模型进行坡面阴影的可视化渲染）

<code>fill-extrusion</code>：三维填充（用于给三维多边形进行填充和描边）

<code>Expressions</code>：表达式集合（并非 <code>style</code> 的属性，只是 <code>layer</code> 的任何 <code>layout</code> 布局属性和 <code>paint</code> 绘制属性，以及 <code>filter</code> 属性等，它们的值都可以指定成一个表达式 <code>Expression</code>）

一个 <code>Expression</code> 定义了一个公式，总体来说可以将公式中的操作符分为以下 <code>5</code> 种：

<code>Mathematical operators</code>：数学操作符，用来对数值进行数学运算

<code>Logical operators</code>：逻辑操作符，用来计算布尔值和条件控制

<code>String operators</code>：字符串操作符，用来操作字符串

<code>Data operators</code>：数据操作符，用来访问数据源中的要素 <code>feature</code>

<code>Camera operators</code>：照相机操作符，用来访问当前地图视图的各个参数

<code>Expressions</code> 是 <code>Expression</code> 的集合。而 <code>Expression</code> 是以 <code>JSON</code> 数组的形式来表示的，数组的第一个元素是 <code>Expression</code> 的操作符的名称，后续的元素表示操作的参数（也可以是一个 <code>Expression</code>）。

由以上 <code>5</code> 种操作符，相应地可以推出 <code>5</code> 种表达式集合 <code>Expressions</code>，并且相互之间可以组合使用：

<code>Mathematical expressions</code>

<code>Logical expressions</code>

<code>String expressions</code>

<code>Data expressions</code>

<code>Camera expressions</code>

这里主要讲述 <code>Data expressions</code> 和 <code>Camera expressions</code>。

一个 <code>data expression</code> 是可以访问要素数据的任何表达式。而这些表达式使用了以下至少一种数据操作符：

<code>get</code>：用于获取要素的属性值，格式为 <code>["get", "property_name"]</code>，余下具体的可以看 <code>Expression reference</code>

<code>has</code>

<code>id</code>

<code>geometry-type</code>

<code>properties</code>

<code>feature-state</code>

通过 <code>data expression</code> 可以实现区分同一个图层中的不同要素，并以不同的形式呈现。比如设置颜色 <code>circle-color</code>：

需要注意的是，并非所有的 <code>layout</code> 布局类属性和 <code>paint</code> 绘制类属性都支持 <code>data expression</code>：

具体可以看 <code>SDK Support</code> 中的 <code>data-driven styling</code> 那一行； 而且使用了 <code>feature-state</code> 操作符的 <code>data expression</code> 仅在 <code>paint</code> 绘制类属性中可用。

以下是官网中记录的暂不支持数据表达式 <code>data expression</code> 的属性：

一个 <code>camera expression</code> 是使用了 <code>zoom</code> 操作符的任何表达式。

通过 <code>camera expression</code> 可以实现图层 <code>layer</code> 根据地图的缩放层级 <code>zoom</code> 有不同的表现。 比如设置半径 <code>circle-radius</code>：

所有可以使用 <code>Expression</code> 的属性都支持 <code>camera expression</code>。不过当用于 <code>layout</code> 布局类属性和 <code>paint</code> 绘制类属性时，必须是以下几种格式：

或

为什么呢？因为 <code>["zoom"]</code> 在 <code>layout</code> 布局类属性和 <code>paint</code> 绘制类属性中仅作为 <code>interpolate</code> 或 <code>step</code> 操作的输入参数。

需要注意，<code>layout</code> 布局类属性和 <code>paint</code> 绘制类属性有一个很重要的区别：

<code>layout</code> 布局类属性中使用的 <code>camera expression</code> 只有在 <code>zoom</code> 的值是 <code>整数变化</code> 时才会重新计算。 <code>paint</code> 绘制类型属性中使用的 <code>camera expression</code> 在<code>zoom</code> 的值是 <code>小数变化</code> 时也会重新计算。比如 <code>zoom</code> 从 <code>4.1</code> 变为 <code>4.6</code>。

前面介绍了表达式集合 <code>Expressions</code>，简单地讲述了其中的 <code>Data expressions</code> 和 <code>Camera expressions</code>，而这些表达式里涉及和很多的操作符，这里就对每个操作符进行分类介绍，作为表达式的参考 <code>Expression reference</code>。

主要分为以下几类操作符：

<code>Types</code>

<code>Feature data</code>

<code>Lookup</code>

<code>Decision</code>

<code>Variable binding</code>

<code>String</code>

<code>Color</code>

<code>Math</code>

<code>Zoom</code>

<code>Heatmap</code>

<code>Types</code>：这类操作符用于 <code>断言</code> 和 <code>转换</code> 数据的类型，包含的操作符如下：

<code>Feature data</code>：这类操作符用于操作要素的数据。

<code>Lookup</code>：这类操作符用于查找并获取值

<code>Decision</code>：这类操作符用于条件判断

<code>Ramps, scales, curves</code>：这类操作符用于渐变、缩放、曲线等特殊效果的设置。

<code>Variable binding</code>：这类操作符用于变量绑定。

<code>String</code>：这类操作符用于操作字符串。

<code>Color</code>：这类操作符用于操作颜色。

<code>Math</code>：这类操作符用于数学运算。

<code>Zoom</code>：这类操作符只包含一个操作符 <code>zoom</code>，用于获取当前地图的缩放层级。

<code>Heatmap</code>：这类操作符只包含一个操作符 <code>heatmap-density</code>，用于获取热力图的密度（特定像素内有多少个数据点），只能在 <code>heatmap-color</code> 中使用。

之前介绍了表达式集合 <code>Expressions</code>，我们知道了 <code>layout</code> 布局类属性和 <code>paint</code> 绘制类属性的值都可以设为一个表达式 <code>Expression</code>。

同样地，函数 <code>Function</code> 也可以作为其 <code>layout</code>布局类属性和 <code>paint</code> 绘制类属性的属性值。

需要注意的是，在使用 <code>Function</code> 作为属性值时，实际上是一个对象 <code>{}</code>。 ps：不晓得 <code>Function</code> 翻译成 “函数” 对不对，还是说翻译成 “功能”......

<code>Functions</code> 是 <code>Function</code> 的集合。<code>Function</code> 可以用来根据 <code>地图缩放层级</code> 和 <code>地图要素的属性</code> 来控制地图要素的呈现。所以可以分为三类：

<code>Zoom functions</code>

<code>Property functions</code>

<code>Zoom-and-property functions</code>

一个 <code>zoom function</code> 允许地图的呈现根据 <code>地图的缩放层级</code> 而改变。

一个 <code>property function</code> 允许地图的呈现根据 <code>地图要素的属性</code> 而改变。

一个 <code>zoom-property function</code> 允许地图的呈现根据 <code>地图的缩放层级</code> 和 <code>地图要素的属性</code> 而改变。

（完）