hotspot.ObjectSource

Расширяет IHotspotObjectSource.

Стандартная реализация интерфейса IHotspotObjectSource. Работает со стандартным форматом ответа сервера.

Конструктор | Поля | События | Методы

Конструктор

hotspot.ObjectSource(tileUrlTemplate[, keyTemplate[, options]])

Возвращает источник данных для слоя активных областей.

Параметры:

Параметр

Значение по умолчанию

Описание

tileUrlTemplate*

Тип: String|Function

Возвращает шаблон URL данных для тайла. Поддерживаются специальные конструкции и возможность использования функции по аналогии с Layer.

keyTemplate

Тип: String|Function

Шаблон идентификатора тайла. Используется для формирования padding в JSONP-запросе за данными тайла. Задается по аналогии с предыдущим параметром. Все символы, не являющиеся буквой, цифрой или символом '', будут заменены на ''. Если параметр не задан, то padding jsonp-запроса будет сгенерирован автоматически. Примеры преобразований при tileNumber=[3, 1], zoom=9:

  • 'myCallback=%x' => 'myCallback_3'
  • '%c' => 'x_3_y_1_z_9'
  • 'callback2_%c' => 'callback2_x_3_y_1_z_9'
  • 'callback%test' => 'callback_test'

options

Тип: Object

Опции источника данных.

options.bounds

null

Тип: Bounds

Область на карте, для которой есть данные, или null, если данные есть везде. Опция для стандартной реализации метода restrict.

options.maxZoom

0

Тип: Bounds

Максимальный уровень масштабирования, для которого делаются запросы за данными. Опция для стандартной реализации метода restrict.

options.minZoom

0

Тип: Bounds

Минимальный уровень масштабирования, для которого делаются запросы за данными. Опция для стандартной реализации метода restrict.

options.noCache

false

Тип: Boolean

false — использовать встроенный кэш браузера, true — не использовать (к каждому URL будет автоматически приписываться случайный GET-параметр, чтобы исключить кэширование тайлов браузером).

* Обязательный параметр/опция.

Пример:

// Пример стандартного формата ответа сервера.
hotspot_callback({
     // Ответ может содержать поле "data" или "error".
    "data": {
        "type": "FeatureCollection",
        // Массив активных областей.
        "features": [{
            "type": "Feature",
            // Данные объекта.
            // Передаются в конструктор hotspot.layer.Object в качестве данных.
            "properties": {
                "hintContent": "Содержимое всплывающей подсказки.",
                "balloonContentBody": "Содержимое балуна.",
                "balloonContentHeader": "Заголовок балуна.",
                "balloonContentFooter": "Нижняя часть балуна.",
               // Можно задавать свойство balloonContent вместо Body/Header/Footer

                // Обязательное поле, описывающее hotspot.layer.Object.
                "HotspotMetaData": {
                    // Идентификатор активной области.
                    // hotspot.layer.Object.getId по умолчанию возвращает значение этого поля.
                    "id": 10469893,
                    "zIndex": 10,
                   // Данные, на основе которых создается геометрияhotspot.layer.Object.
                    // Обязательное поле.
                    // Стандартная реализация позволяет передавать следующие типы геометрий: 
                    //    "Rectangle" - прямоугольник.
                    //      Будет создана геометрия geometry.pixel.Rectangle.
                    //    "Polygon" - многоконтурный многоугольник.
                    //       Будет создана геометрия geometry.pixel.Polygon.
                    //    "MultiPolygon" - сложная фигура, состоящая из нескольких многоконтурных многоугольников.
                    //      Будет создана геометрия geometry.pixel.MultiPolygon.
                    //    "ConvexPolygon" - многоконтурный многоугольник. Все контуры должны быть выпуклыми. Все контуры должны быть выпуклыми.
                    //     Работает быстрее, чем "Polygon".
                    //       Будет создана геометрия geometry.pixel.Polygon.
                    //    "MultiConvexPolygon" - сложная фигура, состоящая из нескольких многоконтурных многоугольников.
                    Все контуры должны быть выпуклыми. Работает быстрее, чем "MultiPolygon".
                    //      Будет создана геометрия geometry.pixel.MultiPolygon.
                    "RenderedGeometry": {
                        "type": "Polygon",
                        // Координаты передаются в пиксельных координатах, отсчитываемых от верхнего левого угла тайла.
                        "coordinates": [
                            // Первый контур многоугольника.
                            [
                                [-315, 280], [32, 442], [141, 208], [-206, 46], [-315, 280]
                            ],
                            // Второй контур многоугольника.
                            [
                                [-186, 155], [-238, 265], [-152, 306], [-100, 196], [-186, 155]
                            ]
                        ]
                    }
                }
            },
            // Фактическая геометрия объекта.
            // Необязательное поле;
            // Передается в hotspot.layer.Object и доступна через метод hotspot.layer.Object.getGeometry.
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    // Первый контур многоугольника.
                    [
                        [29.176096525, 40.904183940],
                        [29.177027467, 40.903854324],
                        [29.177319900, 40.904329679],
                        [29.176389040, 40.904659406],
                        [29.176096525, 40.904183940]
                    ],
                    // Второй контур многоугольника.
                    [
                        [29.176442530, 40.904437683],
                        [29.176303055, 40.904213830],
                        [29.176533525, 40.904131168],
                        [29.176673032, 40.904355010],
                        [29.176442530, 40.904437683]
                    ]
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                // Описание следующей активной области.
            }        }]    }});

Поля

Имя

Тип

Описание

events

IEventManager

Менеджер событий.

Унаследовано от IEventEmitter.

options

IOptionManager

Менеджер опций.

Унаследовано от ICustomizable.

События

Имя

Описание

optionschange

Изменение в опциях объекта.

Унаследовано от ICustomizable.

Методы

Имя

Возвращает

Описание

cancelLastRequest()

Отменяет последний запрос за данными.

Унаследован от IHotspotObjectSource.

getKey(tileNumber, zoom)

String

Возвращает имя callback-функции (padding) в JSONP-запросе, если оно статическое, либо null, если можно использовать динамический JSONP-callback. Шаблоны поддерживают те же подстановки, что и в шаблоне url тайла. Все символы, не являющиеся буквой, цифрой или символом '', будут заменены на ''.

getKeyTemplate()

String

Возвращает шаблон идентификатора тайла.

getTileUrl(tileNumber, zoom)

String

Возвращает URL данных для конкретного тайла.

getTileUrlTemplate()

String

Возвращает шаблон URL данных для тайла.

parseResponse(layer, res, callback, tileNumber, zoom)

Разбирает ответ сервера. Возвращает в callback массив объектов-активных областей, сформированных по JSON-описанию.

requestObjects(layer, tileNumber, zoom, callback)

Строит массив объектов IHotspotLayerObject, соответствующих определенному слою, тайлу и коэффициенту масштабирования карты, и передает его в функцию callback.

Унаследован от IHotspotObjectSource.

restrict(layer, tileNumber, zoom)

Boolean

Метод, который вызывается перед тем, как отправить запрос за данными для тайла. Если метод возвращает true, то запрос на сервер посылаться не будет, и в качестве ответа вернется пустой массив объектов. Стандартная реализация метода проверяет, лежит ли параметр zoom в пределах [options.minZoom, options.maxZoom]. А также проверяет, попадает ли центр запрашиваемого тайла в указанные options.bounds. Если options.bounds=null, то проверка для этого параметра не осуществляется.

setKeyTemplate(template)

Задает новый шаблон идентификатора тайла.

setTileUrlTemplate(template)

Задает новый шаблон URL данных для тайла.

Описание методов

getKey

{String} getKey(tileNumber, zoom)

Возвращает имя callback-функции (padding) в JSONP-запросе, если оно статическое, либо null, если можно использовать динамический JSONP-callback. Шаблоны поддерживают те же подстановки, что и в шаблоне url тайла. Все символы, не являющиеся буквой, цифрой или символом '', будут заменены на ''.

Возвращает идентификатор тайла. Используется для формирования padding в JSONP-запросе за данными тайла.

Параметры:

Параметр

Значение по умолчанию

Описание

tileNumber*

Тип: Number[]

Номер тайла (тайловые координаты).

zoom*

Тип: Integer

Уровень масштабирования.

* Обязательный параметр/опция.

getKeyTemplate

{String} getKeyTemplate()

Возвращает шаблон идентификатора тайла.

getTileUrl

{String} getTileUrl(tileNumber, zoom)

Возвращает URL данных для конкретного тайла.

Параметры:

Параметр

Значение по умолчанию

Описание

tileNumber*

Тип: Number[]

Номер тайла (тайловые координаты).

zoom*

Тип: Integer

Уровень масштабирования.

* Обязательный параметр/опция.

Пример:

var hotspotObjectSource = new ymaps.hotspot.ObjectSource('dataSource/?%c');
hotspotObjectSource.getTileUrl = function (tileNumber, zoom) {
    if (zoom > 10) {
        // Для крупных масштабов используем выставленный путь к данным.
        return ymaps.hotspot.ObjectSource.prototype.call(this, tileNumber, zoom);
     } else {
        // Для мелких масштабов используем другой путь.
        return 'otherSource/getHotspots.xml?z=' + zoom + '<codeph>&</codeph>x=' + tileNumber[0] + '<codeph>&</codeph>y=' + tileNumber[1];
     }
};

getTileUrlTemplate

{String} getTileUrlTemplate()

Возвращает шаблон URL данных для тайла.

parseResponse

{} parseResponse(layer, res, callback, tileNumber, zoom)

Разбирает ответ сервера. Возвращает в callback массив объектов-активных областей, сформированных по JSON-описанию.

Параметры:

Параметр

Значение по умолчанию

Описание

layer*

Тип: hotspot.Layer

Слой, которому принадлежат объекты.

res*

Тип: Object

Ответ сервера.

callback*

Тип: Function

Функция-обработчик.

tileNumber*

Тип: Number[]

Номер тайла, для которого пришел ответ.

zoom*

Тип: Number

Коэффициент масштабирования, для которого пришел ответ. массива объектов.

* Обязательный параметр/опция.

restrict

{Boolean} restrict(layer, tileNumber, zoom)

Метод, который вызывается перед тем, как отправить запрос за данными для тайла. Если метод возвращает true, то запрос на сервер посылаться не будет, и в качестве ответа вернется пустой массив объектов. Стандартная реализация метода проверяет, лежит ли параметр zoom в пределах [options.minZoom, options.maxZoom]. А также проверяет, попадает ли центр запрашиваемого тайла в указанные options.bounds. Если options.bounds=null, то проверка для этого параметра не осуществляется.

Возвращает true - тайл вышел за пределы области данных (для данного тайла данных нет), false - не вышел (данные есть).

Параметры:

Параметр

Значение по умолчанию

Описание

layer*

Тип: hotspot.Layer

Слой активных областей.

tileNumber*

Тип: Number[]

Номер тайла.

zoom*

Тип: Integer

Уровень масштабирования.

* Обязательный параметр/опция.

Пример:

// Пример переопределения метода "restrict"
// Предположим, что есть только данные по Мурманску и Новосибирску.
var myMap = new ymaps.Map('map', {center: [32.5, 68.9] , zoom: 9});
var geoBounds = [
    [[31.729958, 69.369182], [34.203324, 68.666473]], // Murmansk
    [[82.179084, 55.341085], [83.725642, 54.670738]]  // Novosibirsk
];
var projection = myMap.options.get('projection');
var myHotspotSource = new ymaps.hotspot.ObjectSource('http://www.myDomain.ru/tiles/?%c', '%c');

myHotspotSource.restrict = function(layer, tileNumber, zoom) {
    // Вычисление пиксельных границ городов для данного уровня масштабирования.
    var boundsFromPoints = ymaps.util.bounds.fromPoints;
    var toGlobalPixels = projection.toGlobalPixels;
    var pixelBounds = [
        boundsFromPoints(
            toGlobalPixels(geoBounds[0][0], zoom),
            toGlobalPixels(geoBounds[0][1], zoom)
        ),
        boundsFromPoints(
            toGlobalPixels(geoBounds[1][0], zoom),
            toGlobalPixels(geoBounds[1][1], zoom)
        )
    ];

    // Вычисление границ пикселей плитки
    var leftTop = [tileNumber[0] * 256, tileNumber[1] * 256];
    var tileBounds = [leftTop, [leftTop[0] + 256, leftTop[1] + 256]];
    var intersects = ymaps.util.bounds.intersects;
    // Если границы пикселей тайла пересекаются с границами пикселей указанных областей,
    // мы должны отправить запрос на получение данных.
    if (intersects(pixelBounds[0], tileBounds) || (intersects(pixelBounds[1], tileBounds))) {
        return false;
    }

    // Для всех остальных тайлов этот источник не содержит никаких данных.
    return true;
}

setKeyTemplate

{} setKeyTemplate(template)

Задает новый шаблон идентификатора тайла.

Параметры:

Параметр

Значение по умолчанию

Описание

template*

Тип: String

Шаблон идентификатора.

* Обязательный параметр/опция.

setTileUrlTemplate

{} setTileUrlTemplate(template)

Задает новый шаблон URL данных для тайла.

Параметры:

Параметр

Значение по умолчанию

Описание

template*

Тип: String

Шаблон URL

* Обязательный параметр/опция.

Предыдущая
Следующая