Базовые классы
Служебные классы библотеки, необходимые для работы 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(
|
Function |
Возвращает функцию Javascript, являющуюся конструктором класса (в дальнейшем, функция должна вызываться с
new ), который наследует методы и свойства базового класса. |
include(
|
|
Подмешивает методы и свойства объекта в текущий класс. |
mergeOptions(
|
|
Объединяет объект опций с объектом опций класса по умолчанию. |
addInitHook(
|
|
Добавляет функцию-перехватчик конструктора к классу. |
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(
|
this |
Добавляет обработчик (fn ) для определенного типа событий. Вы также можете указать
контекст вызова обработчика (объект, на который ссылается ключевое слово this
внутри обработчика). Также, можно указать несколько типов событий, разделив их пробелами
(например: 'click dblclick' ). |
on(
|
this |
Добавляет набор пар 'тип/обработчик' в качестве обработчиков событий
(например: {click: onClick, mousemove: onMouseMove} ). |
off(
|
this |
Удаляет ранее добавленную функцию обработчика событий. Если функция не указана, то у объекта будут удалены
все обработчики для данного типа событий. Замечание: если методу on передавался
контекст, этот же контекст должен быть передан и методу off , для того чтобы обработчик был удален. |
off(
|
this |
Удаляет набор пар 'тип/обработчик' обработчиков событий. |
off() |
this |
Удаляет все обработчики для всех типов событий. |
fire(
|
this |
Инициирует событие определенного типа. Опционально можно передать объект с данными события, который будет передан первым параметром в функцию-обработчик. Также возможно указать, чтобы событие распространилось на родительские объекты. |
listens(
|
Boolean |
Возвращает true , если существуют хотя бы один обработчик для заданного типа событий. |
once(…) |
this |
Метод эквивалентен on(…) , но обработчик события будет вызван
один раз, после чего удален. |
addEventParent(
|
this |
Добавляет объект Evented в качестве получателя событий от
текущего объекта. |
removeEventParent(
|
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(
|
this |
Добавляет слой на карту. |
remove() |
this |
Удаляет слой с карты, к которой он в данный момент прикреплен. |
removeFrom(
|
this |
Удаляет слой с карты. |
getPane(
|
HTMLElement |
Возвращает HTMLElement , представляющий панель на карте с данным именем.
Если аргумент name не задан, возвращает панель, в которой находится данный слой. |
Методы попапов
Все слои поддерживают набор методов, удобных для связывания с ними попапов.
var layer = DG.Polygon(latlngs).bindPopup('Hi There!').addTo(map);
layer.openPopup();
layer.closePopup();
Попапы автоматически открываются при щелчке мышью по слою, а также закрываются, при удалении слоя или открытии другого попапа.
Метод | Возвращает | Описание |
---|---|---|
bindPopup(
|
this |
Связывает попап со слоем и устанавливает необходимые обработчики событий.
Если в качестве параметра передать функцию, она получит текущий объект в качестве своего
первого аргумента и должна вернуть String или HTMLElement . |
unbindPopup() |
this |
Удаляет попап, ранее привязанный с помощью bindPopup . |
openPopup(
|
this |
Открывает, связанный со слоем попап, в заданных координатах
latlng
или в координатах, сохраненных в параметрах самого элемента. |
closePopup() |
this |
Закрывает, связанный со слоем попап, если он ранее был открыт. Также, может работать
как триггер, открывая или закрывая связанный элемент, в зависимости от его предыдущего состояния.
Возвращает true , если попап, был открыт в момент вызова метода. |
setPopupContent(
|
this |
Задает содержимое попапа, связанного с данным слоем. |
getPopup() |
Popup |
Возвращает попап, связанный с данным слоем. |
Методы расширения
Каждый слой, который наследуется от DG.Layer
, должен реализовать следующие методы.
Метод | Возвращает | Описание |
---|---|---|
onAdd(
|
this |
Должен содержать код, который создает DOM элемент для слоя и добавляет его в одну из панелей карты,
а также создает обработчики для соответствующих событий карты. Вызывается из
map.addLayer(layer) . |
onRemove(
|
this |
Должен содержать код, который убирает слой и сопутствующие элементы из DOM, а также удаляет обработчики,
ранее выставленные в onAdd . Вызывается из
map.removeLayer(layer) . |
getEvents() |
Object |
Опциональный метод, который должен возвращать объект вида { viewreset: this._reset } ,
подходящего для вызова addEventListener .
Эти обработчики будут автоматически добавлены и удалены для событий карты вместе с операциями добавления
и удаления слоя. |
beforeAdd(
|
this |
Опциональный метод, который вызывается из map.addLayer(layer) ,
перед тем как слой будет добавлен к карте и инициализированы соответствующие обработчики событий.
Объект карты может быть не до конца подготовлен к использованию (не загружены необходимые данные и т.п.)
в момент вызова. Поэтому метод можно использовать только для базовой инициализации структур данных слоя. |
События, унаследованные от Evented
DG.Control
Базовый класс, от которого наследуют все элементы управления. Обеспечивает позиционирование элементов управления.
Опции
Опция | Тип | Значение по умолчанию |
Описание |
---|---|---|---|
position |
String |
'topright' |
Местоположение элемента управления (один из углов карты). Возможные значения: 'topleft' ,
'topright' , 'bottomleft' или 'bottomright' |
Методы
Метод | Возвращает | Описание |
---|---|---|
getPosition() |
string |
Возвращает позицию элемента управления. |
setPosition(
|
this |
Задает позицию элемента управления. |
getContainer() |
HTMLElement |
Возвращает объект HTMLElement, который содержит элемент управления. |
addTo(
|
this |
Добавляет элемент управления на карту. |
remove() |
this |
Удаляет элемент управления с карты, на которой он сейчас активен. |
DG.Handler
Базовый класс для обработчиков взаимодействия с картой.
Методы
Метод | Возвращает | Описание |
---|---|---|
enable() |
|
Включает обработчик |
disable() |
|
Отключает обработчик |
enabled() |
Boolean |
Возвращает true , если обработчик активен |
Методы расширения функционала
Классы, наследующие от Handler
, должны реализовывать следующие методы:
Метод | Возвращает | Описание |
---|---|---|
addHooks() |
|
Вызывается при включении обработчика, должен добавлять обработчики событий. |
removeHooks() |
|
Вызывается при отключении обработчика, должен удалять обработчики событий. |
DG.Projection
Объект для работы с картографической проекцией. Содержит методы для перевода географических координат в координаты на плоскости и обратно.
API карт использует сферическую проекцию Меркатора (EPSG:3857).
Методы
Метод | Возвращает | Описание |
---|---|---|
project(
|
Point |
Осуществляет проекцию географических координат на двухмерную координатную плоскость. |
unproject(
|
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
Popup event
Свойство | Тип | Описание |
---|---|---|
popup |
Popup |
Попап, который был открыт или закрыт. |
Свойства, унаследованные от Event
DragEndEvent
Свойство | Тип | Описание |
---|---|---|
distance |
Number |
Расстояние в пикселях на которое был сдвинут элемент. |
MetaEvent
Свойство | Тип | Описание |
---|---|---|
latlng |
LatLng |
Географические координаты точки объекта допслоя. |
meta |
Object |
Метаданные объекта допслоя. |
LangEvent
Свойство | Тип | Описание |
---|---|---|
lang |
String |
Текущий язык карты. |