YMap

Класс YMap создает все необходимые элементы карты и представляет базовый контейнер для вкладывания в него других сущностей. Класс позволяет себя уничтожить, при необходимости.

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

Для создания карты в конструкторе класса необходимо:

указать HTML-элемент, в котором будет размещена карта;
инициализировать карту через параметр карты location.

vanilla

react

vue

<head>
  <script>
    ymaps3.ready.then(() => {
      // HTML-элемент.
      const map = new ymaps3.YMap(document.getElementById('first_map'), {
        location: {
          bounds: [[-0.118092, 51.509865], [-0.118092, 51.509865]]
        }
      });
    });
  </script>
</head>
<body>
  <p>Карта</p>
  <div id="first_map" style="width:400px; height:300px"></div>
</body>

Карта может быть размещена в любом блочном HTML-элементе, она полностью заполнит занимаемую ею прямоугольную область. Вычисление размеров этой области производится при помощи ResizeObserver.

Пример создания карты.

Уничтожение карты

Для уничтожения карты из DOM используется метод destroy().

// Уничтожение карты.
map.destroy();

HTML-элемент, который был указан при создании карты, из DOM-дерева не удаляется.

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

Конструктор

new YMap(rootContainer, props[, children]);

Параметры конструктора

Параметр	Тип	required	Описание
`rootContainer`	`HTMLElement`	required	Ссылка на HTML-элемент, в котором размещается карта
`props`	`YMapProps`	required	Параметры карты
`children`	`YMapEntity<unknown, {}>[]`	-	Дочерние элементы

Props

Свойство	Тип	required	Описание
`location`	`YMapLocationRequest`	required	Первоначальное местоположение или запрос на изменение местоположения с возможностью указания анимации.
`behaviors`	`BehaviorType[]`	-	Активные поведения.
`camera`	`YMapCameraRequest`	-	Первоначальная камера или запрос на смену камеры с указанием продолжительности.
`className`	`string`	-	Имя css-класса контейнера карты.
`config`	`Config`	-	Другие конфигурации.
`hotspotsStrategy`	`"forViewport"` \| `"forPointerPosition"`	-	Стратегия запрашивания активных областей на карте сразу для всего видимого экрана или по наведению указателя мыши.
`margin`	`Margin`	-	Отступы карты.
`mode`	`MapMode`	-	Режим карты: `растровый`, `векторный` или `автоматический`. По умолчанию используется автоматический режим карты (отображение растровых фрагментов во время загрузки векторных фрагментов).
`projection`	`Projection`	-	Проекция, используемая на карте.
`restrictMapArea`	`false` \| `LngLatBounds`	-	Устанавливает область просмотра карты таким образом, чтобы пользователь не мог перемещаться за пределы этой области.
`worldOptions`	`WorldOptions`	-	Нужно ли повторять мир по оси X.
`zoomRange`	`ZoomRange`	-	Ограничение минимального и максимального увеличения карты.
`zoomRounding`	`ZoomRounding`	-	Округление для масштабирования. Если выбрано значение `авто`, масштабирование округляется для `растрового` и не округляется для `векторного` режима карты. По умолчанию установлено значение `авто`.
`zoomStrategy`	`ZoomStrategy`	-	Стратегия масштабирования описывает, привязан ли центр карты к точке масштабирования или нет.

Методы

addChild

Объекты расширяемые от класса YMapEntity можно добавить на карту с помощью метода addChild(), вызванного у экземпляра карты:

const {YMap, YMapLayer} = ymaps3;

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

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

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

Параметры

Параметр	Тип	required	Описание
`child`	`YMapEntity<unknown, {}>`	required	Сущность добавляемая на карту.
`index`	`number`	-

Возвращается экземпляр карты типа `YMap`

removeChild

Метод удаляет объект с карты.

const {YMap, YMapLayer} = ymaps3;

const map = new YMap(...);
const layer = new YMapLayer(...);
map.addChild(layer);

map.removeChild(layer);

Параметр	Тип	required	Описание
`child`	`YMapEntity<unknown, {}>`	required	Объект, удаляемый с карты.

Возвращается экземпляр карты типа `YMap`

setLocation

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

// Указание центра карты и масштаба
map.setLocation({
  center: [37.588144, 55.733842],
  zoom: 5
});

// Указание границ видимой части карты
map.setLocation({
  bounds: [[25.21, 55.27], [25.23, 55.29]]
});

Область картографирования можно изменить в любой момент.

setLocation(location: YMapLocationRequest): void {
        this.update({location});
    }

Примечание

Метод не меняет местоположение карты, если в него передавать объект location с одинаковыми параметрами при каждом запросе.

Пример:

const moscow = {center: [37,55], zoom:10};
map.setLocation({location: moscow});
// масштабирование
map.update({location: moscow}); // Запрос на изменение location такой же как и последний, локация не меняется.

Параметры

Параметр	Тип	required	Описание
`location`	`YMapLocationRequest`	required	Область картографирования.

update

update(changedProps): void

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

map.update({
 location: {
     center: [-0.118092, 51.509865], // Центр карты.
     zoom: 10, // Уровень зума.
     duration: 200, // Анимация карты займет 200 миллисекунд.
     easing: 'ease-in-out' // Функция анимации изменения местоположения на карте.
 }
});

Примечание

Пример:

const moscow = {center: [37,55], zoom:10};
map.update({location: moscow});
// масштабирование
map.update({location: moscow}); // Запрос на изменение location такой же как и последний, локация не меняется.

Параметры

Параметр	Тип	Описание
`changedProps`	`Partial`<`YMapProps`>	Новые значения `props`.

Карта обладает набором поведений, определяющих реакцию карты на действия, производимые пользователем. Например, при перемещении курсора мыши в области показа при нажатой левой кнопке карта сдвигается вслед за курсором.

При инициализации карты ей присваивается набор поведений, который в дальнейшем можно изменить с помощью метода setBehaviors(). Доступ к поведениям карты предоставляется через поле behaviors.

const map = new YMap(element, {
  document.getElementById('map'),
  {
    // ... остальные props.
    behaviors: ['drag', 'pinchZoom', 'mouseTilt']
  }
});

map.setBehaviors(['drag', 'pinchZoom']);

Параметры

Параметр	Тип	required	Описание
`behaviors`	`BehaviorType[]`	required	Набор поведений.

Возвращается `void`

setMode

Режим карты может быть задан как в конструкторе, так и с помощью метода setMode().

// Задание растрового режима в конструкторе.
const map = new YMap(
  document.getElementById('map'),
  {
    // ... остальные props.
    mode: 'raster'
  }
);

// Задание векторного режима с помощью метода setMode().
map.setMode('vector');

Параметры

Параметр	Тип	required	Описание
`mode`	`MapMode`	required	Режим карты.

Возвращается `void`

destroy

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

const {YMap} = ymaps3;

const map = new YMap(...);

map.destroy();

Возвращается `void`

Проекционные пакеты

Пакет `@yandex/ymaps3-cartesian-projection`

Пакет предоставляет проекцию, с которой карта будет работать в декартовой системе координат.

Установка и использование пакета

Использование c npm

Использование без npm

npm install --save @yandex/ymaps3-cartesian-projection

Чтобы использовать декартову проекцию, импортируйте ее:

import {Cartesian} from '@yandex/ymaps3-cartesian-projection';

const projection = new Cartesian([
    // Эти границы определяют границы карты мира в декартовой системе координат.
    [-400, -600],
    [400, 600],
]);

console.log(projection.toWorldCoordinates([-400, 600])) // {x: -1, y: 1}
console.log(projection.toWorldCoordinates([200, 0])) // {x: 0.5, y: 0}
console.log(projection.toWorldCoordinates([0, -75])) // {x: 0, y: -0.125}

console.log(projection.fromWorldCoordinates({x: -1, y: 1})) // [-400, 600]
console.log(projection.fromWorldCoordinates({x: 0.5, y: 0})) // [200, 0]
console.log(projection.fromWorldCoordinates({x: 0, y: -0.125})) // [0, -75]

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

По умолчанию ymaps3.import можно загружать собственные модули. Просто используйте ymaps3.registerCdn и ymaps3.import:

// зарегистрируйте CDN в `ymaps3.import`, добавьте загрузчик для пакета, указывая из какого CDN загружать
ymaps3.import.registerCdn(
  'https://cdn.jsdelivr.net/npm/{package}',
  '@yandex/ymaps3-cartesian-projection@latest'
);

// ...

// импортируйте пакет из CDN
const pkg = await ymaps3.import('@yandex/ymaps3-cartesian-projection');

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

vanilla

react

vue

<!DOCTYPE html>
<html>
    <head>
        <title>Vanila example @yandex/ymaps3-cartesian-projection</title>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
        <script src="https://api-maps.yandex.ru/v3/?apikey=%APIKEY%&lang=en_US"></script>
        <script src="common.js"></script>
        <script>
            let map = null;

            main();
            async function main() {
                await ymaps3.ready;
                const {YMap, YMapTileDataSource, YMapLayer, YMapDefaultFeaturesLayer, YMapControls} = ymaps3;

                const {YMapZoomControl} = await ymaps3.import('@yandex/ymaps3-default-ui-theme');
                const {YMapDefaultMarker} = await ymaps3.import('@yandex/ymaps3-default-ui-theme');
                const {Cartesian} = await ymaps3.import('@yandex/ymaps3-cartesian-projection');

                map = new YMap(document.getElementById('app'), getMapProps(Cartesian));

                map.addChild(new YMapTileDataSource(SOURCE));
                map.addChild(new YMapLayer(LAYER));
                map.addChild((new YMapDefaultFeaturesLayer()));

                map.addChild(
                    new YMapControls({position: 'right'}).addChild(new YMapZoomControl({}))
                );

                MARKERS.forEach(marker => {
                    map.addChild(new YMapDefaultMarker(marker));
                });
            }
        </script>

        <link rel="stylesheet" href="common.css" />
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>

 <!DOCTYPE html>
 <html>
     <head>
         <title>React example @yandex/ymaps3-cartesian-projection</title>
         <meta charset="UTF-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
         <script crossorigin src="https://unpkg.com/react@17/umd/react.production.min.js"></script>
         <script crossorigin src="https://unpkg.com/react-dom@17/umd/react-dom.production.min.js"></script>
         <script crossorigin src="https://unpkg.com/babel-standalone@6/babel.min.js"></script>
         <script src='https://api-maps.yandex.ru/v3/?apikey=%APIKEY%&lang=en_US'></script>
         <script src="common.js"></script>

         <script type="text/babel">
             let map = null;

             main();
             async function main() {
                 const [ymaps3React] = await Promise.all([ymaps3.import('@yandex/ymaps3-reactify'), ymaps3.ready]);
                 const reactify = ymaps3React.reactify.bindTo(React, ReactDOM);

                 const {
                     YMap,
                     YMapTileDataSource,
                     YMapLayer,
                     YMapDefaultFeaturesLayer,
                     YMapControls
                 } = reactify.module(ymaps3);

                 const {useState, useCallback} = React;

                 const {YMapZoomControl} = reactify.module(await ymaps3.import('@yandex/ymaps3-default-ui-theme'));
                 const {YMapDefaultMarker} = reactify.module(await ymaps3.import('@yandex/ymaps3-default-ui-theme'));
                 const {Cartesian} = await ymaps3.import('@yandex/ymaps3-cartesian-projection');

                 const mapProps = getMapProps(Cartesian);

                 ReactDOM.render(
                     <React.StrictMode>
                         <App />
                     </React.StrictMode>,
                     document.getElementById('app')
                 );

                 function App() {
                     const [location, setLocation] = useState(mapProps.location);
                     const onClick = useCallback(() => alert('Click!'), []);

                     return (
                         <YMap {...mapProps} location={location} ref={(x) => (map = x)}>
                             <YMapTileDataSource {...SOURCE} />
                             <YMapLayer {...LAYER} />

                             <YMapDefaultFeaturesLayer />

                             <YMapControls position="right">
                                 <YMapZoomControl />
                             </YMapControls>

                             {MARKERS.map(marker => <YMapDefaultMarker {...marker} />)}
                         </YMap>
                     );
                 }
             }
         </script>

         <link rel="stylesheet" href="common.css" />
     </head>
     <body>
         <div id="app"></div>
     </body>
 </html>

Пакет `@yandex/ymaps3-web-mercator-projection`

Пакет предоставляет проекцию Web Меркатора.

Установка и использование пакета

Использование c npm

Использование без npm

npm install --save @yandex/ymaps3-web-mercator-projection

Чтобы использовать декартову проекцию, импортируйте ее:

import {WebMercator} from '@yandex/ymaps3-web-mercator-projection';

const projection = new WebMercator();

console.log(projection.toWorldCoordinates([-180, 90])) // {x: -1, y: 1}
console.log(projection.toWorldCoordinates([-180, 85.051])) // ~ {x: -1, y: 1}
console.log(projection.toWorldCoordinates([90, 0])) // ~ {x: 0.5, y: 0}
console.log(projection.toWorldCoordinates([0, -23.6])) // ~ {x: 0, y: -0.135}

console.log(projection.fromWorldCoordinates({x: -1, y: 1})) // ~ [-180, 85.051]
console.log(projection.fromWorldCoordinates({x: 0.5, y: 0})) // [90, 0]
console.log(projection.fromWorldCoordinates({x: 0, y: -0.135})) // ~ [0, -23.6]

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

По умолчанию ymaps3.import можно загружать собственные модули. Просто используйте ymaps3.registerCdn и ymaps3.import:

// зарегистрируйте CDN в `ymaps3.import`, добавьте загрузчик для пакета, указывая из какого CDN загружать
ymaps3.import.registerCdn(
  'https://cdn.jsdelivr.net/npm/{package}',
  '@yandex/ymaps3-web-mercator-projection@latest'
);

// ...

// импортируйте пакет из CDN
const pkg = await ymaps3.import('@yandex/ymaps3-web-mercator-projection');

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

vanilla

react

vue

<!DOCTYPE html>
<html>
    <head>
        <title>Vanila example @yandex/ymaps3-web-mercator-projection</title>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
        <script src="https://api-maps.yandex.ru/v3/?apikey=%APIKEY%&lang=en_US"></script>
        <script src="common.js"></script>
        <script>
            let map = null;

            main();
            async function main() {
                await ymaps3.ready;
                const {YMap, YMapTileDataSource, YMapLayer, YMapDefaultFeaturesLayer} = ymaps3;

                const {YMapZoomControl} = await ymaps3.import('@yandex/ymaps3-default-ui-theme');
                const {YMapDefaultMarker} = await ymaps3.import('@yandex/ymaps3-default-ui-theme');

                const {WebMercator} = await ymaps3.import('@yandex/ymaps3-web-mercator-projection');
                const projection = new WebMercator();

                map = new YMap(document.getElementById('app'), {
                    location: LOCATION,
                    projection: projection
                });

                map.addChild(new YMapTileDataSource(SOURCE));
                map.addChild(new YMapLayer(LAYER));

                map.addChild(new YMapDefaultFeaturesLayer());
                map.addChild(new YMapDefaultMarker(MARKER));
            }
        </script>

        <link rel="stylesheet" href="common.css" />
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>

 <!DOCTYPE html>
 <html>
     <head>
         <title>React example @yandex/ymaps3-web-mercator-projection</title>
         <meta charset="UTF-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
         <script crossorigin src="https://unpkg.com/react@17/umd/react.production.min.js"></script>
         <script crossorigin src="https://unpkg.com/react-dom@17/umd/react-dom.production.min.js"></script>
         <script crossorigin src="https://unpkg.com/babel-standalone@6/babel.min.js"></script>
         <script src='https://api-maps.yandex.ru/v3/?apikey=%APIKEY%&lang=en_US'></script>
         <script src="common.js"></script>

         <script type="text/babel">
             let map = null;

             main();
             async function main() {
                 const [ymaps3React] = await Promise.all([ymaps3.import('@yandex/ymaps3-reactify'), ymaps3.ready]);
                 const reactify = ymaps3React.reactify.bindTo(React, ReactDOM);

                 const {YMap, YMapTileDataSource, YMapLayer, YMapDefaultFeaturesLayer} = reactify.module(ymaps3);

                 const {useState, useCallback} = React;

                 const {YMapZoomControl} = reactify.module(await ymaps3.import('@yandex/ymaps3-default-ui-theme'));
                 const {YMapDefaultMarker} = reactify.module(await ymaps3.import('@yandex/ymaps3-default-ui-theme'));

                 const {WebMercator} = await ymaps3.import('@yandex/ymaps3-web-mercator-projection');
                 const projection = new WebMercator();

                 ReactDOM.render(
                     <React.StrictMode>
                         <App />
                     </React.StrictMode>,
                     document.getElementById('app')
                 );

                 function App() {
                     const [location, setLocation] = useState(LOCATION);
                     const onClick = useCallback(() => alert('Click!'), []);

                     return (
                         <YMap location={location} projection={projection} ref={(x) => (map = x)}>
                             <YMapTileDataSource {...SOURCE} />
                             <YMapLayer {...LAYER} />
                             <YMapDefaultFeaturesLayer />
                             <YMapDefaultMarker {...MARKER} />
                         </YMap>
                     );
                 }
             }
         </script>

         <link rel="stylesheet" href="common.css" />
     </head>
     <body>
         <div id="app"></div>
     </body>
 </html>

YMap

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

Уничтожение картыУничтожение карты

КонструкторКонструктор

Параметры конструктораПараметры конструктора

PropsProps

МетодыМетоды

addChildaddChild

ПараметрыПараметры

Возвращается экземпляр карты типа Возвращается экземпляр карты типа YMap

removeChildremoveChild

Возвращается экземпляр карты типа Возвращается экземпляр карты типа YMap

setLocationsetLocation

ПараметрыПараметры

Возвращается Возвращается void

updateupdate

ПараметрыПараметры

Возвращается Возвращается void

setBehaviorssetBehaviors

ПараметрыПараметры

Возвращается Возвращается void

setModesetMode

ПараметрыПараметры

Возвращается Возвращается void

destroydestroy

Возвращается Возвращается void

Проекционные пакетыПроекционные пакеты

Пакет Пакет @yandex/ymaps3-cartesian-projection

Установка и использование пакетаУстановка и использование пакета

Пакет Пакет @yandex/ymaps3-web-mercator-projection

Установка и использование пакетаУстановка и использование пакета

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

Уничтожение карты

Конструктор

Параметры конструктора

Props

Методы

addChild

Параметры

Возвращается экземпляр карты типа `YMap`

removeChild

Возвращается экземпляр карты типа `YMap`

setLocation

Параметры

Возвращается `void`

update

Параметры

Возвращается `void`

setBehaviors

Параметры

Возвращается `void`

setMode

Параметры

Возвращается `void`

destroy

Возвращается `void`

Проекционные пакеты

Пакет `@yandex/ymaps3-cartesian-projection`

Установка и использование пакета

Пакет `@yandex/ymaps3-web-mercator-projection`

Установка и использование пакета