Регионы

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

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

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

Названия стран следует указывать в соответствии со стандартом ISO 3166-1.

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

• Загрузка и использование регионов
  • Координаты регионов
  • Задание стиля для регионов

Загрузка и использование регионов

Информация о регионах может быть загружена с помощью метода YMaps.Regions.load. В этот метод необходимо передать следующие параметры:

• countryCode - код страны в соответствии со стандартом ISO 3166;
• callback - функцию-обработчик ответа;

В обработчик callback передаются два параметра:

• статус запроса;
• данные.

Статус запроса и данные могут содержать различные значения в зависимости от исхода выполнения запроса (см. таблицу ниже).

Пример ниже производит загрузку регионов Украины:

YMaps.Regions.load("ua", function (state, response) {
    if (state == YMaps.State.SUCCESS) {
        map.addOverlay(response);
    } else {
        alert("Во время выполнения запроса произошла ошибка: " + response.error.message)
    }
});

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

Коллекция регионов представляет собой группу, содержащую набор регионов - объектов класса YMaps.Regions.RegionHotspot.

Использование коллекции регионов позволяет создавать один обработчик выбранного события мыши (например, Click) для всего набора регионов. В обработчик события мыши передается три параметра:

• ссылка на объект группы регионов YMaps.Regions.RegionCollection;
• ссылка на объект YMaps.Regions.RegionHotspot, над которым произошло событие;
• ссылка на объект события мыши YMaps.MouseEvent.

// Загрузка регионов для Украины
YMaps.Regions.load("ua", function (state, collection) {
    if (state == YMaps.State.SUCCESS) {
        // Добавляет коллекцию регионов на карту
        map.addOverlay(collection);
    
        YMaps.Events.observe(collection, collection.Events.Click, function (collection, region, mEvent) {
            alert("Вы щелкнули на регионе \"" + region.name + "\"");
        });
    }
});

По умолчанию загруженные регионы подсвечиваются при наведении на них указателя мыши. Это поведение можно изменить, если после загрузки коллекции каждому региону установить параметр highlightRegion в значение false. Параметры для регионов задаются с помощью метода setOptions(). Все допустимые параметры регионов приведены в классе YMaps.Regions.RegionHotspotOptions (в настоящее время доступен только параметр highlightRegion).

YMaps.Regions.load("ua", function (state, response) {
    if (state == YMaps.State.SUCCESS) {

        // Убираем подсветку регионов при наведении указателя мыши
        response.forEach(function (region) {
            region.setOptions({
                highlightRegion: false
            });
        });

        map.addOverlay(response);
    } else {
        alert("Во время выполнения запроса произошла ошибка: " + response.error.message)
    }
});

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

На карту необязательно добавлять сразу все регионы, например, с помощью метода filter() можно отобрать только необходимые и добавить на карту только их:

// Загрузка регионов Украины
YMaps.Regions.load("ua", function (state, response) {
    if (state == YMaps.State.SUCCESS) {
        // Добавляет на карту только Киевскую область 
        var regionKiev = response.filter(function (obj) {
            return obj.name == "Киевская область";
        })[0];
        map.addOverlay(regionKiev);
    } else {
        alert("Во время выполнения запроса произошла ошибка: " + response.error.message)
    }
});

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

Координаты регионов

Координаты границ региона можно получить в двух вариантах:

• в виде массива координат;
• в виде закодированных строк вершин и уровней (см. Кодирование вершин ломаной).

Чтобы получить координаты конкретного региона в виде массива вызовите метод getGeometry(). Данный метод возвращает описание геометрической области в виде массива фигур. Подробнее о формате массива читайте в разделе Активные области.

Границы многоугольников, отображаемых при наведении курсора на регион, заданы с помощью закодированных вершин.

Кодирование позволяет на каждом уровне масштаба отображать только необходимые вершины, поэтому процесс отрисовки многоугольников с закодированными вершинами происходит быстрее.

Чтобы получить доступ к массиву закодированных вершин используйте поле metaDataProperty.encodedShapes. Данное поле содержит массив массивов объектов, соответствующих регионам. У каждого такого объекта два поля:

• coords - строка закодированных вершин многоугольника;
• levels - строка уровней.

Задание стиля для регионов

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

Чтобы задать стиль многоугольника используйте метод setStyle() после загрузки коллекции регионов.

// Загрузка регионов Украины
YMaps.Regions.load("ua", function (state, response) {
    if (state == YMaps.State.SUCCESS) {

        // Задает стиль для коллекции регионов
        response.setStyle({
            polygonStyle : {
                fillColor : "ff9e3f55",
                strokeColor : "ff9e3f"
            },
            hasHint : false
        });

        // Добавляет коллекцию регионов на карту
        map.addOverlay(response);
    } else {
        alert("Во время выполнения запроса произошла ошибка: " + response.error.message)
    }
});

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