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 |
— |
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:
The template function receives three input parameters:
|
|
— |
Type: Object Options. |
|
0.5 |
Type: Number Layer brightness. Specified as a number from 0 to 1. 0 corresponds to black, and 1 to white. |
|
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. |
|
'ground' |
Type: IPane|String Pointer to the layer pane or key from map.pane.Manager. |
|
— |
Type: Object Layer projection. |
|
[256, 256] |
Type: Number[] Size of tiles on the layer. |
|
false |
Type: Boolean Flag showing whether layer tiles are transparent. |
|
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 |
Event manager. Inherited from IEventEmitter. |
||
Options manager. Inherited from ICustomizable. |
Events
Name |
Description |
Layer brightness change event. Inherited from ILayer. |
|
Event for changes to available copyright information. Inherited from ILayer. |
|
Map reference changed. Data fields:
Inherited from IParentOnMap. |
|
Change to the object options. Inherited from ICustomizable. |
|
The parent object reference changed. Data fields:
Inherited from IChild. |
|
Tile upload status change event. Data fields:
Inherited from ILayer. |
|
Event for changes to available information about the zoom level range. Inherited from ILayer. |
Methods
Name |
Returns |
Description |
Number[] |
Returns the number of the tile that the specified point falls on for the specified tile zoom level. |
|
Number[] |
Converts client pixel coordinates to global coordinates. Inherited from IPositioningContext. |
|
Number |
Optional method. Inherited from ILayer. |
|
Optional method. Requests information about copyrights at the specified point with the specified zoom. Inherited from ILayer. |
||
getMap() |
Returns reference to the map. Inherited from IParentOnMap. |
|
getPane() |
Returns the container that the layer is located in. |
|
IParentOnMap|null |
Returns link to the parent object, or null if the parent element was not set. Inherited from IChildOnMap. |
|
Number[] |
Returns the horizontal and vertical tile dimensions for the specified zoom level. |
|
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. |
|
String|null |
Returns the tile URL by its number and zoom level, or null if there is no data for the requested section. |
|
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. |
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. |
||
Number[][] |
Converts the tile number and zoom level to the area occupied by the tile in client coordinates of the parent container. |
|
Integer[]|null |
Applies restrictions to the visible area for tiles (including map cycling on the x and y axes). |
|
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 |
— |
Type: Number A point in client pixel coordinates. |
|
— |
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 |
|
— |
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 |
— |
Type: |
|
— |
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 |
— |
Type: Integer[] Tile number. |
|
— |
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 |
— |
Type: Integer[] Tile number. |
|
— |
Type: Integer Tile zoom level. |
* Mandatory parameter/option.
setTileUrlTemplate
{} setTileUrlTemplate(tileUrlTemplate)
Parameters:
Parameter |
Default value |
Description |
— |
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 |
— |
Type: |
* Mandatory parameter/option.
Mandatory parameter/option.