dojo.require("esri/layers/VectorTileLayer");
Description
(Added at v3.15)
A VectorTileLayer renders cached tiles of data. It is similar to a WebTiledLayer
in that it renders cached data; however, a WebTiledLayer
renders as a series of images, not vector data.
Unlike image caches, vector tiles contain data for rendering the tile information. Because the data in VectorTileLayer is vector, it is stored in individual layers containing geometry, attributes, and styles. Styling information is stored separately from the tile geometry and attributes, and more than one style can be defined. This means that one set of vector tiles may be styled numerous ways without having to generate a new cache for each style. This saves space and speeds up the process for creating new map styles.
Styles may contain multiple options for rendering the same type of feature. In a street layer, for example, major highways might have three symbology options. Styles can also be changed on the client without having to make a request for a new tile from the server. This enables maps to be dynamic on the client while still taking advantage of cached vector data.
For more information about vector tile layers see the Vector tile layer topic in the ArcGIS Online Help and the Vector Basemaps group in ArcGIS Online.
Known Limitations:
- Vector tile layers can be displayed in Internet Explorer 11 and higher and most other current versions of desktop browsers, including Chrome, Firefox, and Safari.
- Vector tile layers have the best performance on machines with newer hardware.
- In some cases, labels along vector tile boundaries may collide with labels from the neighboring tile.
- VectorTileLayer printing requires ArcGIS Server 10.5.1 or later. Using ArcGIS Server 10.5.1, the PrintTask will create a client-side image for the VectorTileLayer in the printout. For printing secure VectorTileLayers with ArcGIS Server 10.5.1 or 10.6.0, the PrintTask will also create a client-side image for the VectorTileLayer in the printout. This has some limitations related to large size printing quality and a dependency on browser window height/width ratio.
Samples
Search for
samples that use this class.
Class hierarchy
esri/layers.Layer
|_esri/layers.VectorTileLayer
Constructors
Properties
Methods
Events
[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.
Events
error | {
error: <Error >
} | Fires when there is a problem retrieving a layer. |
load | {
layer: <Layer >
} | Fires after layer properties for the layer are successfully populated. |
opacity-change | {
opacity: <Number >
} | Fires when the layer opacity has been changed, and returns an object with the opacity value. |
resume | | Fires when a layer resumes drawing. |
scale-range-change | | Fires when a layer's minScale and/or maxScale is changed. |
scale-visibility-change | | Fires when a layer's scale visibility changes. |
style-change | {
style: <Object >
} | Fires when the style is changed on the layer. |
suspend | | Fires when a layer suspends drawing. |
update-end | {
error: <Error >
} | Fires when the layer has finished updating its content. |
update-start | | Fires when the layer begins to update its content. |
visibility-change | {
visible: <Boolean >
} | Fires when the layer visibility has been changed, and returns an object with a Boolean visible property containing the new visibility value of the layer. |
Constructor Details
Create a new VectorTileLayer object.
Parameters:
<String | Object > url |
Required |
The URL to the vector tile service or style JSON that will be used to draw the layer. If specifying a URL to a style JSON object, the tiles are fetched from the tile servers specified in the style object.
For documentation and examples of using objects to define the style of the layer, see the Mapbox style documentation. |
<Object > options |
Optional |
Optional parameters. See options list. |
options
properties:
<Number[] > displayLevels |
Optional |
Lists which levels of the layer to draw. |
<Number > maxScale |
Optional |
Maximum visible scale for the layer. |
<Number > minScale |
Optional |
Minimum visible scale for the layer. |
<Number > opacity |
Optional |
Initial opacity or transparency of layer. Values range from 0.0 to 1.0, where 0.0 is 100% transparent and 1.0 has no transparency. The default value is 1.0. |
<Boolean > visible |
Optional |
Visibility of the layer. |
Property Details
The URL, when available, where the layer's attribution data is stored. (Added at v3.1)
class attribute of the layer's node.
(Added at v3.7)
Provides credential information for the layer such as userid and token if the layer represents a resource that is secured with token-based authentication. This value is available after the layer has been loaded i.e. layer.loaded
is true. (Added at v2.5)
The current style information of the VectorTileLayer. See the object specification below. (Added at v3.25)
Object Specifications: <currentStyleInfo
>
<String > glyphsUrl |
Required |
Absolute template URL for font sets included in a style. |
<Object > layerDefinition |
Required |
Vector tile service information. |
<String > serviceUrl |
Required |
Absolute URL for a vector tile service. |
<String > spriteUrl |
Required |
Asbolute URL for sprites included in a style. |
<Object > style |
Required |
Style JSON object for vector tiles. Style object includes version of the style specification, sprite and glyphs properties. |
<String > styleUrl |
Required |
Absolute URL for vector tile service style. |
The full extent of the layer. By default, this is worldwide.
When true, the layer has attribution data. Use the
getAttributionData method to retrieve this data as JSON.
(Added at v3.1) Known values: true | false
Default value: false
ID assigned to the layer. If not assigned, esri.Map assigns value. By default, the ID of the layer is "layer" followed by a number. The ID can be user defined only in the layer constructor.
Sample:
- Setting the layer ID in the layer constructor.
population = new esri.layers.ArcGISDynamicMapServiceLayer("http://myserver/arcgis/rest/population/MapServer/Layers", {id:"population"});
- Setting the layer ID after a layer is initialized.
population.id = "population";
- Retrieving the layer ID.
function getMapLayers() {
for (var j=0, jl=myMap.layerIds.length; j<jl; j++) {
var currentLayer = myMap.getLayer(myMap.layerIds[j]);
alert("id: " + currentLayer.id);
}
}
The initial extent of the layer. By default, the extent is worldwide.
Set if the layer failed to load. (Added at v3.9)
When the layer is loaded, the value becomes "true", and layer properties can be accessed. The
onLoad event is also fired.
Known values: true | false
Maximum visible scale for the layer. If the map is zoomed in beyond this scale, the layer will not be visible. A value of 0 means the layer does not have a maximum scale. (Added at v3.1)
Default value: 0
Minimum visible scale for the layer. If the map is zoomed out beyond this scale, the layer will not be visible. A value of 0 means the layer does not have a visible scale. (Added at v3.1)
Default value: 0
Name of the vector tile layer.
Opacity or transparency of layer. Values range from 0.0 to 1.0, where 0.0 is 100% transparent and 1.0 has no transparency.
Known values: 0.0 - 1.0
Default value: 1.0
When true, the layer's attribution is displayed on the map. (Added at v3.1)
Known values: true | false
Default value: true
The spatial reference of the layer.
When true, the layer is suspended. A layer is considered to be suspended when one of the following is true:
- The layer is hidden.
- The layer is not visible at the current map scale.
- The layer is explicitly suspended by calling the
Layer.suspend
method.
(Added at v3.1) Known values: true | false
Contains information about the tiling scheme for the layer.
The URL to the vector tile service or style JSON that will be used to draw the layer.
Visibility of the layer.
Known values: true | false
Default value: true
When true, the layer is visible at the current map scale. (Added at v3.1)
Known values: true | false
Method Details
Adds a new attribute or changes the value of an existing attribute on the layer's node. Removes the attribute if the value is null
or undefined
. (Added at v3.7)
Parameters:
<String > name |
Required |
The name of the attribute. |
<String > value |
Required |
The value of the attribute. Set this value as null to remove the attribute. |
Asynchrously returns custom data for the layer when available. (Added at v3.1)
Returns reference to the map control the layer is added to. Returns null
or undefined
if it is not added to a map. (Added at v3.7)
Returns the layer's DOM node. (Added at v3.7)
Returns an object that contains the current style information for the layer. This object can be used as the argument to create a new layer.
Sets the visibility of the layer to "false". The layer is not removed, but it is hidden from view.
Returns true if the layer is visible at the given scale. (Added at v3.1)
Parameters:
<Number > scale |
Required |
The scale at which to check if the layer is visible. |
Resumes layer drawing. (Added at v3.1)
Set the maximum scale for the layer. (Added at v3.1)
Parameters:
<Number > scale |
Required |
The maximum scale at which the layer is visible. |
Set the minimum scale for the layer. (Added at v3.1)
Parameters:
<Number > scale |
Required |
The minimum scale at which the layer is visible. |
Sets the opacity of the layer. Values range from 0.0 to 1.0, where 0.0 is 100% transparent and 1.0 has no transparency.
Parameters:
<Number > opacity |
Required |
Value from 0 to 1, where 0 is 100% transparent and 1 has no transparency. The default value is 1. |
Sample:
layer.setOpacity(0.5);
Set the scale range for the layer. If minScale
and maxScale
are set to 0 then the layer will be visible at all scales. (Added at v3.1)
Parameters:
<Number > minScale |
Required |
The minimum scale at which the layer is visible. |
<Number > maxScale |
Required |
The maximum scale at which the layer is visible. |
Changes the style properties used to render the layers. It is the equivalent of changing the entire CSS style sheet for a web page. It takes either a style object or a url to a style resource. When loading a style, it is the developer's responsibility to make sure that any relative urls in the style resolve correctly.
Parameters:
<String | Object > styleUrl |
Required |
A url to a JSON file containing the stylesheet information to render the layer. You may also pass an object containing the stylesheet information identical to the JSON file. |
Sets the visibility of the layer. When true, the layer is visible.
Parameters:
<Boolean > isVisible |
Required |
Set the visibility of the layer. |
Sets the visibility of the layer to "true".
Suspends layer drawing. (Added at v3.1)
Event Details
[ On Style Events | Connect Style Event ]
Fires when there is a problem retrieving a layer. Should be used in favor of onError. (Added at v3.5)
Fires after layer properties for the layer are successfully populated. This event must be successful before the layer can be added to the map. Should be used in favor of onLoad. (Added at v3.5)
Event Object Properties:
<Layer > layer |
The loaded layer. |
Fires when the layer opacity has been changed, and returns an object with the opacity value. Should be used in favor of onOpacityChange. (Added at v3.5)
Event Object Properties:
<Number > opacity |
Fires when the layer opacity (transparency) changes. A number property named opacity that indicates the new opacity. Values range from 0.0 to 1.0, where 0.0 is 100% transparent and 1.0 has no transparency. |
Fires when a layer resumes drawing. Should be used in favor of onResume. (Added at v3.5)
Fires when a layer's minScale and/or maxScale is changed. Should be used in favor of onScaleRangeChange. (Added at v3.5)
Fires when a layer's scale visibility changes. The scale visibility changes when a layer is initially visible and becomes invisible because the map scale does not intersect the layer's scale range or vice versa. Should be used in favor of onScaleVisibilityChange. (Added at v3.5)
Fires when the style is changed on the layer.
Event Object Properties:
<Object > style |
The style object of the service with fully qualified URLs for glyphs and sprite. |
Sample:
require([
"esri/layers/VectorTileLayer", ...
], function(VectorTileLayer, ... ) {
var vectorTileLayer = new VectorTileLayer("https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap/VectorTileServer");
vectorTileLayer.on("style-change", function(event){
console.log("Event: ", event);
});
...
});
Fires when a layer suspends drawing. Should be used in favor of onSuspend. (Added at v3.5)
Fires when the layer has finished updating its content. This event is always preceded by update-start. (Added at v3.21)
Event Object Properties:
<Error > error |
Optional argument. The error object is available when an error occurs during the update. |
Fires when the layer begins to update its content. (Added at v3.21)
Fires when the layer visibility has been changed, and returns an object with a Boolean visible property containing the new visibility value of the layer. Should be used in favor of onVisibilityChange. (Added at v3.5)
Event Object Properties:
<Boolean > visible |
Fires when the layer visibility changes. A boolean property named visible indicates whether or not the layer is visible after visibility changed. |
Fires when there is a problem retrieving a layer. (Added at v1.3)
Fires after layer properties for the layer are successfully populated. This event must be successful before the layer can be added to the map.
In Internet Explorer, due to resource caching, the onLoad event is fired as soon as the layer is constructed. Consequently you should check whether the layer's loaded property is true before registering a listener for the onLoad event:
Event Object Properties:
<Layer > layer |
The loaded layer. |
Sample: function init() {
//setting initial extent in constructor
var map = new esri.Map("mapDiv", { extent: new esri.geometry.Extent(...) });
//or use set extent method
var map = new esri.Map("mapDiv");
map.setExtent(new esri.geometry.Extent(...));
//add first layer
map.addLayer(...);
}
Fires when the layer opacity has been changed, and returns the opacity value.
Event Object Properties:
<Number > opacity |
Opacity or transparency of layer. Values range from 0.0 to 1.0, where 0.0 is 100% transparent and 1.0 has no transparency. |
This event is fired when the layer's refreshInterval
is modified. (Added at v3.7)
Fires when a layer resumes drawing. (Added at v3.1)
Fires when a layer's minScale and/or maxScale is changed. (Added at v3.1)
Fires when a layer's scale visibility changes. The scale visibility changes when a layer is initially visible and becomes invisible because the map scale does not intersect the layer's scale range or vice versa. (Added at v3.1)
Fires when a layer suspends drawing. (Added at v3.1)
Fires when a layer has finished updating its content. It is the responsibility of the subclass to determine when this event is fired.
Event Object Properties:
<Error > error |
Optional argument. The error object is available when an error occurs during the update. |
Sample: dojo.connect(layer, "onUpdateEnd", layerUpdateCompleted);
function layerUpdateCompleted(error) {
if (error) {
console.log("Update completed with error: ", error);
}
else {
console.log("Update completed");
}
}
Fires when a layer begins to update its content. It is the responsibility of the subclass to determine when this event is fired.
Sample:
dojo.connect(layer, "onUpdateStart", layerUpdateStarted);
function layerUpdateStarted() {
console.log("Update started...");
}
Fires when the layer visibility has been changed, and returns the new visibility.
Event Object Properties:
<Boolean > visbility |
Determines whether the layer is visible on the map. |