Layer

Extends ILayer, IParentOnMap, IPositioningContext.

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

Constructor | Fields | Events | Methods

Constructor

Layer(tileUrlTemplate[, options])

Parameters:

Parameter

Default value

Description

tileUrlTemplate*

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 is 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:

// Adds 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

Name

Type

Description

events

IEventManager

Event manager.

Inherited from IEventEmitter.

options

IOptionManager

Options manager.

Inherited from ICustomizable.

Events

Name

Description

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.

tileloadchange

Tile upload status change event. Data fields:

  • readyTileNumber - Number of ready tiles. A tile is considered ready when it is downloaded and rendered. Type: Number.
  • totalTileNumber - Total number of visible tiles. Type: Number.

Inherited from ILayer.

zoomrangechange

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

Inherited from ILayer.

Methods

Name

Returns

Description

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()

IParentOnMap|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.

getTileStatus()

Object

Returns the total number of visible tiles and the number of ready tiles. A tile is considered ready when it is downloaded and rendered.

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)

Name: 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:

Parameter

Default value

Description

clientPixelPoint*

Type: Number

A point in client pixel coordinates.

tileZoom*

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:

Parameter

Default value

Description

zoom*

Type: Number

Zoom value.

* Mandatory parameter/option.

Example:

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

getTileStatus

{Object} getTileStatus()

Returns the total number of visible tiles and the number of ready tiles. A tile is considered ready when it is downloaded and rendered.

Returns object with following fields:

  • readyTileNumber - Number of ready tiles. Type: Number.
  • totalTileNumber - Total number of tiles. Type: Number.

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:

Parameter

Default value

Description

tileNumber*

Type:

tileZoom*

Type:

* Mandatory parameter/option.

Example:

// Defines 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:

Parameter

Default value

Description

tileNumber*

Type: Integer[]

Tile number.

tileZoom*

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:

Parameter

Default value

Description

number*

Type: Integer[]

Tile number.

tileZoom*

Type: Integer

Tile zoom level.

* Mandatory parameter/option.

setTileUrlTemplate

{} setTileUrlTemplate(tileUrlTemplate)

Parameters:

Parameter

Default value

Description

tileUrlTemplate*

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:

Parameter

Default value

Description

updateBounds*

Type:

* Mandatory parameter/option.