Пользовательские слои

• Введение
• Основы
  • Пользовательские слои
  • Группы слоев
  • Менеджер слоев
• Класс слоя DG.Layers.Common
  • Конструктор
  • Методы
    • Получить идентификатор слоя
    • Скрыть слой
    • Показать слой
    • Установить URL пустого тайла
    • Получить URL пустого тайла
• Класс менеджера слоев DG.Layers
  • Методы управления группами слоев
    • Создать группу
    • Удалить группу
    • Получить список имен групп
    • Получить уже созданный объект группы по ее имени
    • Получить имя группы по умолчанию
    • Получить объект группы по умолчанию
  • Методы управления слоями
    • Добавить слой
    • Удалить слой
    • Получить список всех слоев
    • Получить слой по его идентификатору
    • Удалить все слои
• Класс группы слоев DG.LayerGroup
  • Методы
    • Добавить слой в группу
    • Удалить слой из группы
    • Получить список всех слоев в группе
    • Получить слой по его идентификатору в группе
    • Удалить все слои из группы
    • Скрыть группу
    • Отобразить группу
    • Получить количество слоев в группе
    • Проверить наличие слоя в группе
    • Получить порядковый номер слоя в группе
    • Выполнить операцию для каждого слоя в группе
    • Получить имя группы

Введение

API карт позволяет накладывать пользовательские слои поверх слоя географической карты. Это дает возможность отображать на карте практически любые объекты, маршруты, области. Например, легко показать зоны покрытия города интернет-провайдерами, или же в графическом виде отобразить области доставки магазина или пиццерии с указанием времени и стоимости доставки. Так же можно указать путь проезда к вашим офисам или маршрут экскурсии по городу. Одним словом, возможности ограничены лишь фантазией.

Предполагается, что вы уже ознакомились с разделами «Быстрый старт» и «Карта».

Основы

Пользовательские слои

Рассмотрим пример создания слоя:

// Создаем слой с указанием источника тайлов:
var myLayer = new DG.Layers.Common('myName', 'http://example.com/${z}/${x}/${y}.png');
 
// Добавим слой на карту:
myMap.layers.add(myLayer, 'myGroup');

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

В дальнейшем мы рассмотрим класс DG.Layers.Common подробнее.

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

Группы слоев

Каждый слой должен принадлежать определенной группе. Это дает возможность выполнять групповые операции.

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

Объект группы предоставляет наиболее полный арсенал методов, для управления слоями.

Любые операции со слоями в группе сразу же отображаются на карте.

Менеджер слоев

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

При этом, для удобства, часть методов по работе со слоями есть также и в менеджере.

Менеджер слоев доступен как свойство layers объекта карты:

// Инициализируем объект карты:
var myMap = new DG.Map("myMapId");
 
// Менеджер слоев:
myMap.layers;

Класс слоя DG.Layers.Common

Ниже мы подробно рассмотрим конструктор и все методы класса слоя. Для наглядности, допустим myLayer - объект слоя.

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

Конструктор

Параметры:

Имя	Тип	Обязательный	Описание
name	String	Да	Имя слоя
url	String	Да	Шаблон адреса тайлового сервера в виде http://example.com/${z}/${x}/${y}.png, где {z} - коэффициент масштабирования, {x} - номер тайла по горизонтали, {y} - номер тайла по вертикали.
options.opacity	Number	Нет	Прозрачность слоя. Задается в диапазоне 0.0 (полная прозрачность) - 1.0 (без эффекта прозрачности)
options.transitionEffect	String | null	Нет	Визуальный эффект изменения размера тайла в процессе изменения масштаба. Как только новые тайлы становятся доступными - они отображаются поверх предыдущих тайлов. Допустимые значения: resize и null. По умолчанию: null - визуального эффекта нет.
options.countTileServers	Number	Нет	Количество субдоменов для тайлого сервера. У браузеров есть ограничение на количество одновременно скачиваемых файлов с одного домена. Чтобы обойти это ограничение можно загружать тайлы с нескольких поддоменов. Для оптимальной скорости загрузки карты, мы настоятельно рекомендуем устанавливать это значение равным 4. Параметр используется совместно с параметром options.tilePrefix. По умолчанию, options.countTileServers равен нулю - тайлы загружаются с одного сервера.
options.tilePrefix	String	Нет	Префикс имени субдомена тайлового сервера. Например, у параметр url равен http://example.com/${z}/${x}/${y}.png. Если вы определяете options.tilePrefix как mytile - получаем URL субдоменов тайлового сервера в виде: http://mytile1.example.com/, http://mytile2.example.com/, http://mytile3.example.com/ и так далее, в зависимости от параметра options.countTileServers. Поэтому параметр используется совместно с параметром options.tilePrefix.

Пример:

// Задаем необязательный параметр - объект дополнительных опций:
var options = {
    opacity: 0.8,
    transitionEffect: 'resize',
    countTileServers: 4,
    tilePrefix: 'mytile'
};
// Создаем слой:
var myLayer = new DG.Layers.Common('myName', 'http://example.com/${z}/${x}/${y}.png', options);
//Добавляем слой на карту:
myMap.layers.add(myLayer);

Методы

Получить идентификатор слоя

myLayer.getId()

Возвращает:

Тип	Описание
String	Возвращает уникальный идентификатор слоя, который генерируется в момент его создания.

Скрыть слой

myLayer.hide()

Показать слой

myLayer.show()

Установить URL пустого тайла

myLayer.setURLErrorImage(url)

Параметры:

Имя	Тип	Обязательный	Описание
url	String	Да	URL пользовательского тайла, который будет отображаться при отсутствии запрашиваемого с сервера тайла (например - http://example.com/image/errortile.png)

Получить URL пустого тайла

myLayer.getURLErrorImage()

Возвращает:

Тип	Описание
String	URL пользовательского тайла, который будет отображаться при отсутствии запрашиваемого с сервера тайла

Класс менеджера слоев DG.Layers

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

При этом, для удобства, часть методов по работе со слоями есть также и в менеджере.

Ниже мы подробно рассмотрим все методы класса менеджера. Для наглядности, допустим myMap - объект карты.

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

Создать менеджер слоев явно через ключевое слово new нельзя. Он автоматически доступен как свойство layers объекта карты.

Методы управления группами слоев

Создать группу

myMap.layers.createGroup(groupName)

Параметры:

Имя	Тип	Обязательный	Описание
groupName	String	Да	Название группы. Должно быть уникальным.

Возвращает:

Тип	Описание
DG.LayerGroup	Экземпляр класс DG.LayerGroup

Удалить группу

myMap.layers.removeGroup(groupName)

Параметры:

Имя	Тип	Обязательный	Описание
groupName	String	Да	Название группы.

Получить список имен групп

myMap.layers.getAllGroupsNames()

Возвращает:

Тип	Описание
Array	Список имен групп. Массив строк.

Получить уже созданный объект группы по ее имени

myMap.layers.getGroup(groupName)

Параметры:

Имя	Тип	Обязательный	Описание
groupName	String	Да	Название группы.

Возвращает:

Тип	Описание
DG.LayerGroup | null	Экземпляр класс DG.LayerGroup, который уже был создан с помощью метода myMap.layers.createGroup. Если запросить у метода несуществующую группу, возвращает null.

Получить имя группы по умолчанию

myMap.layers.getDefaultGroupName()

Возвращает:

Тип	Описание
String	Название группы по умолчанию, которая есть всегда.

Получить объект группы по умолчанию

myMap.layers.getDefaultGroup()

Возвращает:

Тип	Описание
DG.LayerGroup	Объект группы по умолчанию, который есть всегда.

Особенности:

Фактически данный метод, является короткой записью выражения:

myMap.layers.getGroup(myMap.layers.getDefaultGroupName())

Методы управления слоями

Добавить слой

myMap.layers.add(layer, groupName)

Параметры:

Имя	Тип	Обязательный	Описание
layer	DG.Layers.Common	Да	Слой. Экземпляр класса DG.Layers.Common
groupName	String	Нет	Название группы. Если параметр не передан, слой будет добавлен в группу по умолчанию. Если название группы новое, автоматически будет создана новая группа с переданным именем. Ограничение: нельзя добавлять один и тот же слой дважды, во-первых, в одну группу, а во-вторых, в несколько групп сразу.

Удалить слой

myMap.layers.remove(item)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Layers.Common | String	Да	Может быть либо объектом слоя, либо его идентификатором. Для получения идентификатора у слоя есть метод getId().

Получить список всех слоев

myMap.layers.getAll()

Возвращает:

Тип	Описание
Array	Массив состоящий из экземпляров класса DG.Layers.Common.

Получить слой по его идентификатору

myMap.layers.get(id)

Параметры:

Имя	Тип	Обязательный	Описание
id	String	Да	Идентификатор слоя. Для его получения у слоя есть метод getId().

Удалить все слои

myMap.layers.removeAll()

Особенности:

При этом, хоть все слои и удаляются, группы остаются не тронутыми.

Класс группы слоев DG.LayerGroup

Объект группы предоставляет наиболее полный арсенал методов, для управления cлоями.

Ниже мы подробно рассмотрим все методы класса группы слоев. Для наглядности, допустим myGroup - объект группы.

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

Создать группу слоев явно через ключевое слово new нельзя. Правильно это делать с помощью метода createGroup менеджера слоев.

Методы

Добавить слой в группу

myGroup.add(item, index)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Layers.Common	Да	Слой. Экземпляр класса DG.Layers.Common
index	Number	Нет	Порядковый номер добавляемого слоя в группе. При этом нумерация слоев происходит с нуля. Если параметр не передан, слой будет добавлен в конец группы. Ограничение: значение должно быть целым неотрицательным числом не превышающим текущее кол-во слоев в группе.Таким образом обеспечивается непрерывная нумерация элементов в группе.

Удалить слой из группы

myGroup.remove(item)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Layers.Common	Да	Слой. Экземпляр класса DG.Layers.Common

Получить список всех слоев в группе

myGroup.getAll()

Возвращает:

Тип	Описание
Array	Массив состоящий из экземпляров класса DG.Layers.Common.

Получить слой по его идентификатору в группе

myGroup.get(id)

Параметры:

Имя	Тип	Обязательный	Описание
id	String	Да	Идентификатор слоя. Для его получения у слоя есть метод getId().

Удалить все слои из группы

myGroup.removeAll()

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

Скрыть группу

myGroup.hide()

При этом все слои в группе становятся невидимыми. Более того, при добавлении новых слоев, они также остаются невидимыми.

Отобразить группу

myGroup.show()

Отменяет действие метода myGroup.hide(), все слои в группе становятся видимыми.

Получить количество слоев в группе

myGroup.length()

Возвращает:

Тип	Описание
Number	Возвращает количество слоев в группе.

Проверить наличие слоя в группе

myGroup.contains(item)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Layers.Common	Да	Слой. Экземпляр класса DG.Layers.Common

Возвращает:

Тип	Описание
Boollean	Возвращает true, если слой содержится в группе. В противном случае — false.

Получить порядковый номер слоя в группе

myGroup.indexOf(item)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Layers.Common	Да	Слой. Экземпляр класса DG.Layers.Common

Возвращает:

Тип	Описание
Number | null	Возвращает порядковый номер слоя в группе. Нумерация начинается с нуля. Если слоя нет в группе, возвращает null.

Выполнить операцию для каждого слоя в группе

myGroup.forEach(callback, context)

Параметры:

Имя	Тип	Обязательный	Описание
callback	Function	Да	Сallback-функция, вызываемая для каждого элемента в группе. Функция вызывается со следующими параметрами callback(layer, index, group), где: layer — текущий слой, index — порядковый номер текущего слоя (нумерация начинается с нуля), group — объект группы myGroup.
context	Object	Нет	Контекст выполнения callback-функции. Другими словами, что будет скрываться за ключевым словом this внутри callback-функции. Если параметр не передан, по умолчанию this равен глобальному объекту window.

Получить имя группы

myGroup.getName()

Возвращает:

Тип	Описание
String	Возвращает имя группы, которое задается в конструкторе группы при ее создании.