当前位置：首页 > article >正文

【Mapbox】介绍及基本使用

article 2025/3/16 11:32:08

文章目录

一、认识 Mapbox
- 1. 核心功能
- 2. 应用场景
- 3. 优势
- 4. 如何使用
二、Mapbox GL JS
- 1. 简单示例
- 2. 导入或安装
- - 2.1 CDN
  - 2.2 npm
- 3. Map styles 地图样式
- - 3.1 Set a style 设置样式
  - - Mapbox Standard
    - 经典样式模板和自定义样式
  - 3.2 Configure a style 配置样式
  - - Mapbox Standard
    - Mapbox Standard Satellite
  - 3.3 Work with layers 使用图层
  - 3.4 Source types 源类型
  - 3.5 Layer types 图层类型
  - - 1. Line layer 线层
    - 2. Fill layer 填充层
    - 3. Circle layer 圆层
    - 4. Symbol layer 符号图层
    - 5. Fill extrusion layer 填充挤出层
    - 6. Hillshade layer 山体阴影图层
    - 7. Heatmap layer 热力图图层
    - 8. Raster layer 栅格图层
    - 9. Background layer 背景图层
  - 3.6 Styling your layers 设置图层样式
- 4. 用户交互
- - 4.1 手势和事件
  - 4.2 交互事件
  - 4.3 外部交互

一、认识 Mapbox

Mapbox 是一个强大的地理位置数据平台，旨在为开发者提供创建、定制和集成地图及位置相关功能的工具。它通过提供一系列灵活的开发工具和 API，帮助开发者在应用程序中实现高度定制化的地图显示、地理编码、路线规划、导航以及数据可视化等功能

访问 Mapbox 官网: https://www.mapbox.com/
阅读 Mapbox 文档: https://docs.mapbox.com/

1. 核心功能

自定义地图设计
Mapbox 允许用户通过其 Mapbox Studio 工具设计独特的地图样式。开发者可以调整地图的颜色、字体、图标等元素，以匹配品牌风格或应用场景需求。
地理编码
提供地理编码服务，将地址转换为经纬度坐标（正向地理编码），或将经纬度坐标转换为可读的地址（反向地理编码）。
路线规划与导航
支持多种交通方式的路线规划（如驾车、步行、骑行等），并提供实时导航功能，包括逐向导航和交通状况更新。
数据可视化
开发者可以在地图上展示各种数据，例如通过标记、热力图、路径线、多边形等方式呈现地理数据，帮助用户更直观地理解信息。
实时数据集成
Mapbox 支持实时数据的集成，例如实时交通信息、动态位置追踪等，适用于需要实时更新的应用场景。
跨平台支持
Mapbox 提供多种平台的 SDK 和 API，支持 Web、iOS、Android 等主流开发环境，方便开发者在不同平台上实现一致的地图体验
3D 地图与沉浸式体验
Mapbox 支持 3D 地图渲染，允许开发者创建更具沉浸感的地图体验，例如建筑模型、地形起伏等。

2. 应用场景

Mapbox 广泛应用于多个行业，包括但不限于：

交通与物流：用于路线优化、车队管理和实时追踪。
旅游与导航：提供景点地图、路线规划和旅行指南。
房地产：展示房源位置、周边设施和区域分析。
数据分析：通过地图可视化展示地理数据，辅助决策。
游戏与增强现实（AR）：为游戏或 AR 应用提供地理位置支持。

3. 优势

高度可定制：开发者可以根据需求完全自定义地图样式和功能。
高性能：Mapbox 的地图渲染速度快，支持大规模数据的高效展示。
全球覆盖：提供全球范围的地图数据和服务。
开发者友好：提供详细的文档、示例代码和社区支持，降低开发门槛

4. 如何使用

注册 Mapbox 账号并获取 API 密钥。
- 注册 Mapbox 账户: https://account.mapbox.com/auth/signup/
- 获取 assess token：https://docs.mapbox.com/help/getting-started/access-tokens/
使用 Mapbox Studio 设计地图样式。
- Mapbox Studio 官方文档: https://docs.mapbox.com/studio-manual/overview/
通过 Mapbox 的 SDK 或 API 将地图集成到你的应用中。
根据需求添加地理编码、导航、数据可视化等功能

二、Mapbox GL JS

Mapbox GL JS 是一个客户端 JavaScript 库，用于使用 Mapbox 的现代地图技术构建 Web 地图和 Web 应用程序。您可以使用 Mapbox GL JS 在 Web 浏览器或客户端中显示 Mapbox 地图，添加用户交互性，并在应用程序中自定义地图体验。

官方文档：https://docs.mapbox.com/mapbox-gl-js/guides
API: https://docs.mapbox.com/mapbox-gl-js/api/

1. 简单示例

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Mapbox</title>
        <link href="https://api.mapbox.com/mapbox-gl-js/v3.10.0/mapbox-gl.css" rel="stylesheet" />
        <script src="https://api.mapbox.com/mapbox-gl-js/v3.10.0/mapbox-gl.js"></script>
        <style>
            #map {
                position: absolute;
                top: 0;
                bottom: 0;
                width: 100%;
            }
        </style>
    </head>
    <body>
        <div id="map"></div>
        <script>
            mapboxgl.accessToken = "pk.eyJ1IjoiZ3VvemhlbnNodSIsImEiOiJjbTdyYWVmcmYxNGQ3MmpvaGJyejJiMDZpIn0.NQ-ey98NqQH1zmpe9ky9XQ";
            const map = new mapboxgl.Map({
                container: "map", // container ID
                style: "mapbox://styles/mapbox/streets-v9", // style URL
                projection: "globe", // Display the map as a globe, since satellite-v9 defaults to Mercator
                zoom: 2, // starting zoom
                center: [112, 30], // starting position [lng, lat]
            });
        </script>
    </body>
</html>

2. 导入或安装

2.1 CDN

引入：

<script src='https://api.mapbox.com/mapbox-gl-js/v3.10.0/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.10.0/mapbox-gl.css' rel='stylesheet' />

使用：

<div id='map' style='width: 400px; height: 300px;'></div>
<script>
mapboxgl.accessToken = 'pk.eyJ1IjoiZ3VvemhlbnNodSIsImEiOiJjbTdyYWVmcmYxNGQ3MmpvaGJyejJiMDZpIn0.NQ-ey98NqQH1zmpe9ky9XQ';
const map = new mapboxgl.Map({
	container: 'map', // container ID
	style: 'mapbox://styles/mapbox/streets-v12', // style URL
	center: [-74.5, 40], // starting position [lng, lat]
	zoom: 9, // starting zoom
});
</script>

2.2 npm

安装：

npm install --save mapbox-gl

引入样式：

<link href='https://api.mapbox.com/mapbox-gl-js/v3.10.0/mapbox-gl.css' rel='stylesheet' />

或者

import 'mapbox-gl/dist/mapbox-gl.css';

使用：

import mapboxgl from 'mapbox-gl'; // or "const mapboxgl = require('mapbox-gl');"

mapboxgl.accessToken = 'pk.eyJ1IjoiZ3VvemhlbnNodSIsImEiOiJjbTdyYWVmcmYxNGQ3MmpvaGJyejJiMDZpIn0.NQ-ey98NqQH1zmpe9ky9XQ';
const map = new mapboxgl.Map({
	container: 'map', // container ID
	style: 'mapbox://styles/mapbox/streets-v12', // style URL
	center: [-74.5, 40], // starting position [lng, lat]
	zoom: 9, // starting zoom
});

3. Map styles 地图样式

3.1 Set a style 设置样式

Mapbox Standard

Mapbox Standard 是默认样式，在不指定任何样式的情况下实例化一个 Map 意味着您的地图将使用 Mapbox Standard

const map = new mapboxgl.Map({
  container: 'map',
  center: [-74.5, 40],
  zoom: 9
});

经典样式模板和自定义样式

如果不使用 Mapbox Standard，则可以通过使用自定义样式 URL 设置 style 属性来加载样式:

const map = new mapboxgl.Map({
  container: 'map',
  style: '<STYLE_URL>',
  center: [-74.5, 40],
  zoom: 9
});

有两种方法可以自定义地图的外观：

使用 Mapbox GL JS API 在运行时动态更新地图功能
使用 Mapbox Studio 创建自定义地图样式：Studio 手册

如果要使用 Mapbox 拥有的样式之一，请使用以下值之一:

mapbox://styles/mapbox/standard
mapbox://styles/mapbox/standard-satellite
mapbox://styles/mapbox/streets-v12
mapbox://styles/mapbox/outdoors-v12
mapbox://styles/mapbox/light-v11
mapbox://styles/mapbox/dark-v11
mapbox://styles/mapbox/satellite-v9
mapbox://styles/mapbox/satellite-streets-v12
mapbox://styles/mapbox/navigation-day-v1
mapbox://styles/mapbox/navigation-night-v1

运行时切换样式：
也可以在使用 Map 的 setStyle 方法在初始化地图后随时更改样式

3.2 Configure a style 配置样式

Mapbox Standard

官方文档：文档链接
要更改标准底图的视觉外观，可以通过 setConfigProperty 修改标准底图的视觉外观，共有15 个配置属性：

Property 财产	Type 类型	Description 描述
showPedestrianRoads	Bool	显示或隐藏所有人行道路、小路、小径。
showPlaceLabels	Bool	显示或隐藏地点标签图层。
showPointOfInterestLabels	Bool	显示或隐藏所有 POI 图标和文本。
showRoadLabels	Bool	显示或隐藏所有道路标签，包括道路盾形路牌。
showTransitLabels	Bool	显示或隐藏所有交通图标和文本。
show3dObjects	Bool	显示或隐藏所有 3D 图层（3D 建筑物、地标、树木等），包括阴影、环境光遮蔽和泛光灯。重要提示：从 v11.5.2 SDK 开始可用的配置。
theme	String	在4个主题之间切换：default、faded、monochrome & custom。重要提示：从 v11.5.2 SDK 开始可用的配置。
theme-data	String	以 Base64 编码的 LUT 图像以创建自定义颜色主题。重要提示：从 v11.9.0 SDK 开始可用的配置。
lightPreset	String	在 4 种时间状态之间切换：dusk、dawn、day 和 night。还可以使用 Mapbox 样式规范在预设之外完全自定义灯光。
font	String	从预定义选项中定义样式的字体系列。选项：Alegreya、Alegreya SC、Asap、Barlow、DIN Pro、EB Garamond、Faustina、Frank Ruhl Libre、Heebo、Inter、League Mono、Montserrat、Poppins、Raleway、Roboto、Roboto Mono、Rubik、Source Code Pro、Spectral、Ubuntu、Noto Sans CJK JP、Open Sans、Manrope、Source Sans Pro、Lato。
colorPlaceLabelHighlight	Color	设置高亮显示功能状态时使用的放置标签颜色。重要提示：从 v11.9.0 SDK 开始可用的配置。
colorPlaceLabelSelect	Color	设置[选择特征状态]时使用的标签颜色的配置。重要提示：从 v11.9.0 SDK 开始可用的配置。
colorMotorways	Color	高速公路的颜色覆盖。
colorTrunks	Color	主干道路的颜色覆盖。
colorRoads	Color	所有其他道路的颜色覆盖。

示例：

map.on('style.load', () => {
  map.setConfigProperty('basemap', 'lightPreset', 'dusk');
});

Mapbox Standard Satellite

标准卫星样式（ mapbox://styles/mapbox/standard-satellite ）结合了更新的卫星图像和矢量图层，可为用户提供更高的清晰度和细节
官方文档：文档链接

3.3 Work with layers 使用图层

运行时添加图层：

首先添加源： addSource ，使用说明
然后添加图层：addLayer，使用说明

在运行时更新图层：
使用 map.setPaintProperty 方法，示例：

map.setPaintProperty('route', 'line-opacity', 0.9);

在运行时删除图层：

删除图层：removeLayer

3.4 Source types 源类型

1. Vector
矢量源 VectorTileSource 是符合 Mapbox 矢量瓦片格式的矢量瓦片集

map.addSource('terrain', {
  type: 'vector',
  url: 'mapbox://mapbox.mapbox-terrain-v2'
});

2. GeoJSON
GeoJSON 源 GeoJSONSource 是符合 GeoJSON 规范的 JSON 对象形式的数据。GeoJSON 源是一个或多个地理特征的集合，这些地理特征可以是点、线条和多边形。数据必须通过属性 “data” 提供，其值可以是 URL 或内联 GeoJSON

map.addSource('polygon', {
  type: 'geojson',
  data: { type: 'Feature', geometry: { type: 'Polygon' /* ... */ } }
});

示例：line示例

获取源数据的工具推荐：

geojson.io
功能: 支持在地图上绘制点、线和多边形，并直接生成 GeoJSON 数据
网址: https://geojson.io/
获取地图数据：DataV.GeoAtlas地理小工具系列

3. Raster
栅格源 RasterTileSource是栅格切片集

map.addSource('openstreetmap', {
  type: 'raster',
  tiles: ['https://tile.openstreetmap.org/{z}/{x}/{y}.png'],
  tileSize: 256,
  attribution:
    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
});

4. Raster DEM
栅格 DEM 源（一种特殊情况 RasterTileSource ）包含高程数据

map.addSource('dem', {
  type: 'raster-dem',
  url: 'mapbox://mapbox.mapbox-terrain-dem-v1'
});

5. Image
图像源 ImageSource 是与地理坐标一起提供的图像。将 “coordinates” 数组中的地理坐标成 [longitude, latitude] 对指定，数组中的每个 “coordinates” 坐标对都表示按顺时针顺序列出的图像角：左上角、右上角、右下角、左下角。

map.addSource('radar', {
  type: 'image',
  url: '/mapbox-gl-js/assets/radar.gif',
  coordinates: [
    [-80.425, 46.437],
    [-71.516, 46.437],
    [-71.516, 37.936],
    [-80.425, 37.936]
  ]
});

示例：官方示例

3.5 Layer types 图层类型

1. Line layer 线层

type 为 line

map.addLayer({
  id: 'id_route',
  type: 'line',
  source: 'route',
  layout: {
    'line-cap': 'round'
  },
  paint: {
    'line-color': 'red',
    'line-opacity': 0.8
  }
});

官方示例：官方示例

2. Fill layer 填充层

type 为 fill

map.addLayer({
  id: 'id_maine',
  type: 'fill',
  source: 'maine',
  paint: {
    'fill-color': '#0080ff',
    'fill-opacity': 0.5
  }
});

官方示例：示例

3. Circle layer 圆层

type 为 circle

map.addLayer({
  id: 'id_point',
  type: 'circle',
  source: 'national-park',
  paint: {
    'circle-radius': 6,
    'circle-color': '#B42222'
  }
});

官方示例：示例

4. Symbol layer 符号图层

symbol 样式图层在地图上的点或沿线呈现图标和文本标签
type 为 symbol

map.addLayer({
  id: 'city-label',
  type: 'symbol',
  source: 'labels',
  layout: {
    'text-field': ['get', 'city_name'],
    'text-size': 12
  }
});

官方示例：示例

5. Fill extrusion layer 填充挤出层

fill-extrusion 样式图层在地图上渲染一个或多个填充（和可选描边）凸出（3D）多边形。
要添加填充拉伸层，您需要首先添加包含多边形数据的矢量或 GeoJSON 源
type 为 fill-extrusion

map.addLayer({
  id: '3d-buildings',
  source: 'composite',
  'source-layer': 'building',
  filter: ['==', 'extrude', 'true'],
  type: 'fill-extrusion',
  paint: {
    'fill-extrusion-color': '#aaa',
    'fill-extrusion-height': ['get', 'height'],
    'fill-extrusion-base': ['get', 'min_height'],
    'fill-extrusion-opacity': 0.6
  }
});

官方示例：示例

6. Hillshade layer 山体阴影图层

hillshade 样式图层在客户端渲染数字高程模型（DEM）数据
该实现仅支持由 Mapbox Terrain RGB 或 Mapzen Terrarium 瓦片组成的源。添加适当的源后，您可以使用 layer 中的 hillshade 可用属性来自定义图层的外观
type 为 hillshading

map.addSource('dem', {
  type: 'raster-dem',
  url: 'mapbox://mapbox.mapbox-terrain-dem-v1'
});
map.addLayer({
  id: 'hillshading',
  source: 'dem',
  type: 'hillshade'
});

官方示例：示例

7. Heatmap layer 热力图图层

type 为 heatmap 样式图层渲染一系列颜色以表示区域中点的密度
要添加热度地图层，您需要首先添加包含点数据的矢量或 GeoJSON 源

map.addLayer({
  id: 'earthquakes-heat',
  type: 'heatmap',
  source: 'earthquakes',
  paint: {
    'heatmap-color': [
      'interpolate',
      ['linear'],
      ['heatmap-density'],
      0,
      'rgba(33,102,172,0)',
      0.2,
      'rgb(103,169,207)',
      0.4,
      'rgb(209,229,240)',
      0.6,
      'rgb(253,219,199)',
      0.8,
      'rgb(239,138,98)',
      1,
      'rgb(178,24,43)'
    ],
    'heatmap-radius': 20
  }
});

官方示例：示例

8. Raster layer 栅格图层

raster 样式图层用于在地图上渲染栅格切片

map.addLayer({
  id: 'radar-layer',
  type: 'raster',
  source: 'radar',
  paint: {
    'raster-fade-duration': 0
  }
});

官方示例：https://docs.mapbox.com/mapbox-gl-js/example/image-on-a-map/

9. Background layer 背景图层

background 样式图层将覆盖整个地图

map.addLayer({
  type: 'background',
  paint: {
    'background-color': 'blue',
    'background-opacity': 0.3
  }
});

3.6 Styling your layers 设置图层样式

1. 使用表达式：
在 Mapbox GL JS 中，可以将任何布局属性、绘制属性或过滤器的值指定为表达式。
表达式定义如何使用逻辑、数学、字符串或颜色运算组合一个或多个特征属性值或当前缩放级别，以生成适当的样式属性值或筛选决策。

2. 表达式语法：

["expression_name", argument_0, argument_1]

表达式是一个数组（Array），第一个元素是操作符（如 “get”、“match”），后续元素是参数或子表达式。

3. 表达式类型：

数据访问：

获取要素的属性值： ["get", "property_name"]

"fill-color": ["get", "type"] // 根据要素的 `type` 属性设置颜色

条件判断

["match", input, key1, value1, key2, value2, ..., fallback]：匹配输入值与键，返回对应的值

"fill-color": [
  "match",
  ["get", "type"],
  "park", "#00ff00",
  "school", "#0000ff",
  "#cccccc" // 默认颜色
]

["case", condition1, value1, condition2, value2, ..., fallback]：按顺序判断条件，返回第一个满足条件的值

"fill-color": [
  "case",
  [">=", ["get", "population"], 100], "red",
  [">=", ["get", "population"], 400], "orange",
  "green"
]

数学运算
逻辑运算
字符串操作
- 拼接字符串：["concat", "text1", ["get", "property"], ...]

4. 实际应用
示例 1：根据属性值设置颜色

{
  "id": "points-layer",
  "type": "circle",
  "paint": {
    "circle-color": [
      "match",
      ["get", "type"], // 获取属性值
      "park", "#00ff00", // type 为 "park" 时绿色
      "school", "#0000ff", // type 为 "school" 时蓝色
      "hospital", "#ff0000", // type 为 "hospital" 时红色
      "#cccccc" // 默认颜色
    ],
    "circle-radius": 5
  }
}

示例 2：根据缩放级别调整线宽

{
  "id": "road-layer",
  "type": "line",
  "paint": {
    "line-width": [
      "interpolate",
      ["exponential", 1.5],
      ["zoom"],
      0, 1,
      14, 5
    ]
  }
}

4. 用户交互

4.1 手势和事件

启用和禁用地图交互：

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    center: [0, 0],
    zoom: 2,
    
    dragPan: true, // 启用或禁用拖动平移
    scrollZoom: false, // 关闭滚动缩放
    dragRotate: true, // 启用拖动旋转
    boxZoom: true, // Enable box zoom
    keyboard: true, // 启用键盘控制
    touchZoomRotate: true // 启用触摸缩放和旋转
});

也可通过代码控制：

// 拖动平移
map.dragPan.disable()
map.dragPan.enable()

// 滚动缩放
map.scrollZoom.disable();
map.scrollZoom.enable();

// 拖动旋转
map.dragRotate.disable()
map.dragRotate.enable()

4.2 交互事件

所有事件：map-events

常见的事件类型：

click 当用户单击地图时触发
move 在平移或缩放地图时连续触发
moveend 在平移移动完成时触发
zoom 在地图缩放时持续触发
zoomend 缩放完成后触发
rotate 在地图旋转时持续触发
rotateend 旋转完成后触发
pitch 在pitch发生改变时触发

使用示例：

map.on('move', () => {
    console.log('Map is moving');
});

map.on('click', (e) => {
    console.log(`Clicked at: ${e.lngLat.lng}, ${e.lngLat.lat}`);
});

4.3 外部交互

缩放控制：使用 zoomIn 和 zoomOut 方法控制地图：
示例：

const zoomInButton = document.getElementById('zoom-in');
zoomInButton.addEventListener('click', () => {
    map.zoomIn();
});

飞行相机： flyTo
可在用户单击重置按钮时将地图平滑过渡到新位置

 const zoomOutButton = document.getElementById('reset-map-view');
zoomOutButton.addEventListener('click', () => {
    map.flyTo({
        center: [0, 0],
        zoom: 2
    });
});