Регионы

Иногда на карте требуется выделить какую-нибудь страну или регион. Для того чтобы вручную не создавать каждый объект, описывающий нужную географическую область, можно воспользоваться сервисом «Регионы».

Сервис «Регионы» позволяет добавлять на карту сразу целые области. При этом работать с ними можно как с отдельными объектами: задавать цвет контура и заливки, определять поведение объекта при наведения на него мышкой и т.п.

«Регионы» предоставляют доступ к информации о региональном делении стран, в частности, о координатах границ и названиях единиц административного деления.

Информация о регионах доступна для следующих стран:

• Россия;
• Украина;
• Казахстан;
• Белоруссия.

Для загрузки данных о регионах какой-либо страны предназначена функция regions.load. В качестве параметров следует указать код страны (в формате ISO 3166-1), а также при необходимости дополнительные опции:

• lang — язык, на котором будут отображены названия регионов. Указывается в формате ISO 639-1. По умолчанию принимает значение, указанное в параметре lang при подключении API. В настоящий момент доступны следующие языки:

  • для России: русский;
  • для Украины: русский, украинский;
  • для Казахстана: русский;
  • для Белоруссии: русский, белорусский.

• quality — уровень детализации. Может принимать значение от 0 до 3. Чем выше уровень, тем выше точность отображения региональных границ. По умолчанию принимает значение «0».

  quality = 0	quality = 3

  Разница между уровнями детализации видна только на крупных масштабах. При повышении уровня детализации увеличивается объем загружаемых данных, и, как следствие, возрастает нагрузка на браузер. Поэтому не рекомендуется использовать высокую детализацию для мелкомасштабных карт (например, для обзорной карты).

Когда функция regions.load получает от OSM данные, она обрабатывает их и преобразует в коллекцию GeoObjectCollection, которую затем можно добавить на карту. Ссылка на данную коллекцию находится в поле geoObjects объекта, передаваемого в функцию-обработчик:

ymaps.regions.load('RU', {
    lang: 'ru',
    quality: 1
}).then(function (result) {
    var regions = result.geoObjects; // ссылка на коллекцию GeoObjectCollection
    myMap.geoObjects.add(regions);
}, function () {
    alert('No response');
});

Коллекция GeoObjectCollection является контейнером для объектов GeoObject, которые содержат описания всех регионов страны. Описание каждого региона включает в себя его геометрию, свойства и опции.

Геометрия региона задается в поле geometry и характеризуется геометрическим типом и координатами.

В свойствах указывается метаинформация о регионе, которая была получена от OSM. Свойства региона задаются в поле properties и доступны по следующим ключам:

• osmId — идентификатор региона в OSM;
• hintContent — содержимое всплывающей подсказки, которая будет появляться при наведении курсора на регион. По умолчанию отображается название региона;
• name — название региона на языке, указанном в параметре lang.

Опции отвечают за визуальное отображение региона на карте (цвет заливки, прозрачность и пр.). Они доступны через поле options.

Для того чтобы получить доступ к описанию какого-либо региона, необходимо с помощью метода each или geoquery пройти по всем элементам коллекции и выбрать нужный регион. Ниже рассмотрен пример, в котором из всех регионов России выбирается Иркутская область и для нее задается красный цвет заливки:

// 1 способ: проход по массиву с помощью each.
ymaps.regions.load('RU', {
    lang: 'ru',
    quality: 1
}).then(function (result) {
    var regions = result.geoObjects;
    // Включим возможность перетаскивания регионов.
    regions.options.set('draggable', true);
    // Проходим по коллекции регионов и ищем Иркутскую область (osmId = 145454).
    regions.each(function (reg) {
        if (reg.properties.get('osmId') == 145454) {
            // Меняем цвет на красный
            reg.options.set('fillColor', '#ff001a')
        }
    });

    // Добавляем регионы на карту
    myMap.geoObjects.add(regions); 
 }, function () {
    ...
});

// 2 способ: с помощью geoquery.
ymaps.regions.load('RU', {
    lang: 'ru',
    quality: 1
}).then(function (result) {
    var regions = ymaps.geoquery(result.geoObjects);
    regions.search('properties.osmId = 145454').setOptions('fillColor', '#ff001a');
    regions.addToMap(myMap);
 }, function () {
    ...
});

Осуществлять поиск региона целесообразно по его идентификатору. Поэтому разработчику необходимо предварительно определить, какой идентификатор имеет нужный регион. Ниже приведен самый простой способ, как это сделать:

// При клике на регион показывается его идентификатор.
ymaps.regions.load('RU', {
    lang: 'ru',
    quality: 1
}).then(function (result) {
    result.geoObjects.events.add('click', function (e) {
        var region = e.get('target');
        console.log(region.properties.get('name') + ' -> ' + region.properties.get('osmId'));
    });
    ...
}, function () {
    ...
});

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

Следующий пример демонстрирует, как добавить в DOM-дерево список регионов, загруженных с помощью regions.load. При клике на регион по нему происходит центрирование карты, а цвет его заливки становится розовым. В примере также показано, как скрыть всю оставшуюся часть карты, на которую не добавлены регионы.

Открыть пример в новом окне.