2ГИС MapGL можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. MapGL JS API рисует интерактивную карту, а Directions plugin строит и сразу отображает автомобильный или пешеходный маршрут. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.
На первом запуске легко перепутать ключ карты и ключ Directions, порядок координат или вызвать маршрут до создания экземпляра карты. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте страницу с картой Москвы, двумя метками, кнопкой построения и очисткой маршрута. Проверка: карта загружается, две точки видны, carRoute рисует линию, а повторный запуск сначала очищает старый маршрут.
создать mapgl.Map с center, zoom и key. Не расширяйте проект до первого успешного запуска.
обе координаты видны. Проверяйте значение, а не отсутствие ошибки.
После успеха добавьте третью точку и кнопку выбора типа маршрута. Так копирование станет практикой.
Как устроен учебный проект 2ГИС MapGL
MapGL создаёт карту, Marker показывает начало и конец, Directions получает тот же map и отдельный directionsApiKey, затем рисует путь между координатами. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.
| Этап | Действие | Проверяемый результат |
|---|---|---|
| Карта | создать mapgl.Map с center, zoom и key | подложка 2ГИС загружена |
| Точки | добавить Marker для старта и финиша | обе координаты видны |
| Маршрут | создать Directions с directionsApiKey | carRoute рисует оптимальный путь |
| Повтор | вызвать clear перед новым запросом | на карте остаётся одна актуальная линия |
Контрольные точки: карта, точки, маршрут и повтор. Следующий шаг начинается после совпадения с ожидаемым результатом.

От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.
Собираем рабочий пример шаг за шагом
Материал сверялся с официальной документацией 2 ноября 2026 года. Получите отдельные ключи MapGL и Directions, подключите официальные скрипты API и задайте контейнеру карты явную высоту. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.
const start = [37.6176, 55.7558]
const finish = [37.6487, 55.7416]
const map = new mapgl.Map('map', {
center: start,
zoom: 12,
key: window.MAPGL_KEY,
})
new mapgl.Marker(map, { coordinates: start, label: { text: 'Старт' } })
new mapgl.Marker(map, { coordinates: finish, label: { text: 'Финиш' } })
const directions = new mapgl.Directions(map, {
directionsApiKey: window.DIRECTIONS_KEY,
})
document.querySelector('#route').addEventListener('click', async () => {
const status = document.querySelector('#status')
status.textContent = 'Строим маршрут...'
try {
directions.clear()
await directions.carRoute({ points: [start, finish] })
status.textContent = 'Маршрут построен.'
} catch (error) {
console.error(error)
status.textContent = 'Не удалось построить маршрут. Проверьте ключи.'
}
})- После загрузки видны карта и две подписанные точки с координатами в порядке longitude, latitude.
- Кнопка строит одну линию маршрута, а ошибка API превращается в сообщение рядом с картой.
- Повторный запуск даёт тот же предсказуемый результат.
- Пустой ввод получает понятное сообщение вместо падения.
Главная функция принимает явный вход и возвращает результат, который можно проверить отдельно от интерфейса. Найдите в примере вход, проверку и место формирования результата.

Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.
Что происходит внутри и почему это работает
Координаты MapGL передаются в порядке долгота, широта. Directions plugin получает список точек и сам добавляет слои маршрута на существующую карту. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Ключи для клиентского API ограничивайте разрешёнными доменами в кабинете. Не используйте один секретный серверный ключ во фронтенде.
| Часть | За что отвечает | Что проверить |
|---|---|---|
| Map | рисует подложку и управляет камерой | контейнер имеет высоту и корректный key |
| Markers | показывают входные координаты | точки не перепутаны местами |
| Directions | запрашивает и рисует маршрут | ошибка Promise обработана |
Маршрут является результатом внешнего API, поэтому интерфейс должен иметь loading, success и error. Не считайте пустую карту доказательством отсутствия пути: сначала проверьте ключ, сеть и координаты. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.
Проверяем проект и добавляем свою функцию
Добавьте переключатель автомобильного и пешеходного маршрута, используя carRoute и pedestrianRoute для одного набора точек. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.
- Сохраните ожидаемый результат: карта загружается, две точки видны, carRoute рисует линию, а повторный запуск сначала очищает старый маршрут.
- Измените правило: добавьте третью точку и кнопку выбора типа маршрута. Сначала предскажите итог.
- Передайте граничное значение и убедитесь, что приложение не падает.
- Верните корректные данные и объясните роли трёх основных частей.
- подложка 2ГИС загружена
- обе координаты видны
- carRoute рисует оптимальный путь
- на карте остаётся одна актуальная линия
После изменения повторите основной и ошибочный сценарии, чтобы новое поведение не сломало исходный результат. Полезная правка проходит от нового ввода до видимого результата.

Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.
Что запомнить и куда двигаться дальше
Для портфолио вынесите координаты в форму, ограничьте число точек и добавьте доступный текстовый статус, который работает без цвета. Для закрепления откройте в статье про Яндекс Карты, в подсказках адреса DaData и в приложении погоды.
Как изучить тему в Кодике
Сначала разберите формат входных данных и одну функцию, затем подключайте внешний сервис или интерфейс. Сначала восстановите главную функцию и проверьте её на трёх значениях.
| Шаг | Что разобрать | Мини-проверка |
|---|---|---|
| 1. Основа | Массивы, DOM-события и async/await JavaScript | Объясните вход и выход функции. |
| 2. Инструмент | MapGL Map, Marker и Directions plugin | Повторите команду по памяти. |
| 3. Проект | Маршрут с loading, success и error | Проверьте два сценария. |
| 4. Рефакторинг | Форму координат, доменные ограничения ключей и UX карты | Разделите ввод, логику и вывод. |
Закрепите проект, восстановив ключевую функцию по памяти и добавив собственный граничный случай. Базовый синтаксис закрепите через курс JavaScript.
MapGL ждёт долготу, затем широту. Точка улетает в другую часть мира.
MapGL и Directions используют свои параметры доступа.
Карта загружена, но div имеет нулевой размер.
Пользователь видит вечную загрузку. Добавьте try/catch и статус.
Что получится в итоге

Финальный экран показывает результат, состояние операции и понятное сообщение об ошибке без раскрытия секретов.
В каком порядке передаются координаты?
Сначала долгота, затем широта: longitude, latitude.
Зачем вызывать directions.clear()?
Чтобы перед новым запросом удалить старые линии и не смешивать маршруты.
Что проверять первым, если 2ГИС MapGL не запускается?
Версию среды, текущую папку, команду запуска и первую строку ошибки.
Как понять, что проект 2ГИС MapGL работает?
Проверьте основной сценарий, неверный ввод, повторный запуск и один граничный случай.
Можно ли начать с готового кода?
Да. Добейтесь результата, измените одно правило и восстановите ключевую функцию без копирования.
Выберите одно улучшение и проведите его от ввода до результата.
Если не хватает основы, перейдите курс JavaScript, затем восстановите ключевую функцию без подсказки.