Documentation
Reference
2.1.50 (current version)
collection
interactivityModel
Interfaces

Layer

Extends ILayer, IParentOnMap, IPositioningContext.

Tile layer. Allows to display a layer consisting of tiles on the map.

Constructor | Fields | Events | Methods

Constructor

Parameters:

ParameterDefault valueDescription
tileUrlTemplate *
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String|Function

String template for the tile URL, or a function that generates the tile URL. For the string template, the following substitutions are supported:

  • %c - Replaced with x=number[0]&y=number[1]&z=zoom level.
  • %x is replaced with number[0].
  • %y is replaced with number[1].
  • %z is replaced with the zoom level.
  • %l is replaced with lang=language.
  • %d or %d|n is replaced with a number from 1 to n, depending on the tile number; n is the number of domains. Used for distributing the load over multiple domains. For n, specify a factor of two (2, 4, 16, and so on). If the template has %d, then n=4.

The template function receives three input parameters:

  • tileNumber - Array of two numbers, the tile numbers on x and y.
  • tileZoom - Zoom level.
  • Returns a URL string.
options

Type: Object

Options.

options.brightness 0.5

Type: Number

Layer brightness. Specified as a number from 0 to 1. 0 corresponds to black, and 1 to white.

options.notFoundTile null

Type: String|null

Option that specifies the URL for downloading an image if the tile image didn't load. If the value is null, a standard tile is displayed with a text message. For transparent tiles, the notFoundTile option is not applied, and nothing is shown in place of tiles that didn't load.

options.pane 'ground'

Type: IPane|String

Pointer to the layer pane or key from map.pane.Manager.

options.projection

Type: Object

Layer projection.

options.tileSize [256, 256]

Type: Number[]

Size of tiles on the layer.

options.tileTransparent false

Type: Boolean

Flag showing whether layer tiles are transparent.

options.zIndex constants.zIndex.layer

Type: Number

Z-index of the layer in the layers container.

* Mandatory parameter/option.

Example:

// Adding an OSM layer to the map
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

NameTypeDescription
eventsIEventManager

Event manager.

Inherited from IEventEmitter.

optionsIOptionManager

Options manager.

Inherited from ICustomizable.

Events

NameDescription
brightnesschange

Layer brightness change event.

Inherited from ILayer.

copyrightschange

Event for changes to available copyright information.

Inherited from ILayer.

mapchange

Map reference changed. Data fields:

  • oldMap - Old map.
  • newMap - New map.

Inherited from IParentOnMap.

optionschange

Change to the object options.

Inherited from ICustomizable.

parentchange

The parent object reference changed.

Data fields:

  • oldParent - Old parent.
  • newParent - New parent.

Inherited from IChild.

zoomrangechange

Event for changes to available information about the zoom level range.

Inherited from ILayer.

Methods

NameReturnsDescription
clientPixelsToNumber(clientPixelPoint, tileZoom)

Number[]

Returns the number of the tile that the specified point falls on for the specified tile zoom level.

fromClientPixels(clientPixelPoint)

Number[]

Converts client pixel coordinates to global coordinates.

Inherited from IPositioningContext.

getBrightness()

Number

Optional method.

Inherited from ILayer.

getCopyrights(coords, zoom)

vow.Promise

Optional method. Requests information about copyrights at the specified point with the specified zoom.

Inherited from ILayer.

getMap()

Map

Returns reference to the map.

Inherited from IParentOnMap.

getPane()

IPane

Returns the container that the layer is located in.

getParent()

IControlParent|null

Returns link to the parent object, or null if the parent element was not set.

Inherited from IChildOnMap.

getTileSize(zoom)

Number[]

Returns the horizontal and vertical tile dimensions for the specified zoom level.

getTileUrl(tileNumber, tileZoom)

String|null

Returns the tile URL by its number and zoom level, or null if there is no data for the requested section.

getTileUrlTemplate()

String|Function

Returns string template for the tile URL, or a function that generates it.

getZoom()

Number

Returns the current zoom level at which the positioning context works.

Inherited from IPositioningContext.

getZoomRange(point)

vow.Promise

Optional method. Checks the available range of zoom levels at the specified point. If there is data, the returned promise object will be resolved and will pass as a result an array of two numbers - the minimum and maximum zoom level available at the point. If there is no data, the promise is rejected with an error.

Inherited from ILayer.

numberToClientBounds(tileNumber, tileZoom)

Number[][]

Converts the tile number and zoom level to the area occupied by the tile in client coordinates of the parent container.

restrict(number, tileZoom)

Integer[]|null

Applies restrictions to the visible area for tiles (including map cycling on the x and y axes).

setParent(parent)

IChildOnMap

Sets the parent object. If the null value is passed, the manager element will only be deleted from the current parent object.

Inherited from IChildOnMap.

setTileUrlTemplate(tileUrlTemplate)
toClientPixels(globalPixelPoint)

Number[]

Converts global pixel coordinates to client coordinates.

Inherited from IPositioningContext.

update()

Deletes the old tiles and requests new ones.

Methods details

clientPixelsToNumber

{Number[]} clientPixelsToNumber(clientPixelPoint, tileZoom)

Returns the number of the tile that the specified point falls on for the specified tile zoom level.

Parameters:

ParameterDefault valueDescription
clientPixelPoint*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number

A point in client pixel coordinates.

tileZoom*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number

Tile zoom level.

* Mandatory parameter/option.

getPane

{IPane} getPane()

Returns the container that the layer is located in.

getTileSize

{Number[]} getTileSize(zoom)

Returns the horizontal and vertical tile dimensions for the specified zoom level.

Parameters:

ParameterDefault valueDescription
zoom*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number

Zoom value.

* Mandatory parameter/option.

Example:

// We will show tiles for a larger zoom level,
// stretched to twice their size up to 512x512 pixels.
// For example, to reduce traffic.
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

{String|null} getTileUrl(tileNumber, tileZoom)

Returns the tile URL by its number and zoom level, or null if there is no data for the requested section.

Parameters:

ParameterDefault valueDescription
tileNumber*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type:

tileZoom*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type:

* Mandatory parameter/option.

Example:

// Defining the function for generating the tile URL
var layer = new ymaps.Layer('');
layer.getTileUrl = function (tileNumber, zoom) {
    return [
        'http://tile.openstreetmap.org',
        zoom, tileNumber[0], tileNumber[1]
    ].join('/') + '.png';
}

getTileUrlTemplate

{String|Function} getTileUrlTemplate()

Returns string template for the tile URL, or a function that generates it.

numberToClientBounds

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

Converts the tile number and zoom level to the area occupied by the tile in client coordinates of the parent container.

Returns the area in client pixel coordinates.

Parameters:

ParameterDefault valueDescription
tileNumber*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Integer[]

Tile number.

tileZoom*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Integer

Tile zoom level.

* Mandatory parameter/option.

restrict

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

Applies restrictions to the visible area for tiles (including map cycling on the x and y axes).

Returns the new tile number calculated with restrictions, or null if the tile is not in the visible area.

Parameters:

ParameterDefault valueDescription
number*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Integer[]

Tile number.

tileZoom*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Integer

Tile zoom level.

* Mandatory parameter/option.

setTileUrlTemplate

{} setTileUrlTemplate(tileUrlTemplate)

Parameters:

ParameterDefault valueDescription
tileUrlTemplate*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String|Function

String template for the tile URL, or a function that generates it.

* Mandatory parameter/option.

update

{} update()

Deletes the old tiles and requests new ones.

Parameters:

ParameterDefault valueDescription
updateBounds*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type:

* Mandatory parameter/option.