Базовые классы

Служебные классы библотеки, необходимые для работы API карт и разработки собственных модулей.

DG.Class

DG.Class предоставляет возможность использовать ООП подход в разработке API карт, и используется для реализации большинства классов, приведенных в этой документации.

Кроме реализации простой классической модели наследования, имеются несколько свойств для удобной организации кода, такие как options, includes и statics.

var MyClass = DG.Class.extend({
    initialize: function (greeter) {
        this.greeter = greeter;
        // конструктор класса
    },

    greet: function (name) {
        alert(this.greeter + ', ' + name)
    }
});

// создает объект класса MyClass и передает "Hello" в конструктор
var a = new MyClass("Hello");

// вызывает метод greet, который показывает всплывающее окно с текстом "Hello, World"
a.greet("World");

Фабрики классов

Объекты в API карт можно создавать без использования ключевого слова new. Это достигается путем дополнения описания каждого класса статическим методом, имеющим наименование класса, только в нижнем регистре.

new DG.Map('map');
DG.map('map');      // эквивалентный вызов

Вы можете использовать такой подход в своих классах, т.к. подобные методы реализованы достаточно просто:

DG.map = function (id, options) {
    return new DG.Map(id, options);
};

Наследование

Для определения новых классов используется DG.Class.extend, также метод extend можно использовать в любом другом классе, который наследуется от DG.Class:

var MyChildClass = MyClass.extend({
    // ... новые свойства и методы
});

Данный код создаст класс, который унаследует все методы и свойства родительского класса (через цепочку прототипов), при необходимости добавляя или переопределяя родительские методы и свойства. Кроме того, корректно обрабатывается оператор instanceof:

var a = new MyChildClass();
a instanceof MyChildClass; // true
a instanceof MyClass; // true

Вы можете вызывать родительские методы (включая конструктор) из дочерних классов (так, как вы бы делали это с помощью вызова super в других языках программирования) с помощью JavaScript функций call или apply:

var MyChildClass = MyClass.extend({
    initialize: function () {
        MyClass.prototype.initialize.call(this, "Yo");
    },

    greet: function (name) {
        MyClass.prototype.greet.call(this, 'bro ' + name + '!');
    }
});

var a = new MyChildClass();
a.greet('Jason'); // выведет "Yo, bro Jason!"

Объект опций

options — ссылка на специальный объект, свойства которого, в отличии от других объектов передаваемых через extend, будут объединены со свойствами аналогичного объекта родителя, вместо полного переопределения объекта. Это позволяет управлять конфигурацией объектов и значениями по умолчанию:

var MyClass = DG.Class.extend({
    options: {
        myOption1: 'foo',
        myOption2: 'bar'
    }
});

var MyChildClass = DG.Class.extend({
    options: {
        myOption1: 'baz',
        myOption3: 5
    }
});

var a = new MyChildClass();
a.options.myOption1; // 'baz'
a.options.myOption2; // 'bar'
a.options.myOption3; // 5

Также существует метод DG.Util.setOptions, который позволяет объединять опции, переданные в конструктор, с опциями, заданными по умолчанию:

var MyClass = DG.Class.extend({
    options: {
        foo: 'bar',
        bla: 5
    },

    initialize: function (options) {
        DG.Util.setOptions(this, options);
        ...
    }
});

var a = new MyClass({bla: 10});
a.options; // {foo: 'bar', bla: 10}

Поддержка создания миксинов

includes — ссылка на специальный объект, свойства и методы которого будут объединены со свойствами и методами экземпляров класса (такие объекты называются mixin-ами).

 var MyMixin = {
    foo: function () { ... },
    bar: 5
};

var MyClass = DG.Class.extend({
    includes: MyMixin
});

var a = new MyClass();
a.foo();

Также, вы можете подмешивать объекты в процессе выполнения программы, с помощью метода include:

MyClass.include(MyMixin);

Поддержка статических членов класса

statics — ссылка на специальный объект, свойства и методы которого будут объединены со статическими свойствами и методами класса. Бывает удобно использовать для определения констант:

var MyClass = DG.Class.extend({
    statics: {
        FOO: 'bar',
        BLA: 5
    }
});

MyClass.FOO; // 'bar'

Перехватчики конструктора

Если вы разрабатываете модуль к API карт, существует вероятность того, что вам понадобится выполнить дополнительные действия при инициализации объектов существующих классов (например, при инициализации объекта DG.Polyline).

Для подобного рода задач есть метод addInitHook:

MyClass.addInitHook(function () {
    // ... выполнить дополнительные действия при вызове конструктора
    // например, добавить обработчики событий, установить значения свойств и т.п.
});

Также можно использовать сокращенную запись, если вам надо сделать всего лишь один дополнительный вызов метода:

MyClass.addInitHook('methodName', arg1, arg2, …);

Функции

Функция Возвращает Описание
extend( <Object> props ) Function Возвращает функцию Javascript, являющуюся конструктором класса (в дальнейшем, функция должна вызываться с new), который наследует методы и свойства базового класса.
include( <Object> properties ) Подмешивает методы и свойства объекта в текущий класс.
mergeOptions( <Object> options ) Объединяет объект опций с объектом опций класса по умолчанию.
addInitHook( <Function> fn ) Добавляет функцию-перехватчик конструктора к классу.

DG.Evented

Классы, использующие событийную модель (такие как Map и Marker), наследуют методы DG.Evented. В общем случае, класс дает возможность инициировать выполнение последовательности функций, при возникновении какого-либо события, связанного с объектом (например, пользователь щелкнул мышью по карте, тем самым создав событие 'click').

map.on('click', function(e) {
    alert(e.latlng);
} );

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

function onClick(e) { ... }
map.on('click', onClick);
map.off('click', onClick);

Методы

Метод Возвращает Описание
on( <String> type, <Function> fn, <Object> context? ) this Добавляет обработчик (fn) для определенного типа событий. Вы также можете указать контекст вызова обработчика (объект, на который ссылается ключевое слово this внутри обработчика). Также, можно указать несколько типов событий, разделив их пробелами (например: 'click dblclick').
on( <Object> eventMap ) this Добавляет набор пар 'тип/обработчик' в качестве обработчиков событий (например: {click: onClick, mousemove: onMouseMove}).
off( <String> type, <Function> fn?, <Object> context? ) this Удаляет ранее добавленную функцию обработчика событий. Если функция не указана, то у объекта будут удалены все обработчики для данного типа событий. Замечание: если методу on передавался контекст, этот же контекст должен быть передан и методу off, для того чтобы обработчик был удален.
off( <Object> eventMap ) this Удаляет набор пар 'тип/обработчик' обработчиков событий.
off() this Удаляет все обработчики для всех типов событий.
fire( <String> type, <Object> data?, <Boolean> propagate? ) this Инициирует событие определенного типа. Опционально можно передать объект с данными события, который будет передан первым параметром в функцию-обработчик. Также возможно указать, чтобы событие распространилось на родительские объекты.
listens( <String> type ) Boolean Возвращает true, если существуют хотя бы один обработчик для заданного типа событий.
once() this Метод эквивалентен on(…), но обработчик события будет вызван один раз, после чего удален.
addEventParent( <Evented> obj ) this Добавляет объект Evented в качестве получателя событий от текущего объекта.
removeEventParent( <Evented> obj ) this Удаляет объект, ранее добавленный методом addEventParent.
addEventListener() this Псевдоним для on(…)
removeEventListener() this Псевдоним для off(…)
clearAllEventListeners() this Псевдоним для off()
addOneTimeEventListener() this Псевдоним для once(…)
fireEvent() this Псевдоним для fire(…)
hasEventListeners() Boolean Псевдоним для listens(…)

DG.Layer

Все объекты слоев API карт, так или иначе, задействуют методы базового класса DG.Layer. Класс наследует все методы, свойства и событийную модель от DG.Evented.

var layer = DG.Marker(latlng).addTo(map);
layer.addTo(map);
layer.remove();

Опции

Опция Тип Значение
по умолчанию
Описание
pane String 'overlayPane' По умолчанию, слои добавляются в т.н. панель слоев. Поведение по умолчанию можно изменить, переопределив данную опцию.

События

Событие Данные Описание
add Event Возникает после того, как слой будет добавлен к карте.
remove Event Возникает после того, как слой будет удален с карты.
События попапов
Событие Данные Описание
popupopen PopupEvent Возникает при открытии попапа, прикрепленного к данному слою.
popupclose PopupEvent Возникает при закрытии попапа, привязанного к данному слою.

Методы

Метод Возвращает Описание
addTo( <Map> map) this Добавляет слой на карту.
remove() this Удаляет слой с карты, к которой он в данный момент прикреплен.
removeFrom( <Map> map ) this Удаляет слой с карты.
getPane( <String> name? ) HTMLElement Возвращает HTMLElement, представляющий панель на карте с данным именем. Если аргумент name не задан, возвращает панель, в которой находится данный слой.
Методы попапов

Все слои поддерживают набор методов, удобных для связывания с ними попапов.

var layer = DG.Polygon(latlngs).bindPopup('Hi There!').addTo(map);
layer.openPopup();
layer.closePopup();

Попапы автоматически открываются при щелчке мышью по слою, а также закрываются, при удалении слоя или открытии другого попапа.

Метод Возвращает Описание
bindPopup( <String|HTMLElement|Function|Popup> content, <Popup options> options? ) this Связывает попап со слоем и устанавливает необходимые обработчики событий. Если в качестве параметра передать функцию, она получит текущий объект в качестве своего первого аргумента и должна вернуть String или HTMLElement.
unbindPopup() this Удаляет попап, ранее привязанный с помощью bindPopup.
openPopup( <LatLng> latlng? ) this Открывает, связанный со слоем попап, в заданных координатах latlng или в координатах, сохраненных в параметрах самого элемента.
closePopup() this Закрывает, связанный со слоем попап, если он ранее был открыт. Также, может работать как триггер, открывая или закрывая связанный элемент, в зависимости от его предыдущего состояния. Возвращает true, если попап, был открыт в момент вызова метода.
setPopupContent( <String|HTMLElement|Popup> content, <Popup options> options? ) this Задает содержимое попапа, связанного с данным слоем.
getPopup() Popup Возвращает попап, связанный с данным слоем.
Методы расширения

Каждый слой, который наследуется от DG.Layer, должен реализовать следующие методы.

Метод Возвращает Описание
onAdd( <Map> map ) this Должен содержать код, который создает DOM элемент для слоя и добавляет его в одну из панелей карты, а также создает обработчики для соответствующих событий карты. Вызывается из map.addLayer(layer).
onRemove( <Map> map ) this Должен содержать код, который убирает слой и сопутствующие элементы из DOM, а также удаляет обработчики, ранее выставленные в onAdd. Вызывается из map.removeLayer(layer).
getEvents() Object Опциональный метод, который должен возвращать объект вида { viewreset: this._reset }, подходящего для вызова addEventListener. Эти обработчики будут автоматически добавлены и удалены для событий карты вместе с операциями добавления и удаления слоя.
beforeAdd( <Map> map ) this Опциональный метод, который вызывается из map.addLayer(layer), перед тем как слой будет добавлен к карте и инициализированы соответствующие обработчики событий. Объект карты может быть не до конца подготовлен к использованию (не загружены необходимые данные и т.п.) в момент вызова. Поэтому метод можно использовать только для базовой инициализации структур данных слоя.

События, унаследованные от Evented

DG.Control

Базовый класс, от которого наследуют все элементы управления. Обеспечивает позиционирование элементов управления.

Опции

Опция Тип Значение
по умолчанию
Описание
position String 'topright' Местоположение элемента управления (один из углов карты). Возможные значения: 'topleft', 'topright', 'bottomleft' или 'bottomright'

Методы

Метод Возвращает Описание
getPosition() string Возвращает позицию элемента управления.
setPosition( <string> position ) this Задает позицию элемента управления.
getContainer() HTMLElement Возвращает объект HTMLElement, который содержит элемент управления.
addTo( <Map> map ) this Добавляет элемент управления на карту.
remove() this Удаляет элемент управления с карты, на которой он сейчас активен.

DG.Handler

Базовый класс для обработчиков взаимодействия с картой.

Методы

Метод Возвращает Описание
enable() Включает обработчик
disable() Отключает обработчик
enabled() Boolean Возвращает true, если обработчик активен

Методы расширения функционала

Классы, наследующие от Handler, должны реализовывать следующие методы:

Метод Возвращает Описание
addHooks() Вызывается при включении обработчика, должен добавлять обработчики событий.
removeHooks() Вызывается при отключении обработчика, должен удалять обработчики событий.

DG.Projection

Объект для работы с картографической проекцией. Содержит методы для перевода географических координат в координаты на плоскости и обратно.

API карт использует сферическую проекцию Меркатора (EPSG:3857).

Методы

Метод Возвращает Описание
project( <LatLng> latlng ) Point Осуществляет проекцию географических координат на двухмерную координатную плоскость.
unproject( <Point> point ) LatLng Обратная операция от project. Осуществляет проекцию двухмерных координат в плоскости на географические координаты.

Свойства

Свойство Тип Описание
bounds LatLngBounds Географические границы области, в пределах которой возможно осуществление преобразований.

DG.Renderer

Базовый класс, использующийся для реализации движков отображения векторных объектов (DG.SVG, DG.Canvas). В общем случае, используется для отображения геометрических объектов.

Обслуживает операции, связанные с DOM-контейнером, его размерами и анимацией процесса масштабирования. Renderer выступает в качестве неявной группы слоев для всех элементов, которые наследуются от DG.Path. Все векторные элементы используют движок отображения, который может быть задан неявно (и тогда API карт примет решение о том, какой тип движка использовать для отображения) или явно (с помощью опции векторного слоя renderer). Не используйте этот класс напрямую. Используйте классы, которые наследуются от него, такие как DG.SVG или DG.Canvas.

Опции

Опция Тип Значение
Значение по умолчанию
Описание
padding Number 0.1 Насколько расширять границы отсечения выводимых объектов относительно границ окна, в котором отображается карта. Измеряется в относительных единицах, где 0.1 соответствует 10% размера окна в каждом из направлений.

Опции, унаследованные от Layer

Events

События, унаследованные от Layer

Methods

Методы, унаследованные от Layer

Методы, унаследованные от Evented

Объекты событий

Когда класс, унаследованный от Evented, инициирует событие, вызывается функция-обработчик с аргументом, представляющим собой объект с данными о событии, например:

map.on('click', function(ev) {
    alert(ev.latlng); // ev объект с данными о событии (MouseEvent, в данном случае)
});

Информация, которая попадает в функцию обработчик, зависит от типа события:

Event

Базовый объект события и другие объекты событий содержат следующие свойства:

Свойство Тип Описание
type String Тип события (например, 'click').
target Object Объект, который инициировал событие.

MouseEvent

Свойство Тип Описание
latlng LatLng Географические координаты точки, в которой было инициировано событие мыши.
layerPoint Point Пиксельные координаты, в которых было инициировано событие мыши, относительно слоя карты.
containerPoint Point Пиксельные координаты, в которых было инициировано событие мыши, относительно объекта-контейнера карты.
originalEvent DOMMouseEvent Данные оригинального события мыши, инициированного браузером.

Свойства, унаследованные от Event

LocationEvent

Свойство Тип Описание
latlng LatLng Географическое положение пользователя
bounds LatLngBounds Географические границы, в которых находится пользователь (с учетом точности определения местоположения).
accuracy Number Точность определения местоположения в метрах.
altitude Number Высота над поверхностью земли в метрах, согласно координатной системе WGS84.
altitudeAccuracy Number Точность определения высоты в метрах.
heading Number Направление движения в градусах, считается с севера, в направлении по часовой стрелке.
speed Number Скорость в метрах в секунду.
timestamp Number Момент времени измерения местоположения.

Свойства, унаследованные от Event

ErrorEvent

Свойство Тип Описание
message String Сообщение об ошибке.
code Number Код ошибки (если имеется).

Свойства, унаследованные от Event

LayerEvent

Свойство Тип Описание
layer Layer Слой, который был добавлен или удален.

Свойства, унаследованные от Event

LayersControlEvent

Свойство Тип Описание
layer Layer Слой, который был добавлен или удален.
name String Наименовани слоя, который был добавлен или удален.

Свойства, унаследованные от Event

TileEvent

Свойство Тип Описание
tile HTMLElement Элемент тайла (изображение).

Свойства, унаследованные от Event

TileErrorEvent

Свойство Тип Описание
tile HTMLElement Элемент тайла (изображение).

Свойства, унаследованные от Event

ResizeEvent

Свойство Тип Описание
oldSize Point Старый размер, до изменения размера.
newSize Point Новый размер, после изменения размера.

Свойства, унаследованные от Event

GeoJSON event

Свойство Тип Описание
layer Layer Слой GeoJSON объекта, добавленного на карту.
properties Object Опции GeoJSON объекта.
geometryType String Тип геометрии GeoJSON объекта.
id String GeoJSON ID объекта (если задан).

Свойства, унаследованные от Event

Свойство Тип Описание

Свойства, унаследованные от Event

DragEndEvent

Свойство Тип Описание
distance Number Расстояние в пикселях на которое был сдвинут элемент.

MetaEvent

Свойство Тип Описание
latlng LatLng Географические координаты точки объекта допслоя.
meta Object Метаданные объекта допслоя.

LangEvent

Свойство Тип Описание
lang String Текущий язык карты.