Общие сведения

Пространство имён

Все компоненты JS API попадают в единое пространство имен ymaps3 и доступны только в нём.

Имена компонентов

Имя любого компонента JS API удовлетворяет двум условиям:

  • начинается с префикса YMap;
  • написано в стиле CamelCase.

Примеры: YMap, YMapMarker, YMapListener.

Объекты карты

Название

Описание

Представление в API

Карта

Корневой объект, который координирует свои составляющие.

Класс YMap

Слой

Объект для отображения данных.

Классы с постфиксом Layer

Источник данных

Объект для загрузки данных, передает их для отображения в слои.

Классы с постфиксом DataSource

Геообъект

Полигон, линия, маркер.

Класс YMapFeature

Маркер

Элемент карты с DOM-содержимым, обертка над YMapFeature.

Класс YMapMarker

Визуальные элементы

Объекты, которые используются для управления состоянием карты: кнопка изменения масштаба, кнопка геолокации и т.п.

Классы с постфиксом Control

Утилиты

Вспомогательные объекты для работы с API. Например, YMapListener отвечает за подписку на события карты.

Класс YMapListener и др.

Иерархия объектов

Некоторые объекты могут содержать внутренние узлы-потомки, а некоторые не могут. Например, YMap может содержать YMapTileDataSource, а последний уже не может.

Карта

YMap — корневой элемент в иерархии. Чтобы его инициализировать, в конструктор объекта нужно передать:

<!-- Создайте контейнер для карты -->
<div id="root"></div>

const {YMap} = ymaps3;

// Инициализируйте карту
const map = new YMap(

  // Передайте ссылку на HTMLElement контейнера
  document.getElementById('root'),

  // Передайте параметры инициализации карты
  {
    location: {
      zoom: 10,
      center: [25.229762, 55.289311]
    }
  }
);

Все объекты JS API инициализируются по своим правилам, но на карту добавляются с помощью метода addChild(), вызванного у экземпляра карты. Удалить объекты можно симметричным методом removeChild():

const {YMap, YMapLayer} = ymaps3;

// Инициализируйте карту
const map = new YMap(...);

// Инициализируйте слой
const layer = new YMapLayer(...);

// Добавьте этот слой на карту
map.addChild(layer);

Подробнее о YMap.

Слой

Слой — это визуальный компонент, который отвечает за отрисовку на карте каких-то объектов. Например, слой маркеров отображает точки на карте, а слой тайлов — саму географическую карту.

Карта может содержать произвольное количество слоев, API вас не ограничивает. Например, вы можете добавить слой, на котором будут отображены картинки с облаками, разместить под ним тайловый слой, а между ними добавить слой пробок.

Внимание

По умолчанию карта отображает слои в порядке добавления.
Вы можете управлять порядком слоёв с помощью параметра zIndex.

Подробнее о YMapLayer.

Источник данных

Для отображения слоя необходим источник данных. В JS API источниками данных являются объекты с постфиксом DataSource. Например, YMapTileDataSource — объект для загрузки тайлов растровой или векторной карты.

К примеру, вы хотите отобразить на карте тайлы, полученные с сайта https://sitename.com:

const {YMap, YMapTileDataSource, YMapLayer} = ymaps3;

// Инициализируйте карту
const map = new YMap({...});

// Инициализируйте источник данных
const tileDataSource = new YMapTileDataSource({
  id: 'someSource',
  raster: {
    type: 'someType',
    fetchTile: 'https://sitename.com/?x={{x}}&y={{y}}&z={{z}}&scale={{scale}}'
  }
});

// Добавьте источник данных на карту
map.addChild(tileDataSource);

// Создайте слой с полученными данными
const layer = new YMapLayer({
  zIndex: 1,
  source: 'someSource',
  type: 'someType'
});

// Добавьте этот слой на карту
map.addChild(layer);

Примечание

Для связи источника данных и слоя используется текстовый идентификатор. Будьте внимательны, идентификатор для источника данных задается в поле id, а при передаче в слой используется поле source.

Слой с источником данных

В JS API есть несколько слоёв, для которых источники данных уже настроены.

  • YMapDefaultFeaturesLayer — добавляет на карту источник данных и слой геообъектов (полигоны, линии, точки, метки);
  • YMapDefaultSchemeLayer — добавляет на карту источник данных и слой схемы карт:
    • type: 'ground' — вся схема в растровой версии, слой земли в векторной версии;
    • type: 'buildings' — слой строений в векторной версии;
    • type: 'icons' — слой иконок в векторной версии;
    • type: 'labels' — слой подписей в векторной версии.

Например, этот код добавит на карту все слои типа "схема" со всеми источниками данных:

map.addChild(new YMapDefaultSchemeLayer({theme: 'light'}));

Примечание

В этом примере конструктор слоя получает на вход только цветовую тему, остальные параметры используются по умолчанию из YMapDefaultSchemeLayer.defaultProps

Вы можете сделать всё то же самое, что в примере выше, только вручную:

// Сначала добавьте на карту невидимый слой.
// Он скрыт, потому что используется только для загрузки данных.
map.addChild(new YMapDefaultSchemeLayer({theme: 'light', visible: false, source: 'scheme'}));

// Затем добавьте на карту несколько слоёв, указав для каждого из них,
// какие данные из YMapDefaultSchemeLayer отображать.
map.addChild(new YMapLayer({zIndex: 1, source: 'scheme', type: 'ground'}))
map.addChild(new YMapLayer({zIndex: 2, source: 'scheme', type: 'labels'}))
map.addChild(new YMapLayer({zIndex: 3, source: 'scheme', type: 'buildings'}))
map.addChild(new YMapLayer({zIndex: 4, source: 'scheme', type: 'icons'}))

Маркер

Маркер — DOM-элемент с привязкой к координатам. Маркеры можно перетаскивать и настраивать их внешний вид с помощью HTML-верстки.

const {YMap, YMapDefaultSchemeLayer, YMapDefaultFeaturesLayer, YMapMarker} = ymaps3;

// Инициализируйте карту
const map = new YMap({...});

// Добавьте слой с дорогами и зданиями
map.addChild(new YMapDefaultSchemeLayer());

// Добавьте слой для маркеров
map.addChild(new YMapDefaultFeaturesLayer());

// Создайте DOM-элемент для содержимого маркера.
// Важно это сделать до инициализации маркера!
// Элемент можно создавать пустым. Добавить HTML-разметку внутрь можно после инициализации маркера.
const content = document.createElement('section');

// Инициализируйте маркер
const marker = new YMapMarker(
  {
    coordinates: [25.229762, 55.289311],
    draggable: true
  },
  content
);

// Добавьте маркер на карту
map.addChild(marker);

// Добавьте произвольную HTML-разметку внутрь содержимого маркера
content.innerHTML = '<h1>Этот заголовок можно перетаскивать</h1>';

Подробнее о YMapMarker.

Параметры инициализации

Параметры, передаваемые объектам при инициализации, могут быть обязательными и опциональными. Например, у компонента YMap поле location обязательное, а behaviors — нет.

const {YMap} = ymaps3;

const map = new YMap(document.getElementById('root'), {
  location: {
    zoom: 10,
    center: [25.229762, 55.289311]
  },
  behaviors: ['drag', 'scrollZoom', 'pinchZoom', 'dblClick']
});

Подробнее о параметрах инициализации каждого компонента.

Строгий режим

В JS API можно включить строгий режим для отслеживания ошибок в коде. Используйте глобальную опцию strictMode:

ymaps3.strictMode = true;

В строгом режиме JS API проверяет входные данные. Например, если на карту вы добавите объект, не являющийся наследником YMapEntity, JS API вам об этом сообщит. С выключенным строгим режимом JS API такую проверку не сделает, и ваш код может работать неправильно.

Подробнее о строгом режиме.

React

Для каждого объекта в JS API есть React-аналог. Чтобы воспользоваться React-версией API, подключите модуль @yandex/ymaps3-reactify:

const ymaps3Reactify = await ymaps3.import('@yandex/ymaps3-reactify');
const reactify = ymaps3Reactify.reactify.bindTo(React, ReactDOM);
const {YMap, YMapDefaultSchemeLayer, YMapDefaultFeaturesLayer, YMapMarker} = reactify.module(ymaps3);

Примечание

Модуль @yandex/ymaps3-reactify предоставляет набор методов для обращения в React как отдельных объектов, так и модулей/пакетов целиком. Иерархия объектов и параметры инициализации те же самые.

Подключив модуль, используйте любые объекты JS API как React-компоненты:

<YMap location={{center: [25.229762, 55.289311], zoom: 9}} mode="vector">
  <YMapDefaultSchemeLayer />
  <YMapDefaultFeaturesLayer />

  <YMapMarker coordinates={[25.229762, 55.289311]} draggable={true}>
    <section>
      <h1>You can drag this header</h1>
    </section>
  </YMapMarker>
</YMap>

Примечание

Более подробную информацию про интеграцию с React и другими фреймворками смотрите в разделе Интеграции

Предыдущая
Быстрый старт
Следующая
Подключение API