---
metadata:
  - name: generator
    content: Diplodoc Platform v5.39.1
alternate:
  - https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/llms.txt

# Layer

Расширяет [ILayer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md), [IPositioningContext](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPositioningContext.md).

Тайловый слой. Позволяет отображать на карте подложку, состоящую из тайлов.

## Конструктор {#constructor}

```javascript
Layer(tileUrlTemplate[, options])
```

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `tileUrlTemplate`[*](*parametr) | — | Тип: String\|Function

Строковый шаблон URL тайла, либо функция, которая генерирует URL тайла. Для строкового шаблона поддерживается подстановка:

• %c - заменяется на `x=номер[0]&y=номер[1]&z=уровень масштабирования`;

• %x - заменяется на номер[0]

• %y - заменяется на номер[1]

• %z - заменяется на уровень масштабирования

• %l - заменяется на lang=язык;

• %d или %d\|n - заменяется на число от 1 до n, в зависимости от номера тайла. n - количество доменов. Используется для распределения нагрузки между несколькими доменами. В качестве n нужно указывать степени двойки (2, 4, 16 и т.д.). Если шаблон имеет вид %d, то n=4.

Функция-шаблон получает на вход три параметра:

• tileNumber - массив из двух чисел, номера тайла по x и y;

• tileZoom - уровень масштабирования;

• Возвращает строку-URL. ||
|| `options` | — | Тип: Object

Опции. ||
|| `options.brightness` | 0.5 | Тип: Number

Яркость слоя. Задается числом от 0 до 1. 0 соответствует черному цвету, 1 - белому. ||
|| `options.notFoundTile` | null | Тип: String\|null

Опция, указывающая по какому url нужно загрузить картинку, если картинка для тайла не загрузилась. Если значение null, то будет показан стандартный тайл с текстовым сообщением. Для прозрачных тайлов опция notFoundTile не применяется, и вместо незагруженных тайлов ничего показываться не будет. ||
|| `options.pane` | 'layers' | Тип: [IPane](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPane.md)

Родительский контейнер слоёв. ||
|| `options.projection` | — | Тип: Object

Проекция слоя. ||
|| `options.tileSize` | [256, 256] | Тип: Number[]

Размер тайлов слоя. ||
|| `options.tileTransparent` | false | Тип: Boolean

Флаг, показывающий, являются ли тайлы слоя прозрачными. ||
|| `options.zIndex` | constants.zIndex.layer | Тип: Number

Z-index слоя в контейнере слоёв. ||
|#

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

**Пример:**

```javascript
// Добавим на карту слой OSM
map.layers.add(new ymaps.Layer(
'http://tile.openstreetmap.org/%z/%x/%y.png', {
    projection: ymaps.projection.sphericalMercator
}));
map.copyrights.add('© OpenStreetMap contributors, CC-BY-SA');
```

## Поля {#fields}

#|
|| **Имя** | **Тип** | **Описание** ||
|| [events](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IEventEmitter.md#events) | [IEventManager](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IEventManager.md) | Менеджер событий.

Унаследовано от [IEventEmitter](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IEventEmitter.md#events). ||
|| [options](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICustomizable.md#options) | [IOptionManager](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IOptionManager.md) | Менеджер опций.

Унаследовано от [ICustomizable](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICustomizable.md#options). ||
|#

## События {#events}

#|
|| **Имя** | **Описание** ||
|| [brightnesschange](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#brightnesschange) | Событие изменения яркости слоя.

Унаследовано от [ILayer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#brightnesschange). ||
|| [copyrightschange](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#copyrightschange) | Событие изменения доступной информации об авторских правах.

Унаследовано от [ILayer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#copyrightschange). ||
|| [mapchange](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChildOnMap.md#mapchange) | Сменилась карта. Поля данных:

• oldMap - старая карта;

• newMap - новая карта.

Унаследовано от [IChildOnMap](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChildOnMap.md#mapchange). ||
|| [optionschange](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICustomizable.md#optionschange) | Изменение в опциях объекта.

Унаследовано от [ICustomizable](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ICustomizable.md#optionschange). ||
|| [parentchange](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChild.md#parentchange) | Сменился родительский объект.

Поля данных:

• oldParent - старый родитель;

• newParent - новый родитель.

Унаследовано от [IChild](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChild.md#parentchange). ||
|| [zoomrangechange](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#zoomrangechange) | Событие изменения доступной информации о диапазоне уровней масштабирования.

Унаследовано от [ILayer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#zoomrangechange). ||
|#

## Методы {#method}

#|
|| **Имя** | **Возвращает** | **Описание** ||
|| [clientPixelsToNumber](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#clientPixelsToNumber)([clientPixelPoint](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#clientPixelsToNumber-param-clientPixelPoint), [tileZoom](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#clientPixelsToNumber-param-tileZoom)) | Number[] | Returns номер тайла, в который попадает указанная точка при заданном уровне масштаба тайлов. ||
|| [fromClientPixels](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPositioningContext.md#fromClientPixels)([clientPixelPoint](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPositioningContext.md#fromClientPixels-param-clientPixelPoint)) | Number[] | Преобразует клиентские пиксельные координаты в глобальные.

Унаследован от [IPositioningContext](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPositioningContext.md#fromClientPixels). ||
|| [getBrightness](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#getBrightness)() | Number | Необязательный метод. Возвращает яркость слоя. В зависимости от суммарной яркости слоев, добавленных на карту, выбирается цвет логотипа и копирайтов на карте.

Унаследован от [ILayer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#getBrightness). ||
|| [getCopyrights](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#getCopyrights)([coords](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#getCopyrights-param-coords), [zoom](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#getCopyrights-param-zoom)) | [util.Promise](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/util.Promise.md) | Необязательный метод. Запрашивает информацию об авторских правах в указанной точке с указанным коэффициентом масштабирования. Возвращает объект-promise, который будет подтверждён и передаст в качестве результата массив строк или DOM-элементов с информацией об авторских правах.

Унаследован от [ILayer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#getCopyrights). ||
|| [getPane](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#getPane)() | [IPane](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPane.md) | Возвращает контейнер, в котором находится слой. ||
|| [getParent](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChildOnMap.md#getParent)() | [IParentOnMap](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IParentOnMap.md) | Returns ссылку на родительский объект.

Унаследован от [IChildOnMap](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChildOnMap.md#getParent). ||
|| [getTileSize](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#getTileSize)([zoom](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#getTileSize-param-zoom)) | Number[] | Возвращает размеры тайлов в зависимости от масштаба. ||
|| [getTileUrl](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#getTileUrl)([tileNumber](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#getTileUrl-param-tileNumber), [tileZoom](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#getTileUrl-param-tileZoom)) | String\|null | Returns URL тайла по его номеру и уровню масштабирования или null если для запрашиваемого участка нет данных. ||
|| [getTileUrlTemplate](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#getTileUrlTemplate)() | String\|Function | Returns строковый шаблон URL тайла или функцию, которая его генерирует. ||
|| [getZoom](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPositioningContext.md#getZoom)() | Number | Returns текущий уровень масштабирования, в котором работает контекст позиционирования.

Унаследован от [IPositioningContext](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPositioningContext.md#getZoom). ||
|| [getZoomRange](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#getZoomRange)([point](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#getZoomRange-param-point)) | [util.Promise](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/util.Promise.md) | Необязательный метод. Определяет доступный в указанной точке диапазон уровней масштабирования. Если данные есть, то возвращенный объект-promise будет подтвержден и передаст в качестве результата массив из двух чисел - минимальный и максимальный доступный в точке уровень масштабирования. Если данных нет, то promise отклоняется с указанием ошибки.

Унаследован от [ILayer](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/ILayer.md#getZoomRange). ||
|| [numberToClientBounds](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#numberToClientBounds)([tileNumber](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#numberToClientBounds-param-tileNumber), [tileZoom](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#numberToClientBounds-param-tileZoom)) | Number[][] | Преобразует номер и уровень масштаба тайла в занимаемую тайлом область в клиентских координатах родительского контейнера. ||
|| [restrict](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#restrict)([number](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#restrict-param-number), [tileZoom](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#restrict-param-tileZoom)) | Integer[]\|null | Накладывает ограничения на зону видимости тайлов (в том числе зацикленность карты по осям x, y). ||
|| [setParent](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChildOnMap.md#setParent)([parent](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChildOnMap.md#setParent-param-parent)) | [IChildOnMap](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChildOnMap.md) | Устанавливает родительский объект.

Унаследован от [IChildOnMap](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IChildOnMap.md#setParent). ||
|| [setTileUrlTemplate](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#setTileUrlTemplate)([tileUrlTemplate](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#setTileUrlTemplate-param-tileUrlTemplate)) |  |  ||
|| [toClientPixels](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPositioningContext.md#toClientPixels)([globalPixelPoint](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPositioningContext.md#toClientPixels-param-globalPixelPoint)) | Number[] | Преобразует глобальные пиксельные координаты в клиентские.

Унаследован от [IPositioningContext](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IPositioningContext.md#toClientPixels). ||
|| [update](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Layer.md#update)() |  | Удаляет старые тайлы и запрашивает новые. ||
|#

## Описание методов {#description-methods}

### clientPixelsToNumber

```javascript
{Number[]} clientPixelsToNumber(clientPixelPoint, tileZoom)
```

**Returns** номер тайла, в который попадает указанная точка при заданном уровне масштаба тайлов.

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `clientPixelPoint`[*](*parametr) | — | Тип: Number

Точка в клиентских пиксельных координатах. ||
|| `tileZoom`[*](*parametr) | — | Тип: Number

Уровень масштаба тайла. ||
|#

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

### getPane

```javascript
{IPane} getPane()
```

Возвращает контейнер, в котором находится слой.

**Returns** контейнер.

### getTileSize

```javascript
{Number[]} getTileSize(zoom)
```

Возвращает размеры тайлов в зависимости от масштаба.

**Returns** размеры тайла по горизонтали и вертикали для указанного коэффициента масштабирования.

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `zoom`[*](*parametr) | — | Тип: Number

Значение коэффициента мастабирования. ||
|#

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

**Пример:**

```javascript
// Будем показывать тайлы для большего уровня масштабирования,
// растянутые в два раза до размера 512х512 пикселей
// Например, для экономии трафика.
var layer = new ymaps.Layer('', {
    projection: ymaps.projection.sphericalMercator
});
layer.getTileUrl = function (tileNumber, zoom) {
    return [
        'http://tile.openstreetmap.org',
        Math.max(zoom - 1, 0), tileNumber[0], tileNumber[1]
    ].join('/') + '.png';
}
layer.getTileSize = function (zoom) {
    if (zoom == 0) {
        return [256, 256];
    }
    return [512, 512];
}
map.copyrights.add('© OpenStreetMap contributors, CC-BY-SA');
```

### getTileUrl

```javascript
{String|null} getTileUrl(tileNumber, tileZoom)
```

**Returns** URL тайла по его номеру и уровню масштабирования или null если для запрашиваемого участка нет данных.

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `tileNumber`[*](*parametr) | — | Тип: ||
|| `tileZoom`[*](*parametr) | — | Тип: ||
|#

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

**Пример:**

```javascript
// Определим свою функцию для формирования URL тайла
var layer = new ymaps.Layer('');
layer.getTileUrl = function (tileNumber, zoom) {
    return [
        'http://tile.openstreetmap.org',
        zoom, tileNumber[0], tileNumber[1]
    ].join('/') + '.png';
}
```

### getTileUrlTemplate

```javascript
{String|Function} getTileUrlTemplate()
```

**Returns** строковый шаблон URL тайла или функцию, которая его генерирует.

### numberToClientBounds

```javascript
{Number[][]} numberToClientBounds(tileNumber, tileZoom)
```

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

**Returns** область в клиентских пиксельных координатах.

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `tileNumber`[*](*parametr) | — | Тип: Integer[]

Номер тайла. ||
|| `tileZoom`[*](*parametr) | — | Тип: Integer

Уровень масштаба тайла. ||
|#

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

### restrict

```javascript
{Integer[]|null} restrict(number, tileZoom)
```

Накладывает ограничения на зону видимости тайлов (в том числе зацикленность карты по осям x, y).

**Returns** новый номер тайла с учётом ограничений либо null, если тайл не входит в зону видимости.

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `tileNumber`[*](*parametr) | — | Тип: Integer[]

Номер тайла. ||
|| `tileZoom`[*](*parametr) | — | Тип: Integer

Уровень масштаба тайла. ||
|#

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

### setTileUrlTemplate

```javascript
{} setTileUrlTemplate(tileUrlTemplate)
```

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| `tileUrlTemplate`[*](*parametr) | — | Тип: String\|Function

Строковый шаблон URL тайла, либо функция, которая его генерирует. ||
|#


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

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