README и примеры

README-файл является центральной точкой документации любого проекта на базе Mapbox GL JS. Именно он обеспечивает первое знакомство с библиотекой, демонстрирует базовые возможности, содержит инструкции по запуску и показывает минимальные рабочие примеры. Для проектов, использующих интерактивные карты, качество README напрямую влияет на скорость освоения API и эффективность внедрения решений.

Грамотно оформленный README обычно включает:

  • краткое описание проекта;
  • перечень возможностей;
  • требования к окружению;
  • инструкции по установке;
  • примеры использования;
  • описание конфигурации;
  • ссылки на дополнительную документацию.

Минимальный пример карты

Наиболее распространённый пример демонстрирует создание карты с использованием стандартного стиля.

HTML

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Mapbox GL JS Example</title>

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

    <style>
        body {
            margin: 0;
        }

        #map {
            width: 100vw;
            height: 100vh;
        }
    </style>
</head>
<body>

<div id="map"></div>

<script src="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js"></script>

<script>
    mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN';

    const map = new mapboxgl.Map({
        container: 'map',
        style: 'mapbox://styles/mapbox/streets-v12',
        center: [37.6176, 55.7558],
        zoom: 10
    });
</script>

</body>
</html>

Ключевые параметры

Параметр Назначение
container DOM-элемент для отображения карты
style Стиль визуализации карты
center Координаты центра карты
zoom Начальный масштаб

Пример для npm-проекта

При использовании современных сборщиков приложение обычно подключает Mapbox GL JS как зависимость.

Установка

npm install mapbox-gl

Импорт библиотеки

import mapboxgl from 'mapbox-gl';

mapboxgl.accessToken = process.env.MAPBOX_TOKEN;

Создание карты

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/light-v11',
    center: [30.3141, 59.9386],
    zoom: 11
});

Пример подключения собственного контейнера

Размер карты полностью определяется размерами контейнера.

HTML

<div id="map"></div>

CSS

#map {
    width: 800px;
    height: 500px;
    border: 1px solid #ccc;
}

JavaScript

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12'
});

Mapbox GL JS автоматически адаптирует область рендеринга под размеры контейнера.

Пример добавления навигационных элементов

Для управления масштабом и вращением используется класс NavigationControl.

map.addControl(
    new mapboxgl.NavigationControl()
);

В результате на карте появляются:

  • кнопка увеличения масштаба;
  • кнопка уменьшения масштаба;
  • компас для изменения ориентации карты.

Размещение элемента управления:

map.addControl(
    new mapboxgl.NavigationControl(),
    'top-right'
);

Доступные позиции:

top-left
top-right
bottom-left
bottom-right

Пример добавления маркера

Создание маркера

new mapboxgl.Marker()
    .setLngLat([37.6176, 55.7558])
    .addTo(map);

Цветной маркер

new mapboxgl.Marker({
    color: '#ff0000'
})
.setLngLat([37.6176, 55.7558])
.addTo(map);

Перетаскиваемый маркер

new mapboxgl.Marker({
    draggable: true
})
.setLngLat([37.6176, 55.7558])
.addTo(map);

Пример всплывающего окна

Всплывающие окна используются для отображения дополнительной информации.

const popup = new mapboxgl.Popup()
    .setHTML(`
        <h3>Москва</h3>
        <p>Столица России</p>
    `);

Привязка к маркеру:

new mapboxgl.Marker()
    .setLngLat([37.6176, 55.7558])
    .setPopup(popup)
    .addTo(map);

После щелчка по маркеру откроется окно с содержимым.

Пример обработки событий

Mapbox GL JS предоставляет развитую событийную модель.

Загрузка карты

map.on('load', () => {
    console.log('Map loaded');
});

Щелчок по карте

map.on('click', (event) => {
    console.log(event.lngLat);
});

Изменение масштаба

map.on('zoom', () => {
    console.log(map.getZoom());
});

Перемещение карты

map.on('move', () => {
    console.log(map.getCenter());
});

Пример получения координат курсора

map.on('mousemove', (event) => {
    console.log(
        event.lngLat.lng,
        event.lngLat.lat
    );
});

Подобный механизм часто используется при разработке GIS-систем и аналитических панелей.

Пример смены стиля карты

Mapbox предоставляет несколько готовых стилей.

Streets

style: 'mapbox://styles/mapbox/streets-v12'

Outdoors

style: 'mapbox://styles/mapbox/outdoors-v12'

Light

style: 'mapbox://styles/mapbox/light-v11'

Dark

style: 'mapbox://styles/mapbox/dark-v11'

Satellite

style: 'mapbox://styles/mapbox/satellite-v9'

Переключение стиля

map.setStyle(
    'mapbox://styles/mapbox/dark-v11'
);

Пример геолокации пользователя

Mapbox GL JS содержит готовый элемент управления геолокацией.

map.addControl(
    new mapboxgl.GeolocateControl({
        positionOptions: {
            enableHighAccuracy: true
        },
        trackUserLocation: true
    })
);

После активации контроллер:

  • получает текущие координаты;
  • отображает положение пользователя;
  • может автоматически отслеживать перемещения.

Пример полноэкранного режима

map.addControl(
    new mapboxgl.FullscreenControl()
);

Кнопка позволяет развернуть карту на весь экран браузера.

Пример масштабной линейки

map.addControl(
    new mapboxgl.ScaleControl()
);

Настройка единиц измерения:

map.addControl(
    new mapboxgl.ScaleControl({
        unit: 'metric'
    })
);

Поддерживаются значения:

metric
imperial
nautical

Пример источника GeoJSON

GeoJSON является основным форматом пространственных данных в Mapbox GL JS.

Добавление источника

map.on('load', () => {
    map.addSource('cities', {
        type: 'geojson',
        data: {
            type: 'FeatureCollection',
            features: [
                {
                    type: 'Feature',
                    geometry: {
                        type: 'Point',
                        coordinates: [37.6176, 55.7558]
                    }
                }
            ]
        }
    });
});

Пример отображения точек

После добавления источника создаётся слой.

map.addLayer({
    id: 'cities-layer',
    type: 'circle',
    source: 'cities',
    paint: {
        'circle-radius': 8,
        'circle-color': '#007cbf'
    }
});

Параметры визуализации определяются в секции paint.

Пример отображения линии

GeoJSON

map.addSource('route', {
    type: 'geojson',
    data: routeData
});

Layer

map.addLayer({
    id: 'route-line',
    type: 'line',
    source: 'route',
    paint: {
        'line-color': '#ff0000',
        'line-width': 4
    }
});

Подобный подход используется для отображения:

  • маршрутов;
  • дорог;
  • границ;
  • инженерных сетей.

Пример отображения полигона

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

Полигональные слои применяются для визуализации:

  • административных границ;
  • земельных участков;
  • зон покрытия;
  • тематических областей.

Пример всплывающей информации по объекту

map.on('click', 'cities-layer', (event) => {

    const feature = event.features[0];

    new mapboxgl.Popup()
        .setLngLat(feature.geometry.coordinates)
        .setHTML(`
            <h3>${feature.properties.name}</h3>
        `)
        .addTo(map);

});

Использование свойств объекта позволяет динамически формировать содержимое окна.

Пример фильтрации объектов

map.setFilter(
    'cities-layer',
    ['==', 'country', 'Kazakhstan']
);

Фильтр применяется без повторной загрузки данных.

Другой пример:

map.setFilter(
    'cities-layer',
    ['>', 'population', 1000000]
);

Пример изменения данных на лету

const source = map.getSource('cities');

source.setData(newGeoJson);

Метод позволяет обновлять карту в режиме реального времени.

Типичные сценарии:

  • мониторинг транспорта;
  • GPS-трекинг;
  • телеметрия;
  • диспетчерские системы.

Пример анимации перемещения

Плавное перемещение камеры выполняется через метод flyTo.

map.flyTo({
    center: [76.9286, 43.2389],
    zoom: 12,
    speed: 1.2
});

Дополнительные параметры:

map.flyTo({
    center: [76.9286, 43.2389],
    zoom: 12,
    bearing: 45,
    pitch: 60,
    duration: 5000
});

Настраиваются:

  • направление камеры;
  • наклон;
  • продолжительность анимации;
  • скорость движения.

Пример управления камерой

Изменение центра

map.setCenter([37.6176, 55.7558]);

Изменение масштаба

map.setZoom(12);

Изменение наклона

map.setPitch(60);

Изменение поворота

map.setBearing(90);

Пример получения состояния карты

Центр

const center = map.getCenter();

Масштаб

const zoom = map.getZoom();

Наклон

const pitch = map.getPitch();

Поворот

const bearing = map.getBearing();

Такие методы часто используются при сохранении пользовательского состояния интерфейса.

Пример структуры README для проекта на Mapbox GL JS

# Project Name

## Description

Описание проекта.

## Features

- Interactive map
- Markers
- GeoJSON support
- Custom styles

## Installation

npm install

## Configuration

MAPBOX_TOKEN=your_token

## Usage

npm run dev

## Examples

Примеры использования.

## API

Описание методов.

## License

MIT

Хорошо организованный README должен содержать полностью рабочие фрагменты кода, минимальный путь запуска проекта, примеры основных сценариев использования Mapbox GL JS и демонстрацию наиболее востребованных возможностей библиотеки: работу со слоями, источниками данных, событиями, элементами управления, анимацией камеры и визуализацией пространственных объектов.

Оглавление