Карта
- Введение
- Загрузка библиотеки
- Версия библиотеки
- Инициализация карты
- Первоначальная настройка карты
- Класс карты DG.Map
- Конструктор
- Свойства
- Методы
- Удалить карту
- Добавить обработчик события
- Отключить возможность изменения масштаба карты по двойному клику мыши
- Включить возможность изменения масштаба карты по двойному клику мыши
- Проверить включена ли возможность изменения масштаба карты по двойному клику мыши
- Отключить возможность изменения масштаба карты при прокрутке колесика мыши
- Включить возможность изменения масштаба карты при прокрутке колесика мыши
- Проверить включена ли возможность изменения масштаба карты при прокрутке колесика мыши
- Отключить возможность перетаскивания карты с помощью мыши
- Включить возможность перетаскивания карты с помощью мыши
- Проверить включена ли возможность перетаскивания карты с помощью мыши
- Отключить возможность выделения области карты правой кнопкой
- Включить возможность выделения области карты правой кнопкой
- Проверить включена ли возможность выделения области карты правой кнопкой
- Получить контейнер карты
- Получить размер контейнера карты
- Получить идентификатор контейнера карты
- Перерисовать карту
- Переместить карту на север
- Переместить карту на юг
- Переместить карту на запад
- Переместить карту на восток
- Получить максимальный zoom
- Получить минимальный zoom
- Получить текущий zoom
- Установить максимальный zoom
- Установить минимальный zoom
- Установить текущий zoom
- Увеличить zoom на один уровень
- Уменьшить zoom на один уровень
- Изменить zoom на заданную величину
- Получить текущий центр карты
- Установить центр карты
- Получить видимые границы карты
- Установить видимые границы карты
- Установить ограничения на границы карты
- Установить курсор
- Удалить курсор
Введение
В разделе «Быстрый старт» вы уже могли попробовать создать карту. Здесь же рассмотрен этот процесс в деталях. А также освещены вопросы настройки параметров карты.
Загрузка библиотеки
Работа с картой возможна только после того, как будет загружена библиотека. Есть несколько способов это сделать. Начнем с простого.
Первый способ
Сперва подключаем код библиотеки:
<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 | Да | Функция-обработчик, вызываемая при возникновении события определенного типа. Функция вызывается с одним параметром Параметр Если на события одного типа назначено несколько функций-обработчиков путем нескольких вызовов |
Возвращает:
Тип | Описание |
---|---|
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 | Нет | Изменять ли видимые границы карты, чтобы они соответствовали ограничениям Так же следует учесть, что если заданное ограничение |
isMaxContain | Boolean | Нет | Варианты вписывания bounds области в границы карты. Если isMaxContain не указан или равен false , то видимые bounds области полностью вписываются в границы карты. Если значение isMaxContain равно true — область вписывается в границы карты, руководствуясь меньшей стороной этой области. |
Установить курсор
myMap.addCursor(cursorType)Позволяет добавлять один и больше курсоров на карту. Последний добавленный делается активным.
Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
cursorType | String | Да | Одна из констант класса DG.Cursor |
Удалить курсор
myMap.removeCursor(cursorType)Удаляет курсор из карты. Если курсор был активным, то устанавливает предыдущий активным.
Параметры:
Имя | Тип | Обязательный | Описание |
---|---|---|---|
cursorType | String | Да | Одна из констант класса DG.Cursor |
Также существует возможность задать коэффициент масштабирования при установке центра карты. Для этого при вызове метода устанавливающего центр карты необходимо вторым параметром указать новое значение масштаба.