API карт

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

Служебные классы библотеки, необходимые для работы 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`	Объект, который инициировал событие.