---
metadata:
  - name: generator
    content: Diplodoc Platform v5.39.1
alternate:
  - https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md
  - https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Layer.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/llms.txt

# Layer

Расширяет [ILayer](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md), [IParentOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IParentOnMap.md), [IPositioningContext](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPositioningContext.md).

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

[Конструктор](#constructor-summary) | [Поля ](#properties-summary) | [События ](#events-summary) | [Методы ](#methods-summary)

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

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

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

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

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

- %с заменяется на `x=номер[0]&y=номер[1]&z=уровень масштабирования`.
- %x — заменяется на номер[1];
- %y — заменяется на номер[1];
- %z — заменяется на уровень масштабирования;
- %l — заменяется на lang=язык;
- %d или %d|n- заменяется на число от 1 до n, в зависимости от номера тайла; n - количество доменов. Используется для распределения нагрузки между несколькими доменами. В качестве n нужно указывать степени двойки (2, 4, 16 и т.д.). Если шаблон имеет %d, то n=4.

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

- tileNumber - массив из двух чисел, номера тайла по x и y;
- tileZoom - уровень масштабирования;
- Возвращает строку-URL. ||
|| [`options`](#param-options) | — | Тип: Object

Опции. ||
|| [`options.brightness`](#param-options.brightness) | 0.5 | Тип: Number

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

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

Указатель на пейн слоя или ключ из [map.pane.Manager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/map.pane.Manager.md). ||
|| [`options.projection`](#param-options.projection) | — | Тип: Object

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

Размер тайлов слоя. ||
|| [`options.tileTransparent`](#param-options.tileTransparent) | false | Тип: Boolean

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

zIndex слоя в контейнере слоёв. ||
|#

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

**Пример:**

```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');
```

## Поля {#properties-summary}

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

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

Унаследовано от [ICustomizable](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#options). ||
|#

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

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

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

Унаследовано от [ILayer](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#event-copyrightschange). ||
|| [mapchange](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IParentOnMap.md#event-mapchange) | Сменилась карта. Поля данных:
- oldMap - старая карта;
- newMap - новая карта.

Унаследовано от [IParentOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IParentOnMap.md#event-mapchange). ||
|| [optionschange](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#event-optionschange) | Изменение в опциях объекта.

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

Поля данных:

- oldParent - старый родитель;
- newParent - новый родитель.

Унаследовано от [IChild](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IChild.md#event-parentchange). ||
|| [tileloadchange](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#event-tileloadchange) | Событие изменения состояния загрузки тайла. Поля данных:
- readyTileNumber-количество готовых тайлов. Тайл считается готовым, когда она загружен и отрисован. Тип: Number.
- totalTileNumber-общее количество видимых тайлов. Тип: Number.

Унаследовано от [ILayer](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#event-tileloadchange). ||
|| [zoomrangechange](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#event-zoomrangechange) | Событие изменения доступной информации о диапазоне уровней масштабирования.

Унаследовано от [ILayer](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#event-zoomrangechange). ||
|#


## Методы {#methods-summary}

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

Унаследован от [IPositioningContext](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPositioningContext.md#fromClientPixels). ||
|| [getBrightness](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#getBrightness)() | Number | Необязательный метод.

Унаследован от [ILayer](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#getBrightness). ||
|| [getCopyrights](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#getCopyrights)([coords](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#getCopyrights-param-coords), [zoom](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#getCopyrights-param-zoom)) | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md) | Необязательный метод. Запрашивает информацию об авторских правах в указанной точке с указанным коэффициентом масштабирования.

Унаследован от [ILayer](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayer.md#getCopyrights). ||
|| [getMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IParentOnMap.md#getMap)() | [Map](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Map.md) | Возвращает ссылку на карту.

Унаследован от [IParentOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IParentOnMap.md#getMap). ||
|| [getPane](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Layer.md#getPane)() | [IPane](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPane.md) | Возвращает контейнер, в котором находится слой. ||
|| [getParent](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IChildOnMap.md#getParent)() | [IParentOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IParentOnMap.md)\|null | Возвращает ссылку на родительский объект или null, если родительский элемент не был установлен.

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

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

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

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

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

## Описание методов {#method_detail}

### clientPixelsToNumber {#clientPixelsToNumber}

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

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

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

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

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

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

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

### getPane {#getPane}

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

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

### getTileSize {#getTileSize}

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

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

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

#|
|| **Параметр** | **Значение по умолчанию** | **Описание**  ||
|| [`zoom`](#getTileSize-param-zoom)[*](*star) | — | Тип: 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');
```

### getTileStatus {#getTileStatus}

```javascript
{Object} getTileStatus()
```

Возвращает общее число видимых тайлов и число готовых. Тайл считается готовым, когда она загружен и отрисован.

**Возвращает** объект, содержащий следующие поля:
- readyTileNumber-количество готовых тайлов. Тип: Number.
- totalTileNumber - общее количество тайлов. Тип: Number.

### getTileUrl  {#getTileUrl}

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

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

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

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

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

**Пример:**

```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   {#getTileUrlTemplate}

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

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

### numberToClientBounds {#numberToClientBounds}

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

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

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

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

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

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

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

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

### restrict  {#restrict}

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

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

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

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

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

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

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

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

### setTileUrlTemplate {#setTileUrlTemplate}

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

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

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

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

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

### update {#update}

```javascript
{} update()
```

Удаляет старые тайлы и запрашивает новые.

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

#|
|| **Параметр** | **Значение по умолчанию** | **Описание**  ||
|| [`updateBounds`](#update-param-updateBounds)[*](*star) | — | Тип: ||
|#

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

<!-- XLIFF_FARM_YjVlZTBm_CACHING -->

[*star]: Обязательный параметр.