数据源类型

本页记录 Mapbox GL JS 支持的不同数据源类型。数据源是 Mapbox GL JS style specification 的核心组件,定义用于渲染地图的地理数据来源。有关这些 sources 如何在瓦片系统中处理和管理的信息,请参阅 Tile System。

数据源类型简介

Sources 在 Mapbox GL JS style 的 sources 属性中定义,提供 layers 用于渲染的数据。每个 source 都有一个 type 属性,用于确定数据如何被解释和处理。

100%

数据源类型概述

Mapbox GL JS 支持几种数据源类型,每种类型都服务于特定的目的和数据格式:

100%

矢量数据源

矢量数据源提供 vector tile 数据,其中包含以紧凑的、结构化格式编码的预渲染 geometry。

属性

Property	Type	Default	Description
type	string	(required)	必须是 "vector"
url	string		到 TileJSON 资源的 URL。支持的协议包括 http:、https: 和 mapbox://<Tileset ID>。如果未提供 tiles 则需要。
tiles	string[]		瓦片 source URL 的数组。如果未提供 url 则需要。
bounds	number[4]	[-180, -85.051129, 180, 85.051129]	Source 边界框的西南和东北角。
scheme	string	"xyz"	影响瓦片坐标的 y 方向。可以是 "xyz" 或 "tms"。
minzoom	number	0	瓦片可用的最小缩放级别。
maxzoom	number	22	瓦片可用的最大缩放级别。
attribution	string		显示地图时要显示的归属。
promoteId	string/object		用作 feature id 的属性,用于 feature state。
volatile	boolean	false	Source 的瓦片是否在本地缓存。

示例

"mapbox-streets": {
  "type": "vector",
  "url": "mapbox://mapbox.mapbox-streets-v8"
}

栅格数据源

栅格数据源提供 raster tiles,其中包含像卫星影像、历史地图或其他基于图像的可视化等像素数据。

属性

Property	Type	Default	Description
type	string	(required)	必须是 "raster"
url	string		到 TileJSON 资源的 URL。
tiles	string[]		瓦片 source URL 的数组。
bounds	number[4]	[-180, -85.051129, 180, 85.051129]	Source 的边界框。
minzoom	number	0	瓦片的最小缩放级别。
maxzoom	number	22	瓦片的最大缩放级别。
tileSize	number	512	为此 layer 显示瓦片的最小视觉尺寸。
scheme	string	"xyz"	瓦片坐标方案。
attribution	string		归属文本。
volatile	boolean	false	Source 的瓦片是否在本地缓存。

示例

"satellite": {
  "type": "raster",
  "url": "mapbox://mapbox.satellite",
  "tileSize": 256
}

DEM数据源

DEM数据源（数字高程模型）sources 提供 3D terrain 渲染使用的 terrain elevation 数据。

属性

与 Raster Source 相同,加上:

Property	Type	Default	Description
encoding	string	"mapbox"	DEM 数据的编码。可以是 "mapbox" 或 "terrarium"。

示例

"terrain-source": {
  "type": "raster-dem",
  "url": "mapbox://mapbox.mapbox-terrain-dem-v1",
  "tileSize": 512,
  "maxzoom": 14
}

GeoJSON数据源

GeoJSON数据源以 GeoJSON 格式提供 vector 数据,可以从 URL 加载或内联包含在 style 中。

属性

Property	Type	Default	Description
type	string	(required)	必须是 "geojson"
data	object/string		GeoJSON 数据或到 GeoJSON 文件的 URL。
maxzoom	number	18	保留细节的最大缩放级别。
attribution	string		归属文本。
buffer	number	128	每侧的瓦片缓冲区大小。
tolerance	number	0.375	Douglas-Peucker 简化容差。
cluster	boolean	false	是否聚类 point features。
clusterRadius	number	50	聚类点时每个聚类的半径。
clusterMaxZoom	number	比 maxzoom 少一级	聚类点的最大缩放级别。
lineMetrics	boolean	false	是否计算 line 距离指标。
generateId	boolean	false	是否为 features 生成 ids。

示例

"earthquake-data": {
  "type": "geojson",
  "data": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson"
}

视频数据源

视频数据源允许你添加视频作为动态纹理在地图上显示。

属性

Property	Type	Default	Description
type	string	(required)	必须是 "video"
urls	string[]	(required)	到视频文件的 URL。
coordinates	number[][]	(required)	定义视频四个角的坐标。

示例

"drone-footage": {
  "type": "video",
  "urls": [
    "https://example.com/video.mp4",
    "https://example.com/video.webm"
  ],
  "coordinates": [
    [-122.51, 37.77],
    [-122.48, 37.77],
    [-122.48, 37.75],
    [-122.51, 37.75]
  ]
}

图片数据源

图片数据源允许你添加单个图像作为纹理在地图上显示,用于叠加历史地图或其他地理参考图像。

属性

Property	Type	Default	Description
type	string	(required)	必须是 "image"
url	string	(required)	到图像的 URL。
coordinates	number[][]	(required)	定义图像四个角的坐标。

示例

"radar": {
  "type": "image",
  "url": "https://docs.mapbox.com/mapbox-gl-js/assets/radar.gif",
  "coordinates": [
    [-80.425, 46.437],
    [-71.516, 46.437],
    [-71.516, 37.936],
    [-80.425, 37.936]
  ]
}

模型数据源

模型数据源提供用于在地图上渲染的 3D model 数据。

属性

Property	Type	Default	Description
type	string	(required)	必须是 "model" 或 "batched-model"
maxzoom	number		瓦片的最大缩放级别。
minzoom	number		瓦片的最小缩放级别。
tiles	string[]		瓦片 source URL 的数组。

示例

"buildings-3d": {
  "type": "model",
  "tiles": ["https://example.com/model/{z}/{x}/{y}.glb"],
  "minzoom": 14,
  "maxzoom": 16
}

在样式中使用数据源

下图展示了 sources 如何在 Mapbox GL style specification 中使用以及与 layers 等其他组件的关系:

100%

Source 与 Layers 的使用

不同的 source 类型与不同的 layer 类型一起工作。下表显示了 source 类型和 layer 类型之间的兼容性:

Source Type	兼容的 Layer 类型
Vector	Fill、Line、Symbol、Circle、FillExtrusion、Heatmap
Raster	Raster
Raster DEM	Hillshade
GeoJSON	Fill、Line、Symbol、Circle、FillExtrusion、Heatmap
Image	Raster
Video	Raster
Model	Custom

Layer 通过其 source 属性引用 source,对于 vector sources,可以额外指定 source-layer 来定位 source 中的特定数据。

示例

{
  "sources": {
    "mapbox-streets": {
      "type": "vector",
      "url": "mapbox://mapbox.mapbox-streets-v8"
    }
  },
  "layers": [
    {
      "id": "water",
      "type": "fill",
      "source": "mapbox-streets",
      "source-layer": "water",
      "paint": {
        "fill-color": "#00ffff"
      }
    }
  ]
}