---
metadata:
- name: generator
content: Diplodoc Platform v5.39.1
alternate:
- https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/hotspot.ObjectSource.md
- https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/jsapi-v2-1/doc/ru/llms.txt
# hotspot.ObjectSource
Расширяет [IHotspotObjectSource](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md).
Стандартная реализация интерфейса [IHotspotObjectSource](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md). Работает со стандартным форматом ответа сервера.
[Конструктор](#constructor-summary) | [Поля ](#properties-summary) | [События ](#events-summary) | [Методы ](#methods-summary)
## Конструктор {#constructor-summary}
```javascript
hotspot.ObjectSource(tileUrlTemplate[, keyTemplate[, options]])
```
Возвращает источник данных для слоя активных областей.
**Параметры:**
#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| [`tileUrlTemplate`](#param-tileUrlTemplate)[*](*star) | — | Тип: String\|Function
Возвращает шаблон URL данных для тайла. Поддерживаются специальные конструкции и возможность использования функции по аналогии с [Layer](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Layer.md). ||
|| [`keyTemplate`](#param-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`](#param-options) | — | Тип: Object
Опции источника данных. ||
|| [`options.bounds`](#param-options.bounds) | null | Тип: Bounds
Область на карте, для которой есть данные, или null, если данные есть везде. Опция для стандартной реализации метода restrict. ||
|| [`options.maxZoom`](#param-options.maxZoom) | 0 | Тип: Bounds
Максимальный уровень масштабирования, для которого делаются запросы за данными. Опция для стандартной реализации метода restrict. ||
|| [`options.minZoom`](#param-options.minZoom) | 0 | Тип: Bounds
Минимальный уровень масштабирования, для которого делаются запросы за данными. Опция для стандартной реализации метода restrict. ||
|| [`options.noCache`](#param-options.noCache) | false | Тип: Boolean
false — использовать встроенный кэш браузера, true — не использовать (к каждому URL будет автоматически приписываться случайный GET-параметр, чтобы исключить кэширование тайлов браузером). ||
|#
\* Обязательный параметр/опция.
**Пример:**
```javascript
// Пример стандартного формата ответа сервера.
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": {
// Описание следующей активной области.
} }] }});
```
## Поля {#properties-summary}
#|
|| **Имя** | **Тип** | **Описание** ||
|| [events](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IEventEmitter.md#events) | [IEventManager](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IEventManager.md) | Менеджер событий.
Унаследовано от [IEventEmitter](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IEventEmitter.md#events). ||
|| [options](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#options) | [IOptionManager](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IOptionManager.md) | Менеджер опций.
Унаследовано от [ICustomizable](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#options). ||
|#
## События {#events-summary}
#|
|| **Имя** | **Описание** ||
|| [optionschange](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#event-optionschange) | Изменение в опциях объекта.
Унаследовано от [ICustomizable](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#event-optionschange). ||
|#
## Методы {#methods-summary}
#|
|| **Имя** | **Возвращает** | **Описание** ||
|| [cancelLastRequest](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md#cancelLastRequest)() | | Отменяет последний запрос за данными.
Унаследован от [IHotspotObjectSource](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md#cancelLastRequest). ||
|| [getKey](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#getKey)([tileNumber](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#getKey-param-tileNumber), [zoom](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#getKey-param-zoom)) | String | Возвращает имя callback-функции (padding) в JSONP-запросе, если оно статическое, либо null, если можно использовать динамический JSONP-callback. Шаблоны поддерживают те же подстановки, что и в шаблоне url тайла. Все символы, не являющиеся буквой, цифрой или символом '_', будут заменены на '_'. ||
|| [getKeyTemplate](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#getKeyTemplate)() | String | Возвращает шаблон идентификатора тайла. ||
|| [getTileUrl](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#getTileUrl)([tileNumber](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#getTileUrl-param-tileNumber), [zoom](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#getTileUrl-param-zoom)) | String | Возвращает URL данных для конкретного тайла. ||
|| [getTileUrlTemplate](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#getTileUrlTemplate)() | String | Возвращает шаблон URL данных для тайла. ||
|| [parseResponse](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#parseResponse)([layer](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#parseResponse-param-layer), [res](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#parseResponse-param-res), [callback](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#parseResponse-param-callback), [tileNumber](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#parseResponse-param-tileNumber), [zoom](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#parseResponse-param-zoom)) | | Разбирает ответ сервера. Возвращает в callback массив объектов-активных областей, сформированных по JSON-описанию. ||
|| [requestObjects](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md#requestObjects)([layer](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md#requestObjects-param-layer), [tileNumber](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md#requestObjects-param-tileNumber), [zoom](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md#requestObjects-param-zoom), [callback](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md#requestObjects-param-callback)) | | Строит массив объектов [IHotspotLayerObject](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotLayerObject.md), соответствующих определенному слою, тайлу и коэффициенту масштабирования карты, и передает его в функцию callback.
Унаследован от [IHotspotObjectSource](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IHotspotObjectSource.md#requestObjects). ||
|| [restrict](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#restrict)([layer](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#restrict-param-layer), [tileNumber](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#restrict-param-tileNumber), [zoom](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#restrict-param-zoom)) | Boolean | Метод, который вызывается перед тем, как отправить запрос за данными для тайла. Если метод возвращает true, то запрос на сервер посылаться не будет, и в качестве ответа вернется пустой массив объектов. Стандартная реализация метода проверяет, лежит ли параметр zoom в пределах [options.minZoom, options.maxZoom]. А также проверяет, попадает ли центр запрашиваемого тайла в указанные options.bounds. Если options.bounds=null, то проверка для этого параметра не осуществляется. ||
|| [setKeyTemplate](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#setKeyTemplate)([template](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#setKeyTemplate-param-template)) | | Задает новый шаблон идентификатора тайла. ||
|| [setTileUrlTemplate](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#setTileUrlTemplate)([template](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.ObjectSource.md#setTileUrlTemplate-param-template)) | | Задает новый шаблон URL данных для тайла. ||
|#
## Описание методов {#method_detail}
### getKey {#getKey}
```javascript
{String} getKey(tileNumber, zoom)
```
Возвращает имя callback-функции (padding) в JSONP-запросе, если оно статическое, либо null, если можно использовать динамический JSONP-callback. Шаблоны поддерживают те же подстановки, что и в шаблоне url тайла. Все символы, не являющиеся буквой, цифрой или символом '_', будут заменены на '_'.
**Возвращает** идентификатор тайла. Используется для формирования padding в JSONP-запросе за данными тайла.
**Параметры:**
#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| [`tileNumber`](#getKey-param-tileNumber)[*](*star) | — | Тип: Number[]
Номер тайла (тайловые координаты). ||
|| [`zoom`](#getKey-param-zoom)[*](*star) | — | Тип: Integer
Уровень масштабирования. ||
|#
\* Обязательный параметр/опция.
### getKeyTemplate {#getKeyTemplate}
```javascript
{String} getKeyTemplate()
```
**Возвращает** шаблон идентификатора тайла.
### getTileUrl {#getTileUrl}
```javascript
{String} getTileUrl(tileNumber, zoom)
```
**Возвращает** URL данных для конкретного тайла.
**Параметры:**
#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| [`tileNumber`](#getTileUrl-param-tileNumber)[*](*star) | — | Тип: Number[]
Номер тайла (тайловые координаты). ||
|| [`zoom`](#getTileUrl-param-zoom)[*](*star) | — | Тип: Integer
Уровень масштабирования. ||
|#
\* Обязательный параметр/опция.
**Пример:**
```javascript
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 {#getTileUrlTemplate}
```javascript
{String} getTileUrlTemplate()
```
**Возвращает** шаблон URL данных для тайла.
### parseResponse {#parseResponse}
```javascript
{} parseResponse(layer, res, callback, tileNumber, zoom)
```
Разбирает ответ сервера. Возвращает в callback массив объектов-активных областей, сформированных по JSON-описанию.
**Параметры:**
#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| [`layer`](#parseResponse-param-layer)[*](*star) | — | Тип: [hotspot.Layer](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.Layer.md)
Слой, которому принадлежат объекты. ||
|| [`res`](#parseResponse-param-res)[*](*star) | — | Тип: Object
Ответ сервера. ||
|| [`callback`](#parseResponse-param-callback)[*](*star) | — | Тип: Function
Функция-обработчик. ||
|| [`tileNumber`](#parseResponse-param-tileNumber)[*](*star) | — | Тип: Number[]
Номер тайла, для которого пришел ответ. ||
|| [`zoom`](#parseResponse-param-zoom)[*](*star) | — | Тип: Number
Коэффициент масштабирования, для которого пришел ответ. массива объектов. ||
|#
\* Обязательный параметр/опция.
### restrict {#restrict}
```javascript
{Boolean} restrict(layer, tileNumber, zoom)
```
Метод, который вызывается перед тем, как отправить запрос за данными для тайла. Если метод возвращает true, то запрос на сервер посылаться не будет, и в качестве ответа вернется пустой массив объектов. Стандартная реализация метода проверяет, лежит ли параметр zoom в пределах [options.minZoom, options.maxZoom]. А также проверяет, попадает ли центр запрашиваемого тайла в указанные options.bounds. Если options.bounds=null, то проверка для этого параметра не осуществляется.
**Возвращает** true - тайл вышел за пределы области данных (для данного тайла данных нет), false - не вышел (данные есть).
**Параметры:**
#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| [`layer`](#restrict-param-layer)[*](*star) | — | Тип: [hotspot.Layer](https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.Layer.md)
Слой активных областей. ||
|| [`tileNumber`](#restrict-param-tileNumber)[*](*star) | — | Тип: Number[]
Номер тайла. ||
|| [`zoom`](#restrict-param-zoom)[*](*star) | — | Тип: Integer
Уровень масштабирования. ||
|#
\* Обязательный параметр/опция.
**Пример:**
```javascript
// Пример переопределения метода "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}
```javascript
{} setKeyTemplate(template)
```
Задает новый шаблон идентификатора тайла.
**Параметры:**
#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| [`template`](#setKeyTemplate-param-template)[*](*star) | — | Тип: String
Шаблон идентификатора. ||
|#
\* Обязательный параметр/опция.
### setTileUrlTemplate {#setTileUrlTemplate}
```javascript
{} setTileUrlTemplate(template)
```
Задает новый шаблон URL данных для тайла.
**Параметры:**
#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| [`template`](#setTileUrlTemplate-param-template)[*](*star) | — | Тип: String
Шаблон URL ||
|#
\* Обязательный параметр/опция.
[*star]: Обязательный параметр.