hotspot.ObjectSource

Расширяет IHotspotObjectSource.

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

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

Конструктор

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

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

Параметры:

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

Тип: String|Function

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

keyTemplate-Function

Тип: String

Шаблон идентификатора тайла. Используется для формирования padding в jsonp-запросе за данными. Задается по аналогии с предыдущим параметром. Все символы, не являющиеся буквой, цифрой или символом '_', будут заменены на '_'. Если параметр не задан, то padding запроса будет сгенерирован автоматически. Примеры преобразований при 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-параметр, чтобы исключить кэширование тайлов браузером).

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

Тип: String|Function

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

keyTemplate-Function

Тип: String

Шаблон идентификатора тайла. Используется для формирования padding в jsonp-запросе за данными. Задается по аналогии с предыдущим параметром. Все символы, не являющиеся буквой, цифрой или символом '_', будут заменены на '_'. Если параметр не задан, то padding запроса будет сгенерирован автоматически. Примеры преобразований при 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.Shape в качестве данных.
            "properties": {
                "hintContent": "Содержимое текстовой подсказки.",
                "balloonContentBody": "Содержимое балуна.",
                "balloonContentHeader": "Заголовок балуна.",
                "balloonContentFooter": "Нижняя часть балуна.",
                // Можно задавать свойство balloonContent вместо Body/Header/Footer

                // Обязательное поле, описывающее hotspot.Shape.
                "HotspotMetaData": {
                    // Идентификатор хотспотного объекта.
                    // hotspot.Shape.getId по умолчанию возвращает значение этого поля.
                    "id": 10469893,
                    "zIndex": 10,
                    // Данные, на основе которых создается геометрия hotspot.Shape.
                    // Обязательное поле.
                    // Стандартная реализация позволяет передавать следующие типы геометрий:
                    //    "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.Shape и доступна через метод hotspot.Shape.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": {
                // описание следующего хотспотного объекта...
            }
        }]
    }
});

Поля

Имя Тип Описание
options IOptionManager

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

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

Имя Тип Описание
options IOptionManager

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

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

События

Имя Описание
optionschange

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

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

Имя Описание
optionschange

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

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

Методы

Имя Возвращает Описание
cancelLastRequest()

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

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

getKey(tileNumber, zoom)

String

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

getKeyTemplate()

String

Returns шаблон идентификатора тайла.

getTileUrl(tileNumber, zoom)

String

Returns URL данных для конкретного тайла.

getTileUrlTemplate()

String

Returns шаблон URL данных для тайла.

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

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

requestObjects(layer, tileNumber, zoom, callback)

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

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

restrict(layer, tileNumber, zoom)

Boolean

Метод, который вызывается перед тем, как отправить запрос за данными для тайла. Если метод возвращает true, то запрос на сервер посылаться не будет, и в качестве ответа вернется пустой массив объектов.

setKeyTemplate(template)

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

setTileUrlTemplate(template)

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

Имя Возвращает Описание
cancelLastRequest()

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

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

getKey(tileNumber, zoom)

String

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

getKeyTemplate()

String

Returns шаблон идентификатора тайла.

getTileUrl(tileNumber, zoom)

String

Returns URL данных для конкретного тайла.

getTileUrlTemplate()

String

Returns шаблон URL данных для тайла.

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

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

requestObjects(layer, tileNumber, zoom, callback)

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

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

restrict(layer, tileNumber, zoom)

Boolean

Метод, который вызывается перед тем, как отправить запрос за данными для тайла. Если метод возвращает true, то запрос на сервер посылаться не будет, и в качестве ответа вернется пустой массив объектов.

setKeyTemplate(template)

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

setTileUrlTemplate(template)

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

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

getKey

{String} getKey(tileNumber, zoom)

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

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

Параметры:

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

Тип: Number[]

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

zoom *

Тип: Integer

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

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

Тип: Number[]

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

zoom *

Тип: Integer

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

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

getKeyTemplate

{String} getKeyTemplate()

Returns шаблон идентификатора тайла.

getTileUrl

{String} getTileUrl(tileNumber, zoom)

Returns URL данных для конкретного тайла.

Параметры:

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

Тип: Number[]

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

zoom *

Тип: Integer

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

Параметр Значение по умолчанию Описание
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 + '&x=' + tileNumber[0] + '&y=' + tileNumber[1]';
     }
};

getTileUrlTemplate

{String} getTileUrlTemplate()

Returns шаблон URL данных для тайла.

parseResponse

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

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

Параметры:

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

Тип: hotspot.Layer

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

res *

Тип: Object

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

callback *

Тип: Function

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

tileNumber *

Тип: Number[]

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

zoom *

Тип: Number

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

Параметр Значение по умолчанию Описание
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, то проверка для этого параметра не осуществляется.

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

Параметры:

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

Тип: hotspot.Layer

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

tileNumber *

Тип: Number[]

Номер тайла.

zoom *

Тип: Integer

Коэффициент масштабирования.

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

Тип: hotspot.Layer

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

tileNumber *

Тип: Number[]

Номер тайла.

zoom *

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

Тип: String

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

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

Тип: String

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

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

setTileUrlTemplate

{} setTileUrlTemplate(template)

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

Параметры:

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

Тип: String

Шаблон URL

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

Тип: String

Шаблон URL

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