JavaScript SDK RC9

Подключение и типы

SDK поставляется как браузерный ES-модуль. Подключите https://cdn.mmapps.ru/sdk/1.0.0-rc.9/index.css, затем импортируйте нужные функции из https://cdn.mmapps.ru/sdk/1.0.0-rc.9/index.js. Готовая HTML-страница.

Точные типы поставляются вместе с выпуском: точка входа TypeScript, экспорты SDK. Ссылки на типы ниже относятся к той же версии. Обозначение ? в сигнатурах означает необязательный аргумент.

Клиент и сервисные запросы

createClient(options?) → GeoClient. Без параметров создаёт клиент бесплатной карты. Параметры ClientOptions: apiBaseUrl, apiKey, catalogUrl, fetch, timeoutMs.

import { createClient } from 'https://cdn.mmapps.ru/sdk/1.0.0-rc.9/index.js';

const geo = createClient({
  apiBaseUrl: 'https://mmapps.ru',
  apiKey: 'YOUR_BROWSER_KEY',
});
const operationKey = crypto.randomUUID();
const result = await geo.geocoder.search(
  { q: 'Примерная улица', limit: 5 },
  { operationKey },
);

apiBaseUrl — адрес API без пути, параметров и фрагмента. Для сервисных вызовов используйте HTTPS и браузерный ключ с нужными правами и разрешённым origin. YOUR_BROWSER_KEY — условное обозначение. Серверный ключ в SDK не передавайте.

OperationOptions содержит signal?: AbortSignal и operationKey?: string. Для повторов сохраняйте ключ и тело запроса; изменение данных — новая операция. Если ключ не задан, SDK создаёт его сам. Отмена ожидания через signal не доказывает, что запрос не успел выполниться.

usage передаёт operationId, requestId, chargedMicrorub, funding, retryAfter, stage. При наличии в ответе доступны quantity, freeUnits, paidUnits, meter. Суммы и количества передаются строками. Правила оплаты, типы клиента.

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

createMap(options) → Promise<GeoMap> и geo.createMap(options) → Promise<GeoMap>. После создания дождитесь map.ready.

У публичного basemap дополнительно возможны styleSha256, styleBytes, assetSizes. Для обычного подключения достаточно mapId. houseNumbers.minZoom принимает 0–20, sizeScale — 0,5–2; стандартные значения — 16 и 1. Настройки меняют существующие подписи, а не добавляют данные.

Координаты GeoPoint имеют вид {latitude, longitude}. checkedPoint(latitude, longitude) проверяет конечные числа и диапазоны WGS84. GeoJSON использует обратный порядок: [longitude, latitude]. Bounds — {west, south, east, north}, экранная точка — {x, y}.

Состояние и события карты

События указателя: click, dblclick, contextmenu, mousemove, mouseenter, mouseleave, pointerdown, pointerup, touchstart, touchend. События камеры: move, movestart, moveend, zoom, zoomend, rotate, pitch, resize, idle. Состояние: statechange, error, destroy.

Событие указателя содержит point, screen, objectId, originalEvent, stopPropagation() и preventDefault(). Типы карты и событий.

Для существующих интеграций сохранены setVisits(points), setMarkers(points), setTracks(tracks). Они принимают типы MapPoint и Track; при новом подключении используйте objects и createRouteOverlay. Типы совместимых методов.

Камера и жесты

transition задаёт duration и mode: 'ease', 'fly' или 'jump'. FitOptions содержит maxZoom, duration, padding (число или отступы по четырём сторонам), resetOrientation.

map.interactions.getState(), set(options), enable(), disable() управляют жестами. Параметры: dragPan, scrollZoom (boolean или 'cooperative'), doubleClickZoom, touchZoom, touchRotate, dragRotate, touchPitch, keyboard.

Объекты и коллекции

map.objects.add(object) возвращает ObjectHandle. У каждого объекта обязательны уникальный id и kind.

Сокращённые методы принимают те же поля без kind. Общие параметры: label, properties, visible, selected, style, collection, zIndex. Стиль: color, fillColor, width, opacity, fillOpacity, radius, dash.

objects также предоставляет get(id), getAll(), remove(id), clear(), replace(objects), getBounds(ids?), toGeoJSON(ids?), importGeoJSON(value, {replace?, collection?}?). batch(changes) принимает записи {action: 'upsert', object} или {action: 'remove', id}.

Поддерживаемая GeoJSON-геометрия: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection. Используйте строковые ID объектов, JSON-совместимые properties и корректный порядок координат.

objects.createCollection(id) создаёт группу. Коллекция имеет id, add, get, getAll, remove, clear, setVisible, setFilter(predicate | null), setStyle, getBounds, on, once, destroy. События: add, change, remove, statechange, destroy.

Маркеры, карточки и подсказки

ObjectHandle содержит id, getData(), update(change), setVisible(boolean), setSelected(boolean), getBounds(), getPoint(), remove(), on(), once(), popup и tooltip. Через update нельзя менять id и kind.

События объекта: click, dblclick, contextmenu, mouseenter, mouseleave, dragstart, drag, dragend, change, remove, popupopen, popupclose.

popup и tooltip имеют одинаковые методы: open(content), update(content), load(loader), close(), isOpen(). content — {text?, element?, offset?, maxWidth?}. В load передаётся функция (signal) => Promise<PopupContent>; используйте сигнал для отмены своего запроса.

const marker = map.objects.addMarker({
  id: 'example',
  point: { latitude: 55.75, longitude: 37.61 },
  label: 'Наша точка',
});
marker.popup.open({ text: 'Карточка места', maxWidth: 270 });
marker.update({ selected: true });

Для собственного маркера renderer(data) возвращает новый HTMLElement, объект {element, anchor?, offset?, update?, destroy?} или null для стандартного вида. Создавайте отдельный DOM-элемент для каждого маркера. Пользовательский текст вставляйте через textContent.

Кластеры

map.clusters.create(id, options?) → ClusterGroup; доступны также get(id), getAll(), clear(). Параметры группы: radius, maxZoom, minPoints, zoomOnClick, style. Это группировка Ваших точек в браузере, не адресный поиск.

const group = map.clusters.create('places', { zoomOnClick: true });
group.setPoints([
  { id: 'a', point: { latitude: 55.75, longitude: 37.61 } },
  { id: 'b', point: { latitude: 55.76, longitude: 37.62 } },
]);

ClusterPoint содержит id, point, необязательные label, properties, selected. ClusterSnapshot — {nodes, truncated, loading}. Узел имеет kind: 'cluster' с reference или kind: 'point' с исходной точкой. Reference принадлежит конкретной ревизии группы; после изменения данных получите новый, иначе возможен STALE_CLUSTER.

События: click, dblclick, contextmenu, mouseenter, mouseleave, change, destroy, error. Стиль: color, pointColor, selectedColor, textColor, clusterRadius, pointRadius, textSize, opacity, textFont. Для запросов узлов доступны signal, timeoutMs, у getChildren также limit, у expand — параметры перехода камеры.

Инструменты карты

map.controls.set(id, options) включает или настраивает встроенный инструмент; false выключает его. Общие параметры: position (top-left, top-right, bottom-left, bottom-right), visible, margin.

Геолокация использует разрешение браузера. positionOptions содержит enableHighAccuracy, timeout, maximumAge.

controls.add({id, element, position?, visible?, margin?, onAdd?, onRemove?}) добавляет свой инструмент. Также доступны get(id), getAll(), remove(id), clear().

ControlHandle: id, element, getState(), setPosition(), setVisible(), setMargin(), focus(), remove(), destroy(). Полные типы инструментов.

Поиск и выбор адреса

createSearchController({client, map?, filters?, language?, limit?, fitResults?}) создаёт контроллер. client — geo.geocoder или результат createGeocoder().

В выпуске SDK 1.0.0-rc.11 предусмотрен параметр mapContext: при наличии map он включён по умолчанию и передаёт снимок центра и области карты. mapContext: false оставляет намеренно глобальный поиск. Движение карты само по себе запросов не делает; текстовый Enter использует тот же поиск подсказок, не добавляя геокодинг. Для этой возможности требуется подключить именно этот выпуск после его публикации.

filters поддерживает country_codes и ссылки region, locality, street. События контроллера: change, confirm, response, error. Фазы SearchState: idle, loading, candidates, not_found, needs_context, outside_coverage, selected, error, destroyed.

SearchSelection содержит candidate, ref, point, alternative, queryPoint, userConfirmed: true. Выбор не вызывает новый HTTP-запрос. point может быть null; не создавайте из него маршрут.

map.controls.addSearch(options) размещает поиск на карте. Передайте либо controller, либо client с настройками filters, language, limit, fitResults. Общие настройки: размещение, debounceMs, placeholder, width, onSelect, onRoute, onShare. Результат SearchMapControl дополнительно имеет controller, dockElement, openSelection(), closeSelection().

Для своей вёрстки используйте attachSearchControl({controller, element, dockElement?, debounceMs?, placeholder?, onSelect?, onRoute?, onShare?}). Результат: element, dockElement, focus(), setVisible(), openSelection(), closeSelection(), destroy(). Самостоятельно созданный контроллер освобождайте отдельно.

onRoute(selection) и onShare(selection) выполняют действия Вашего приложения; само открытие карточки не рассчитывает маршрут. Пример подключения, типы поиска.

Свой обработчик запросов геокодера

createGeocoder({baseUrl, fetch?, timeoutMs?, signal?, credentials?, paths?, requestHeaders?}) → Geocoder нужен для подключения к своему backend. Методы: search, geocode, reverse, resolve.

paths задаёт пути этих четырёх операций, requestHeaders(operation, options?) — заголовки. credentials принимает 'omit' или 'same-origin'. Для прямого подключения к API Ммаппс используйте createClient с браузерным ключом. В resolve первый аргумент — сам ref, а не {ref}; дополнительные параметры — language, signal, operationKey.

Расчёт и отображение маршрута

geo.routes.calculate({start, end, via?, profile?}, options?) принимает GeoPoint, профиль — 'car'. geo.routes.geocode() принимает в каждой позиции {point}, {ref} или {q}. Текст требует подтверждения. Запросы и результаты.

routeView(response) возвращает {track, input, snapped, distanceM, durationS, routingVersion}. track может быть null. geocodedRouteView(response) возвращает {route, waypoints}, где каждый waypoint содержит index, point, candidates. routeCandidates(value) извлекает кандидатов из результата геокодинга. Эти функции работают с готовым ответом и не отправляют запросов.

import { createRouteOverlay } from 'https://cdn.mmapps.ru/sdk/1.0.0-rc.9/index.js';

const overlay = createRouteOverlay(map);
overlay.set(routeResponse); // Ответ calculate() или geocode().
overlay.fit();
// overlay.clear();
// overlay.destroy();

createRouteOverlay(map) создаёт слой. set(response | null), clear(), fit(), destroy() управляют им. Результат no_route не превращается в прямую линию.

Редактор маршрута

attachRouteControl(map, service, {recalculate?}?) → RouteControl. service должен предоставлять calculate, например geo.routes. recalculate: 'on-change' пересчитывает после завершённых изменений пользователем; 'manual' требует явного расчёта.

RouteStop — {point, label?}; в списке остановок допускаются незаполненные null. События: change, result, error. Фазы: editing, loading, route, no_route, error. Типы редактора.

Матрица расстояний

geo.routes.matrix({sources, targets, profile?}, options?) → Promise<MatrixResponse> рассчитывает пары координат. geo.routes.matrixGeocode() использует {point}, {ref} или {q} в списках. Профиль — 'car', параметры операции — signal, operationKey.

const operationKey = crypto.randomUUID();
const matrix = await geo.routes.matrix({
  sources: [{ latitude: 55.75, longitude: 37.61 }],
  targets: [{ latitude: 55.76, longitude: 37.62 }],
  profile: 'car',
}, { operationKey });
const cell = matrix.cells[0][0];
if (cell.status === 'ok') {
  // cell.distance_m — метры; cell.duration_s — секунды.
}

matrixView(value, expected?) проверяет готовый ответ, необязательный expected — исходный MatrixRequest. geocodedMatrixView(value, expected) принимает обязательный GeocodeMatrixRequest. Обе функции возвращают проверенный ответ и не вызывают API.

До подтверждения текстовых адресов matrix равна null. Для no_route расстояние и время равны null. Ограничения, тариф и подтверждение адресов, типы матрицы.

Таймлайн

createTimeline(map, {data, time?, markerRenderer?, observationInterpolation?}) → Timeline отображает временные данные Вашего приложения. Время — Unix в миллисекундах UTC.

import { createTimeline, attachTimelineControl } from 'https://cdn.mmapps.ru/sdk/1.0.0-rc.9/index.js';

const from = Date.UTC(2026, 0, 1, 9);
const to = from + 60 * 60 * 1000;
const timeline = createTimeline(map, {
  data: {
    version: 1,
    range: { from, to },
    referenceTime: from,
    entities: [{
      id: 'example',
      label: 'Наш объект',
      locations: [{
        id: 'stop', from, to, basis: 'planned',
        point: { latitude: 55.75, longitude: 37.61 },
      }],
    }],
  },
  time: from,
});
const control = attachTimelineControl(map, timeline);
// При удалении: control.destroy(); timeline.destroy();

TimelineData: version: 1, range: {from, to}, referenceTime, entities. Каждый объект имеет id, необязательные label, locations, observations. Местоположение: {id, from, to?, point, basis, label?}, где basis — 'reported' или 'planned'; интервал [from, to). point: null означает неизвестную координату. Наблюдение: {at, point, accuracyM?}.

Без включённой интерполяции промежутки между наблюдениями остаются неизвестными. observationInterpolation: {maxGapMs} явно разрешает оценку между соседними измерениями; maxGapMs — 1–600 000 мс. В TemporalPosition.source различаются location, observation, interpolated, unknown.

Выбор для плана — {entityId, basis, intermediate: 'observations' / 'none', from?, to?}. Для prepareRoutes дополнительно обязательны maxRequests, operationKeyPrefix, необязателен signal. Сохраняйте префикс для повторов. Результат содержит requested, reused, prepared, noRoute. Подготовка вызывает платный расчёт маршрута; перемотка и воспроизведение — локальные действия.

attachTimelineControl(mapOrElement, timeline, {order?, onPrepareRoutes?}?) создаёт панель. Она предоставляет element, setVisible(boolean), destroy(). onPrepareRoutes({entityId, basis}) открывает Ваш интерфейс подготовки; само воспроизведение его не вызывает. Все типы таймлайна.

Панели и меню точки

map.layout.mount({id, element, slot: 'top' / 'bottom', order?, visible?}) размещает панель в общем стеке. Меньший order — ближе к центру карты. map.layout.reserve({id, element, edge, gap?}) резервирует место под уже размещённую панель приложения; edge — top, bottom, left, right.

Оба метода возвращают LayoutHandle: element, setVisible(), remove(), destroy(). layout.getInsets() читает отступы, layout.onChange(callback) подписывается на их изменение и возвращает отписку.

attachContextMenu(map, {element, search?, routes?, onError?}) подключает меню к контейнеру карты. Передайте существующий SearchController и RouteControl. Меню открывается правой кнопкой мыши или с клавиатуры; действия — «Что здесь?», «Маршрут отсюда», «Маршрут сюда». Недоступные сервисы не выполняются.

MapContextMenu содержит element, open(point, screen?), close(), isOpen(), destroy(). Открытие меню бесплатно. Только выбор действия запускает обратный поиск или выбор точки маршрута с учётом режима пересчёта.

Готовый виджет

createMapWidget(options) → Promise<MapWidget> объединяет инструменты карты. Используйте параметры карты, кроме editable, и добавьте нужные сервисы:

import { createClient, createMapWidget } from 'https://cdn.mmapps.ru/sdk/1.0.0-rc.9/index.js';

const geo = createClient({ apiBaseUrl: 'https://mmapps.ru', apiKey: 'YOUR_BROWSER_KEY' });
const widget = await createMapWidget({
  element: document.getElementById('map'),
  mapId: 'ru',
  services: { geocoder: geo.geocoder, routes: geo.routes },
  search: { placeholder: 'Адрес или координаты' },
  routing: { recalculate: 'manual' },
});
await widget.ready;
// При удалении: widget.destroy(); geo.destroy();

Параметры виджета: services, search (настройки поиска или false), routing (boolean или настройки редактора), controls (без search), timeline, timelineControl, contextMenu, onSelect, onRoute, onShare, onError. Меню точки по умолчанию включено, contextMenu: false отключает его.

Виджет предоставляет map, ready, search, routes, timeline, contextMenu; необязательные инструменты могут быть null. setServices(services) меняет сервисы, сохраняя публичную карту и внешние объекты. destroy() освобождает виджет. Типы виджета.

Ошибки и завершение работы

MapSDKError содержит code, httpStatus, retryable, requestId, operationId, retryAfter, stage. GeocoderError дополнительно предоставляет status. Используйте эти поля для сообщения об ошибке и решения о повторе.

Локальные коды включают INVALID_ARGUMENT, DESTROYED, ABORTED, DEADLINE_EXCEEDED, RESOURCE_UNAVAILABLE, WORKER_CONFLICT, RENDERER_ERROR, INVALID_RESPONSE, STALE_CLUSTER, BUSY, RANDOM_SOURCE_UNAVAILABLE. Коды сервисного API описаны в разделе ошибок.

Храните функции отписки и возвращаемые handles. При размонтировании удаляйте самостоятельно созданные панели и контроллеры, затем карту и клиент. destroy() карты и виджета освобождает принадлежащие им ресурсы; внешний API-клиент освобождается отдельно. Не создавайте новые экземпляры при каждом обновлении состояния компонента.