Карта

Введение

В разделе «Быстрый старт» вы уже могли попробовать создать карту. Здесь же рассмотрен этот процесс в деталях. А также освещены вопросы настройки параметров карты.

Загрузка библиотеки

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

Первый способ

Сперва подключаем код библиотеки:

<script type="text/javascript" src="http://maps.api.2gis.ru/1.0"></script>

Затем воспользуемся функцией DG.autoload, в которую помещаем код инициализации карты:

<script type="text/javascript">
// Создаем обработчик загрузки страницы:
DG.autoload(function() {
// Инициализация карты
...
});
</script>

Именно такой способ рассматривался в разделе «Быстрый старт». Внутри себя эта функция добавляет обработчик на событие загрузки страницы.

Второй способ

Если первый способ не подходит, можно воспользоваться функцией DG.load. Ее можно вызвать именно в тот момент, когда карта станет нужна, а не только при загрузки страницы.

Плюс, если на странице подключена библиотека jQuery (для определенности), можно ускорить загрузку карты, если вызывать DG.load с помощью метода JQuery.ready:

<script type="text/javascript">
$(DG.load(function(){
// Инициализация карты
...
}));
</script>

Правда, в случае использования DG.load нужно изменить способ загрузки библиотеки — добавить GET-параметр loadByRequire:

<script type="text/javascript" src="http://maps.api.2gis.ru/1.0?loadByRequire=1"></script>

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

Версия библиотеки

Версия библиотеки состоит из двух чисел, разделенных точкой. Например, 1.7.

Первая цифра увеличивается при радикальном изменении API. Вторая - при нарушении обратной совместимости со старыми версиями.

Для подключения конкретной версии библиотеки ее следует указать при подключении. Например:

<script src="http://maps.api.2gis.ru/1.7" type="text/javascript"></script>

Указывать версию библиотеки обязательно.

Инициализация карты

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

<div id="myMapId" style="width:500px; height:400px"></div>

Во время создания экземпляра карты нужно связать его с контейнерным HTML-элементом. Первый способ это сделать — передать в конструктор карты идентификатор элемента. В нашем случае:

// Создаем экземпляр карты, привязывая его к контейнеру по его ID
var myMap = new DG.Map("myMapId");

Второй способ, более сложный, — передать в конструктор карты DOMElement:

// Получаем DOMElement контейнера
var container = document.getElementById("myMapId");
// Создаем экземпляр карты, привязывая его к DOM объекту контейнеру
var myMap = new DG.Map(container);

Первоначальная настройка карты

Центр карты

Теперь нужно установить центр карты. Задать местоположение карты можно создав объект DG.GeoPoint, конструктор которого принимает долготу и широту точки соответственно.

Пример для Новосибирска (долгота: ~82.97, широта: ~55.02):

// Задаем географическое положение, передавая долготу и широту
var point = new DG.GeoPoint(82.927810142519,55.028936234826);

Чтобы установить центр карты вызываем метод карты setCenter:

// Устанавливаем центр карты в положение точки 
point:myMap.setCenter(point);

Или одной строчкой:

myMap.setCenter(new DG.GeoPoint(82.927810142519,55.028936234826));

Также существует возможность задать коэффициент масштабирования, при установке центра карты. Для этого, при вызове метода устанавливающего центр карты, необходимо вторым параметром указать новое значение масштаба:

myMap.setCenter(new DG.GeoPoint(82.927810142519,55.028936234826), 15);

Масштаб (zoom)

Установить масштаб карты можно с помощью метода карты setZoom:

// Устанавливаем коэффициент масштабирования равным 14
myMap.setZoom(14);

Что означает коэффициент масштабирования, который мы передаем этому методу? Это целое число в интервале от 1-го до максимально допустимого уровня зума. Максимально допустимый уровень зума зависит от города, отображаемого на карте. Вне городов, покрытых 2ГИС, максимальный уровень зума составляет 13. Для большинства городов России максимальный уровень зума равен 17. Чем больше число, тем ближе мы приближаемся к поверхности. Для корректного рассчета максимально допустимого уровня зума, необходимо предварительно установить центр карты.

Управление масштабом

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

// Добавляем элемент управления коэффициентом масштабирования:
myMap.controls.add(new DG.Controls.Zoom());

В разделе руководства «Элементы управления» мы подробно рассмотрим вопрос работы элементов.

Кнопка разворачивания карты на весь экран браузера

В API карт встроен стандартный элемент управления разворачиванием карты на весь экран браузера, который по умолчанию включен. Используя данный элемент управления в правом верхнем углу карты появится кнопка. При клике по этой кнопке карта разворачивается на весь экран браузера. Повторный клик восстанавливает предыдущий размер карты.

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

Ниже мы рассмотрим несколько примеров.

Для наглядности предположим, что myMap — объект карты.

Включение кнопки разворачивания карты на весь экран браузера:

myMap.fullscreen.enable();

Отключение кнопки разворачивания карты на весь экран браузера:

myMap.fullscreen.disable();

Геокодирование по клику

В API карт встроена функция геокодирования, которая по умолчанию включена. Используя данную функцию, при кликах мышки по карте будет появляться балун с информацией об объекте, а периметр объекта будет подсвечиваться (периметры домов не подсвечиваются). Дополнительно можно изменить стилистику подсветки периметра объекта.

За обработку геокодированиея по клику отвечает класс геокликера. Данный класс создаётся автоматически при инициализации карты и не должен создаваться вручную. Доступ к классу можно получить через свойство объекта карты geoclicker, например: myMap.geoclicker.

Ниже мы рассмотрим несколько примеров.

Для наглядности предположим, что myMap — объект карты.

Включение функции геокодирования:

myMap.geoclicker.enable();

Отключение функции геокодирования:

myMap.geoclicker.disable();

Стилизация подсвечиваемой области:

// Создаем объект стилей:
var style = new DG.Style.Geometry();
// Устанавливаем значения свойств:
style.strokeColor = "blue";
style.strokeOpacity = 1;
style.strokeWidth = 3;
style.fillColor = "#ff00ff";
style.fillOpacity = 0.4;

// Устанавливаем стиль:
myMap.geoclicker.setStyle(style);

В результате выполнения кода из этого примера подсвечиваемая область будет закрашена полупрозрачным фиолетовым фоном, а границы будут синего цвета.

Открыть пример в новом окне

Получение текущего стиля подсвечиваемой области:

var currentStyle = myMap.geoclicker.getStyle();

Класс карты DG.Map

Для наглядности допустим, что myMap — объект карты.

Конструктор

Параметры:

Имя Тип Обязательный Описание
div String | DOMElement Да Карта размещается внутри контейнерного HTML-элемента, внутри которого будет показываться карта. Параметр может принимать либо идентификатор карты, либо сам DOM-элемент.

Пример:

// Первый способ. Создаем экземпляр карты, привязывая его к контейнеру по его ID:
var myMap = new DG.Map("myMapId");

// Второй способ. Получаем DOMElement контейнера:
var container = document.getElementById("myMapId");
// Создаем экземпляр карты, привязывая его к DOM объекту контейнеру
var myMap = new DG.Map("container");

// Создаем экземпляр карты, привязывая его к контейнеру по его ID
var myMap = new DG.Map("myMapId");

Свойства

Менеджер маркеров
myMap.markers

Возвращает:

Тип Описание
DG.Markers Менеджер маркеров. Экземпляр класса DG.Markers.
Менеджер балунов
myMap.balloons

Возвращает:

Тип Описание
DG.Balloons Менеджер балунов. Экземпляр класса DG.Balloons.
Менеджер геометрий
myMap.geometries

Возвращает:

Тип Описание
DG.Geometries Менеджер геометрий. Экземпляр класса DG.Geometries.
Менеджер элементов управления
myMap.controls

Возвращает:

Тип Описание
DG.Controls Менеджер элементов управления. Экземпляр класса DG.Controls.
Преобразователь координат
myMap.converter

Возвращает:

Тип Описание
DG.Converter Преобразователь координат. Экземпляр класса DG.Converter.

Методы

Удалить карту
myMap.destroy()

Уничтожает все объекты, которые содержит карта. Чтобы уничтожить сам объект myMap после вызова данного метода рекомендуется присвоить null объекту карты:

// Удаляем все внутренние объекты карты:
myMap.destroy();
// Удаляем сам объект карты:
myMap = null;
Добавить обработчик события
myMap.addEventListener(objectId, eventType, callback)

Параметры:

Имя Тип Обязательный Описание
objectId String Да Идентификатор DOM-элемента, к которому прикрепляем обработчик.
eventType String Да Тип события. Возможные типы событий перечислены вместе с условием возникновения каждого события в таблице «Тип события — Класс — Условие».
callback Function Да

Функция-обработчик, вызываемая при возникновении события определенного типа. Функция вызывается с одним параметром callback(myEvent).

Параметр myEvent может быть объектом различных классов. Соответствия между типом события и классом события myEvent перечислены в таблице «Тип события — Класс — Условие».

Если на события одного типа назначено несколько функций-обработчиков путем нескольких вызовов myMap.addEventListener, то они вызываются в порядке добавления. При этом, если одна из функций-обработчиков вернет true, то остальные функции-обработчики дальше выполняться не будут.

Возвращает:

Тип Описание
DG.Observer Объект с помощью которого, можно управлять обработчиком.

Все особенности работы с событиями рассмотрены в разделе документации «События».

Таблица «Тип события — Класс — Условие»:

Тип события Класс события Условие возникновения
DgDrag DG.Events.Drag Перетаскивание объекта на карте с помощью зажатия левой кнопки мышки.
DgRightDrag DG.Events.Drag Перетаскивание объекта на карте с помощью зажатия правой кнопки мышки.
DgDragStart DG.Events.Mouse Начало перетаскивания объекта на карте с помощью зажатия правой или левой кнопки мышки.
DgDragStop DG.Events.Mouse Остановка перетаскивания объекта на карте с помощью зажатия правой или левой кнопки мышки.
DgMouseMove DG.Events.Mouse Перемещение курсора мышки.
DgClick DG.Events.Mouse Клик левой кнопкой мышки.
DgRightClick DG.Events.Mouse Клик правой кнопкой мышки.
DgDoubleClick DG.Events.Mouse Двойной клик левой кнопкой мышки.
DgDoubleRightClick DG.Events.Mouse Двойной клик правой кнопкой мышки.
DgMouseWheel DG.Events.Mouse Прокручивание колёсика мышки.
DgMapMove DG.Events.Map Перетаскивание карты на экране.
DgSettingsChange DG.Events.Map Изменение настроек карты (например, ограничений масштаба карты и установка допустимых границ карты).
DgZoomChange DG.Events.Map Изменение масштаба карты.
DgViewResize DG.Events.Map Изменение размеров контейнера карты (во время изменения размера окна браузера).
DgLayerVisibilityChange DG.Events.Layers Скрытие или отображение слоя на карте.
DgLanguageChange DG.Events.Locale Изменение языка карты.
Отключить возможность изменения масштаба карты по двойному клику мыши
myMap.disableDblClickZoom()
Открыть пример в новом окне
Включить возможность изменения масштаба карты по двойному клику мыши
myMap.enableDblClickZoom()
Открыть пример в новом окне
Проверить включена ли возможность изменения масштаба карты по двойному клику мыши
myMap.dblClickZoomEnabled()

Возвращает:

Тип Описание
Boolean Включена ли возможность изменения масштаба карты по двойному клику мыши
Отключить возможность изменения масштаба карты при прокрутке колесика мыши
myMap.disableScrollZoom()
Открыть пример в новом окне
Включить возможность изменения масштаба карты при прокрутке колесика мыши
myMap.enableScrollZoom()
Открыть пример в новом окне
Проверить включена ли возможность изменения масштаба карты при прокрутке колесика мыши
myMap.scrollZoomEnabled()

Возвращает:

Тип Описание
Boolean Включена ли возможность изменения масштаба карты при прокрутке колесика мыши.
Отключить возможность перетаскивания карты с помощью мыши
myMap.disableDragging()
Открыть пример в новом окне
Включить возможность перетаскивания карты с помощью мыши
myMap.enableDragging()
Открыть пример в новом окне
Проверить включена ли возможность перетаскивания карты с помощью мыши
myMap.draggingEnabled()

Возвращает:

Тип Описание
Boolean Включена ли возможность перетаскивания карты с помощью мыши
Отключить возможность выделения области карты правой кнопкой
myMap.disableRightButtonMagnifier()
Включить возможность выделения области карты правой кнопкой
myMap.enableRightButtonMagnifier()
Проверить включена ли возможность выделения области карты правой кнопкой
myMap.rightButtonMagnifierEnabled()

Возвращает:

Тип Описание
Boolean Включена ли возможность выделения области карты правой кнопкой мыши
Получить контейнер карты
myMap.getContainer()

Возвращает:

Тип Описание
DOMElement Контейнерный DOM-элемент, в котором размещается карта.
Получить размер контейнера карты
myMap.getContainerSize()

Возвращает:

Тип Описание
DG.Size Объект DG.Size, соответствующий размеру контейнерного DOM-элементу, в котором размещается карта.
Получить идентификатор контейнера карты
myMap.getContainerId()

Возвращает:

Тип Описание
String Свойство «id» контейнерного DOM-элемента, в котором размещается карта.
Перерисовать карту
myMap.redraw()

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

Открыть пример в новом окне
Переместить карту на север
myMap.moveN(moveStep)

Параметры:

Имя Тип Обязательный Описание
moveStep Number Да Шаг, на сколько пикселей сместить карту на север.
Переместить карту на юг
myMap.moveS(moveStep)

Параметры:

Имя Тип Обязательный Описание
moveStep Number Да Шаг, на сколько пикселей сместить карту на юг.
Переместить карту на запад
myMap.moveW(moveStep)

Параметры:

Имя Тип Обязательный Описание
moveStep Number Да Шаг, на сколько пикселей сместить карту на запад.
Переместить карту на восток
myMap.moveE(moveStep)

Параметры:

Имя Тип Обязательный Описание
moveStep Number Да Шаг, на сколько пикселей сместить карту на восток.
Получить максимальный zoom
myMap.getMaxZoom()

Возвращает:

Тип Описание
Number Максимально возможный коэффициент масштабирования (zoom).
Получить минимальный zoom
myMap.getMinZoom()

Возвращает:

Тип Описание
Number Минимально возможный коэффициент масштабирования (zoom).
Получить текущий zoom
myMap.getZoom()

Возвращает:

Тип Описание
Number Текущий коэффициент масштабирования (zoom).
Установить максимальный zoom
myMap.setMaxZoom(maxZoom)

Параметры:

Имя Тип Обязательный Описание
maxZoom Number Да Максимально возможный коэффициент масштабирования(zoom). Максимальное допустимое значение: 18.
Установить минимальный zoom
myMap.setMinZoom(minZoom)

Параметры:

Имя Тип Обязательный Описание
minZoom Number Да Минимально возможный коэффициент масштабирования(zoom). Минимальное допустимое значение: 1.
Установить текущий zoom
myMap.setZoom(zoom)

Параметры:

Имя Тип Обязательный Описание
zoom Number Да Текущий коэффициент масштабирования (zoom).
Увеличить zoom на один уровень
myMap.zoomIn()
Уменьшить zoom на один уровень
myMap.zoomOut()
Изменить zoom на заданную величину
myMap.zoomBy(zoomDiff)

Параметры:

Имя Тип Обязательный Описание
zoomDiff Number Да Изменяет коэффициент масштабирования(zoom) на определенную величину. Если параметр положительный, увеличиаем zoom, иначе — уменьшаем.
Получить текущий центр карты
myMap.getCenter()

Возвращает:

Тип Описание
DG.GeoPoint Географическое положение центра карты.
Установить центр карты
myMap.setCenter(center, zoomLevel)

Параметры:

Имя Тип Обязательный Описание
center DG.GeoPoint Да Географическое положение центра карты.
zoomLevel Number Нет Коэффициент масштабирования карты (zoom).
Получить видимые границы карты
myMap.getBounds()

Возвращает:

Тип Описание
DG.Bounds Объект DG.Bounds, соответствующий видимым границам карты.
Установить видимые границы карты
myMap.setBounds(bounds)

Параметры:

Имя Тип Обязательный Описание
bounds DG.Bounds Да Объект DG.Bounds, соответствующий видимым границам карты.

При выполнении данного метода коэффициент масштабирования и центр карты будет автоматически установлен в такие значения, чтобы охватить заданные границы.

Установить ограничения на границы карты
myMap.setBoundsRestrictions(bounds, isChangePosition, isMaxContain)

Параметры:

Имя Тип Обязательный Описание
bounds DG.Bounds Да Объект DG.Bounds, соответствующий ограничением на границам карты. За рамки данных границ пользователь не сможет выйти.
isChangePosition Boolean Нет

Изменять ли видимые границы карты, чтобы они соответствовали ограничениям bounds. Если isChangePosition не указан или равен false, то видимые границы не меняются, и пользователь останется в том же положении на карте. Если isChangePosition равен true, видимые границы карты меняются, чтобы вписать заданный bounds.

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

isMaxContain Boolean Нет Варианты вписывания bounds области в границы карты. Если isMaxContain не указан или равен false, то видимые bounds области полностью вписываются в границы карты. Если значение isMaxContain равно true — область вписывается в границы карты, руководствуясь меньшей стороной этой области.
Установить курсор
myMap.addCursor(cursorType)

Позволяет добавлять один и больше курсоров на карту. Последний добавленный делается активным.

Параметры:

Имя Тип Обязательный Описание
cursorType String Да Одна из констант класса DG.Cursor
Открыть пример в новом окне
Удалить курсор
myMap.removeCursor(cursorType)

Удаляет курсор из карты. Если курсор был активным, то устанавливает предыдущий активным.

Параметры:

Имя Тип Обязательный Описание
cursorType String Да Одна из констант класса DG.Cursor
Открыть пример в новом окне

Также существует возможность задать коэффициент масштабирования при установке центра карты. Для этого при вызове метода устанавливающего центр карты необходимо вторым параметром указать новое значение масштаба.