Документация
Справочник JavaScript API
2.1.64 (текущая версия)
collection
interactivityModel
Интерфейсы

hotspot.ObjectSource

Расширяет IHotspotObjectSource.

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

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

Конструктор

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

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

Параметры:

ПараметрЗначение по умолчаниюОписание
tileUrlTemplate *
[no-highlight[

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

]no-highlight]

Тип: 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 *
[no-highlight[

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

]no-highlight]

Тип: Number[]

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

zoom *
[no-highlight[

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

]no-highlight]

Тип: Integer

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

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

getKeyTemplate

{String} getKeyTemplate()

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

getTileUrl

{String} getTileUrl(tileNumber, zoom)

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

Параметры:

ПараметрЗначение по умолчаниюОписание
tileNumber *
[no-highlight[

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

]no-highlight]

Тип: Number[]

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

zoom *
[no-highlight[

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

]no-highlight]

Тип: 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>&amp;</codeph>x=' + tileNumber[0] + '<codeph>&amp;</codeph>y=' + tileNumber[1]';
     }
};

getTileUrlTemplate

{String} getTileUrlTemplate()

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

parseResponse

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

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

Параметры:

ПараметрЗначение по умолчаниюОписание
layer *
[no-highlight[

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

]no-highlight]

Тип: hotspot.Layer

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

res *
[no-highlight[

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

]no-highlight]

Тип: Object

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

callback *
[no-highlight[

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

]no-highlight]

Тип: Function

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

tileNumber *
[no-highlight[

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

]no-highlight]

Тип: Number[]

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

zoom *
[no-highlight[

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

]no-highlight]

Тип: Number

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

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

restrict

{Boolean} restrict(layer, tileNumber, zoom)

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

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

Параметры:

ПараметрЗначение по умолчаниюОписание
layer *
[no-highlight[

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

]no-highlight]

Тип: hotspot.Layer

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

tileNumber *
[no-highlight[

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

]no-highlight]

Тип: Number[]

Номер тайла.

zoom *
[no-highlight[

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

]no-highlight]

Тип: Integer

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

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

Пример:

// Пример переопределения метода restrict.
// Допустим, что данные есть только для Мурманска и Новосибирска.
var myMap = new ymaps.Map('map', {center: [32.5, 68.9] , zoom: 9}),
    geoBounds = [
         [[31.729958, 69.369182], [34.203324, 68.666473]], // Мурманск
         [[82.179084, 55.341085], [83.725642, 54.670738]]  // Новосибирск
    ],
    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,
       toGlobalPixels = projection.toGlobalPixels,
       pixelBounds = [
           boundsFromPoints(
               toGlobalPixels(geoBounds[0][0]], zoom),
               toGlobalPixels(geoBounds[0][1]], zoom)
           ),
           boundsFromPoints(
               toGlobalPixels(geoBounds[1][0]], zoom),
               toGlobalPixels(geoBounds[1][1]], zoom)
           )
      ],

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

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

setKeyTemplate

{} setKeyTemplate(template)

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

Параметры:

ПараметрЗначение по умолчаниюОписание
template *
[no-highlight[

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

]no-highlight]

Тип: String

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

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

setTileUrlTemplate

{} setTileUrlTemplate(template)

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

Параметры:

ПараметрЗначение по умолчаниюОписание
template *
[no-highlight[

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

]no-highlight]

Тип: String

Шаблон URL

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