SDK и API — обзор

Справочник по @evamaps/sdk. Всё, что не описано здесь, может измениться без предупреждения.

Статусы в таблицах: ✅ есть · 🔜 скоро · ⏳ позже.

Главное

• Координаты везде [lng, lat] (долгота, широта — как в GeoJSON) или объект {lng, lat}.
• Методы возвращают this, их можно вызывать цепочкой. Событие приходит объектом с lngLat, point и originalEvent.
• Балун — это Popup.
• HTML из строк не разбирается: текст задаётся через setText, своя разметка — DOM-узлом через setContent(node).
• Подпись © OpenStreetMap contributors · © EvaMaps видна всегда, см. «Атрибуция».
• Сборка для <script> добавляет один объект window.EvaMaps, сборка для npm — ничего.
• Зум в покое целый (zoomSnap: 1), чтобы подписи на карте были чёткими.
• Во встраиваниях колесо мыши масштабирует карту только с Ctrl, чтобы не мешать прокрутке страницы.

Шкала зума — как у OSM (тайл 256 px): зум 0 — весь мир умещается в 256 px.

Установка

Одним <script> (CDN)

<link rel="stylesheet" href="https://evamaps.ru/sdk/1/evamaps.css">
<script src="https://evamaps.ru/sdk/1/evamaps.js"></script>

IIFE-сборка кладёт единственный глобальный объект window.EvaMaps. В нём — create(), классы (Map, Marker, Popup, …) и фабрики без new (EvaMaps.marker(...), EvaMaps.popup(), …).

Из npm (ESM)

pnpm add @evamaps/sdk

import { create, Marker, Popup } from '@evamaps/sdk';
import '@evamaps/sdk/style.css';

В ESM-сборке фабрики (marker(), popup(), …) тоже экспортируются — но обычно проще использовать классы напрямую (new Marker(...)).

EvaMaps.create() ✅

Самый быстрый способ получить карту: create(container, options) — тонкая обёртка над new Map(...) + TileLayer с нашими тайлами, темой, атрибуцией и контролами по умолчанию.

const map = create('map', { center: [37.6173, 55.7558], zoom: 12, theme: 'light' });

Опция	Тип	По умолчанию
center	LngLatLike	[37.6173, 55.7558]	Москва
zoom	number	11
theme	'light' | 'dark' | 'gray'	'light'	Тема подложки
key	string	—	Ключ проекта, необязателен
tilesUrl	string	https://evamaps.ru/v1/{theme}/{z}/{x}/{y}{r}.png	Свой сервер тайлов (коробка, разработка)
minZoom / maxZoom	number	0 / 19
zoomSnap	number	1	См. «Map»
zoomControl	boolean	true	Кнопки +/−
scaleControl	boolean	true	Линейка
cooperative	boolean	false	Кооперативные жесты, см. «Map»
retina	boolean	true	⏳ Тайлы @2x на экранах с DPR ≥ 1.5 — опция принимается ради совместимости API, пока ни на что не влияет

Также в EvaMaps: marker(), popup(), polyline(), polygon(), circle(), geoJSON(), cluster() — фабрики для IIFE-сборки. EvaMaps.version — строка версии SDK.

Дальше по справочнику

• Map — опции, методы вида, слои, события карты
• Слои — TileLayer, Marker, Popup, фигуры, GeoJSONLayer, ClusterLayer
• Контролы — зум, линейка, атрибуция
• События — все события карты, меток и кластеров в одном месте
• Типы — LngLat, LngLatBounds, Point и другие
• Примеры — живые карты с кодом рядом, который можно скопировать