MapboxGL Wiki

English

简体中文

English

简体中文

Appearance

Style Specification ​

Style Specification 定义 Mapbox GL JS 中地图的视觉外观和行为。它是一个结构化的 JSON 格式,描述地图视觉呈现的所有方面,包括数据源、渲染图层、相机位置、光照、地形和其他视觉元素。本文档概述了样式规范的结构和组件,解释它们如何相互关联以及与渲染管道的关系。

有关规范内用于数据驱动样式的表达式系统的信息,请参阅 Expression System。

样式文档结构 ​

Mapbox GL 样式是一个具有特定必需和可选属性的 JSON 对象。在最基本的级别上,样式必须包括 version(必须为 8)、sources(定义要显示的数据)和 layers(定义数据应如何渲染)。

以下是样式文档的一些关键组件:

PropertyTypeDescription
versionNumber必须为 8.
nameString样式的人类可读名称.
sourcesObject样式中使用的数据源.
layersArray定义数据如何可视化的图层.
spriteStringsprite 图像和元数据的 URL.
glyphsString加载字体字形的 URL 模板.
centerArray默认地图中心位置 [longitude, latitude].
zoomNumber默认缩放级别.
bearingNumber默认方位角(旋转),单位为度.
pitchNumber默认俯仰角(倾斜),单位为度.

数据流和处理 ​

使用 Style Specification 时,数据通过几个处理步骤流动:

SVG
100%

Sources ​

Sources 定义将在地图上显示的数据。每个源都有唯一的 ID 和类型,以及类型特定的属性。

Source Types ​

Source TypeDescription
vector分块矢量数据,通常为 MVT 格式
raster分块栅格图像
geojsonGeoJSON 数据
image单个栅格图像
video视频源
raster-dem数字高程模型(DEM)栅格数据

Layers ​

Layers 定义来自 sources 的数据如何在地图上样式化和渲染。每个图层引用一个源并应用样式属性来渲染数据。

Layer Types ​

Layer TypeDescriptionSource Types
background有色或图案背景None (no source)
fill填充多边形vector, geojson
line描边线条vector, geojson
symbol图标和文本标签vector, geojson
raster栅格图像raster
circle小圆圈vector, geojson
fill-extrusion拉伸(3D)多边形vector, geojson
hillshadeDEM 数据的山体阴影可视化raster-dem
sky天空(大气)渲染None (no source)
model3D 模型model

Layer Properties ​

每种图层类型有两种属性:

  1. Layout Properties:定义要素的放置和外观(例如,符号的可见性、文本字段)
  2. Paint Properties:定义视觉方面(例如,颜色、不透明度、宽度)
SVG
100%

Style Implementation ​

样式规范主要通过代码库中的 Style 类实现,该类管理样式的加载、解析和应用。

Expressions 和数据驱动样式 ​

虽然样式规范的核心结构是基于 JSON 的,但 Mapbox GL JS 使用表达式进行高级数据驱动样式。有关此内容的更多详细信息,请参阅 Expression System 文档。

图层绘制属性中表达式的示例:

{
  "id": "roads",
  "type": "line",
  "source": "mapbox-streets",
  "source-layer": "road",
  "paint": {
    "line-color": [
      "match",
      ["get", "type"],
      "motorway", "#009de0",
      "trunk", "#f44",
      "primary", "#f70",
      "secondary", "#fbb",
      "#ccc"
    ],
    "line-width": [
      "interpolate", ["linear"], ["zoom"],
      10, 1,
      14, 5
    ]
  }
}

特殊功能和全局属性 ​

样式规范包括几个影响整个地图的特殊功能和全局属性:

光照和照明 ​

地形 ​

雾 ​

投影 ​

高级功能 ​

Imports ​

样式规范支持从其他源导入样式,允许组合和重用。

Configuration Options ​

样式可以包含配置选项,允许在不更改基础样式的情况下进行自定义。

Featuresets ​

Featuresets 是一项实验性功能,允许定义用于查询、交互和状态管理的要素集。

使用 Style Specification ​

Style Specification 以几种方式使用:

  1. 加载样式:可以从 URL 或直接作为 JSON 对象加载样式

    map.setStyle('mapbox://styles/mapbox/streets-v11');
// 或
map.setStyle({
  version: 8,
  sources: { ... },
  layers: [ ... ]
});

  2. 修改样式:各种方法允许在加载后修改样式

    map.addSource('new-source', { type: 'geojson', data: { ... } });
map.addLayer({ id: 'new-layer', type: 'circle', source: 'new-source' });
map.setPaintProperty('new-layer', 'circle-color', 'red');

  3. 查询要素:可以查询样式的图层以查找渲染的要素

    const features = map.queryRenderedFeatures(point, { layers: ['my-layer'] });

  4. 与要素交互:样式规范和 featuresets 可用于与特定要素交互

    map.addInteraction('click', {
  type: 'click',
  target: { featuresetId: 'buildings' },
  handler: (e) => {
    // 处理建筑物的点击
  }
});

实现细节 ​

样式规范由 Mapbox GL JS 通过几个关键类处理:

Style 类 ​

Style 类是样式规范的中央实现。它处理:

  • 加载样式 JSON
  • 创建和管理数据源和图层
  • 更新样式属性
  • 协调样式转换
  • 处理样式以进行渲染
SVG
100%

StyleLayer 类 ​

StyleLayer 类表示样式规范中的单个图层。它处理:

  • 存储图层属性
  • 评估图层属性中的表达式
  • 渲染图层的要素
  • 查询图层中的要素

SourceCache 类 ​

SourceCache 类管理源的数据。它处理:

  • 加载和缓存瓦片
  • 跟踪视口
  • 根据需要使瓦片失效和刷新

结论 ​

Style Specification 是 Mapbox GL JS 样式系统的基础。它提供了一个结构化的、基于 JSON 的格式来定义地图视觉呈现的所有方面,从数据源到渲染图层到光照和地形等全局效果。理解规范的结构和组件是使用 Mapbox GL JS 创建自定义地图的关键。

Copyright © 2026 LZUGIS