Перейти к основному содержимому

Основные принципы

Модульный подход​

Эта библиотека активно использует систему модулей API Яндекс.Карт, чтобы свести к минимуму объем загружаемого и исполняемого кода из Яндекс.Карт. У этой системы есть свои плюсы и минусы, а также есть способ полностью отказаться от нее.

По умолчанию эта библиотека загружает только те модули, которые фактически отображаются на странице. Если <Placemark /> или <ObjectManager /> не смонтирован на странице, соответствующий не будет загружен.

Это означает, что объем кода, который ваши клиенты будут загружать и выполнять, будет минимальным. С другой стороны, это означает, что вместо того, чтобы получать множество привычных API-модулей Яндекс.Карт по умолчанию, теперь вам нужно серьезно подумать о том, что вы используете на странице.

В приведенном ниже примере мы монтируем карту с меткой на странице:

Вы можете заметить, что здесь отсутствуют все элементы управления картой, которые обычно предоставляются на карте по умолчанию. Это происходит потому, что они не входят в состав «основного» модуля Яндекс.Карт, не входят в состав модуля Map или Placemark.

Загрузка модулей с modules проп​

Давайте исправим это, указав, какие именно элементы управления нам нужны на карте state, а затем воспользуемся modules пропом для загрузки нужных нам элементов:

Отлично! Теперь у нас есть элементы управления на карте, а также мы избежали загрузки полного пакета API Яндекс.Карт.

Все компоненты в этой библиотеке поддерживаю modules prop, что позволит вам загружать дополнительные модули, когда они понадобятся.

Давайте добавим еще один к приведенному выше примеру. На этот раз мы добавим балун к метке. Модуль всплывающей подсказки не загружается с базовым минимальным пакетом API Яндекс.Карт, поэтому, чтобы действительно увидеть баллон, нам нужно указать надстройку балуна как модуль в компоненте Placemark.

Загрузка модулей с YMaps Provider query проп​

Ручное указание необходимых модулей — не единственный способ их загрузки. Вы также можете воспользоваться load опцией при указании query компонента Provider.

Эта опция является частью запроса API Яндекс.Карт и может использоваться для определения того, какие модули вы хотите сразу загрузить с помощью API Яндекс.Карт.

Давайте посмотрим, как можно изменить предыдущий пример, чтобы использовать эту опцию:

Обратите внимание, как мы удалили все modules пропы из всех компонент и заменили их на список модулей в query.load.

Значение по умолчанию API Яндекс.Карт для этой опции — package.full. При установке query.load в 'package.full' этой библиотеки будет установлен режим, полностью соответствующий стандартному поведению API Яндекс.Карт.

Вы можете прочитать подробнее про Yandex.Maps API on-demand module system и API loading parameters в документации на Яндекс.Карты.

Контролируемы и Неконтролируемые компоненты​

Важный шаблон React, о котором следует помнить при использовании этой библиотеки, — это контролируемые и неуправляемые компоненты. Этот шаблон полностью посвящен тому, кто отвечает за обработку обновлений и сохранение состояния компонентов.

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

В приведенном ниже примере состояние карты (точнее, масштаб и координаты) управляется приложением в первом компоненте карты, но не контролируется приложением во втором компоненте карты. При нажатии кнопки масштаб и координаты первой карты будут обновлены, а вторая карта сохранит свое состояние. Это происходит потому, что вместо state prop мы используем defaultState prop.

import React from 'react';

export default function App() {
  const [zoom, setZoom] = React.useState(9);
  const mapState = React.useMemo(
    () => ({ center: [55.75, 37.57], zoom }),
    [zoom]
  );

  return (
    <YMaps>
      <>
        <table>
          <tbody>
            <tr>
              <th>Controlled Map</th>
              <th>Uncontrolled Map</th>
            </tr>
            <tr>
              <td>
                <Map state={mapState} />
              </td>
              <td>
                <Map defaultState={mapState} />
              </td>
            </tr>
          </tbody>
        </table>
        <p>
          <button onClick={() => setZoom((zoom) => (zoom === 9 ? 12 : 9))}>
            Toggle map zoom
          </button>
        </p>
      </>
    </YMaps>
  );
}

Каждая поддержка каждого объекта карты — это библиотека, поддерживающая default версию (например: state и defaultState, options и defaultOptions, properties и defaultProperties, geometry и defaultGeometry). Выбирая использование default версии, вы отказываетесь от обновления объектов карты этой библиотекой при изменении реквизита.

Как упоминалось в разделе «Что поддерживается», невозможно запретить Яндекс.Картам полностью обновлять состояние объектов карты, поэтому очень легко выйти из синхронизации, если вы используете эти компоненты контролируемым образом и не синхронизируете состояние обратно в состояние вашего приложения.

Исходя из личного опыта, вы хотели бы использовать default проп для большинства случаев в вашем приложении.

Если вы хотите узнать больше об управляемых и неуправляемых компонентах, вот несколько полезных ссылок из документации React:

Provider и Consumer компоненты​

Эта библиотека использует React Context API для предоставления API Яндекс.Карт каждому компоненту, который в этом нуждается.

Так как библиотека использует React Context API, поэтому родительские объекты Яндекс.Карт (например, Map, Clusterer, ObjectManager) могут предоставлять дочерним объектам Яндекс.Карт родительский экземпляр.

Если вы хотите узнать больше о компонентах React Context и Provider/Consumer, вы можете ознакомиться с разделом документации React по этой теме.

Убедитесь, что вы использовали компонент провайдера YMaps и все объекты Яндекс.Карт находятся внутри этого дерева компонентов. Эта библиотека выдаст ошибку, если отсутствует контекст Яндекс.Карт.