06. 数据源（Sources）

06. 数据源（Sources）

概述

数据源（Source）是地图样式中定义数据来源的核心部分。MapLibre 支持六种数据源类型，每种类型适用于不同的场景。本节学习：

• 六种数据源类型及其配置
• TileJSON 规范
• 瓦片 URL 模板 {z}/{x}/{y}
• 运行时动态管理数据源

---

数据源类型总览

类型	说明	典型用途
vector	矢量瓦片	高性能矢量底图、可交互要素
raster	栅格瓦片	卫星影像、传统地图底图
raster-dem	高程栅格瓦片	3D 地形渲染
geojson	GeoJSON 数据	自定义要素、动态数据
image	图片覆盖	叠加历史地图、卫星图片
video	视频覆盖	叠加视频流

---

1. vector — 矢量瓦片

矢量瓦片以 PBF（Protocol Buffer）格式存储矢量数据，渲染在客户端完成。

{
  "my-vector": {
    "type": "vector",
    "tiles": ["https://example.com/tiles/{z}/{x}/{y}.pbf"],
    "minzoom": 0,
    "maxzoom": 14
  }
}

也可以使用 TileJSON URL

{
  "my-vector": {
    "type": "vector",
    "url": "https://example.com/tilejson.json"
  }
}

常用属性

属性	说明
tiles	瓦片 URL 模板数组
url	TileJSON URL（与 tiles 二选一）
minzoom	最小缩放级别（默认 0）
maxzoom	最大缩放级别（默认 22）
bounds	数据范围 [west, south, east, north]
attribution	版权归属文本

---

2. raster — 栅格瓦片

栅格瓦片是预渲染的图片，直接贴到地图上。

{
  "osm-raster": {
    "type": "raster",
    "tiles": ["https://tile.openstreetmap.org/{z}/{x}/{y}.png"],
    "tileSize": 256,
    "attribution": "© OpenStreetMap"
  }
}

关键参数

• tileSize：瓦片大小，常见值 256 或 512（默认 512）
• 天地图等国内服务使用 256

---

3. raster-dem — 高程瓦片

用于 3D 地形渲染，瓦片中存储的是高程数据而非图片。

{
  "terrain-dem": {
    "type": "raster-dem",
    "url": "https://demotiles.maplibre.org/terrain-tiles/tiles.json",
    "tileSize": 256
  }
}

配合 setTerrain 开启 3D 地形：

map.setTerrain({ source: 'terrain-dem', exaggeration: 1.5 })

---

4. geojson — GeoJSON 数据

最灵活的数据源，支持内联数据或远程 URL。

内联数据

{
  "points": {
    "type": "geojson",
    "data": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": { "type": "Point", "coordinates": [116.39, 39.91] },
          "properties": { "name": "北京" }
        }
      ]
    }
  }
}

远程 URL

{
  "remote-data": {
    "type": "geojson",
    "data": "https://example.com/data.geojson"
  }
}

GeoJSON 数据源特有属性

属性	说明
data	GeoJSON 对象或 URL
cluster	是否启用聚合（默认 false）
clusterRadius	聚合半径（像素，默认 50）
clusterMaxZoom	聚合最大缩放级别（默认比 maxzoom 小 1）
generateId	自动为要素生成 ID（默认 false）
tolerance	简化容差（默认 0.375）

动态更新

const source = map.getSource('points') as maplibregl.GeoJSONSource
source.setData(newGeoJSON)

---

5. image — 图片源

将一张图片覆盖在指定的地理范围上。

{
  "overlay-image": {
    "type": "image",
    "url": "https://example.com/overlay.png",
    "coordinates": [
      [116.0, 40.2],
      [117.0, 40.2],
      [117.0, 39.6],
      [116.0, 39.6]
    ]
  }
}

• coordinates：四个角的经纬度 [左上, 右上, 右下, 左下]
• 适合叠加历史地图、卫星影像裁片

---

6. video — 视频源

将视频覆盖在指定的地理范围上，用法与 image 类似。

{
  "drone-video": {
    "type": "video",
    "urls": [
      "https://example.com/video.mp4",
      "https://example.com/video.webm"
    ],
    "coordinates": [
      [116.0, 40.2],
      [117.0, 40.2],
      [117.0, 39.6],
      [116.0, 39.6]
    ]
  }
}

• urls：支持多格式（浏览器会选择支持的格式）

---

瓦片 URL 模板

瓦片 URL 使用占位符模板：

占位符	说明
{z}	缩放级别
{x}	瓦片列号
{y}	瓦片行号

https://tile.openstreetmap.org/{z}/{x}/{y}.png

在 zoom=2 时，全球被分为 4×4=16 个瓦片，z=2, x=03, y=03。

子域名负载均衡

部分服务使用子域名分散请求：

tiles: [
  'https://a.tile.example.com/{z}/{x}/{y}.png',
  'https://b.tile.example.com/{z}/{x}/{y}.png',
  'https://c.tile.example.com/{z}/{x}/{y}.png'
]

---

TileJSON 规范

TileJSON 是描述瓦片数据元信息的 JSON 格式：

{
  "tilejson": "3.0.0",
  "name": "OpenStreetMap",
  "tiles": ["https://tile.openstreetmap.org/{z}/{x}/{y}.png"],
  "minzoom": 0,
  "maxzoom": 19,
  "bounds": [-180, -85.0511, 180, 85.0511],
  "center": [0, 0, 2],
  "attribution": "© OpenStreetMap"
}

在数据源中直接使用 TileJSON URL：

{
  "type": "vector",
  "url": "https://example.com/tiles.json"
}

---

运行时管理数据源

// 添加数据源
map.addSource('my-source', {
  type: 'geojson',
  data: { type: 'FeatureCollection', features: [] }
})

// 获取数据源
const source = map.getSource('my-source')

// 移除数据源（需先移除关联的图层）
map.removeLayer('my-layer')
map.removeSource('my-source')

// 判断数据源是否存在
if (map.getSource('my-source')) { ... }

---

本课小结

• MapLibre 支持 6 种数据源：vector / raster / raster-dem / geojson / image / video
• vector 和 raster 通过瓦片 URL 或 TileJSON 加载
• geojson 最灵活，支持内联数据和动态更新
• 瓦片 URL 模板使用 {z}/{x}/{y} 占位符
• 运行时可通过 addSource / removeSource 动态管理

---

📌 上一节：05. 地图样式详解 📌 下一节：07. GeoJSON 数据实战