ArcGIS API for JavaScript ^3.26

One common operation when using a map is setting the map's extent or getting the extent for use in other operations. A simple alternative to setting a new extent on the map is to call the centerAndZoom() method on the map, which sets a new extent based on a given center point and level of detail (LOD).

Default extent

If you include no extent information when you initialize a map, the default extent is the initial extent, which is the extent of the map as it was last saved in the map document. If you are using more than one service, the default extent is the initial extent of the base map or first layer added.

Setting a new starting extent

If you want the starting extent to be something other than the default extent, you have several options for setting this new extent.

• Set the extent in the Map constructor.

  function init() {
    var startExtent = new Extent(-95.271, 38.933, -95.228, 38.976,
            new SpatialReference({ wkid:4326 }) );
    var myMap = new Map("mapDiv", { extent: startExtent });
    var mapServiceURL = "https://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer";
    myMap.addLayer(new ArcGISTiledMapServiceLayer(mapServiceURL));
  }
  

• Set the extent using the Map.setExtent method.

  function init() {
    myMap = new Map("mapDiv");
    var startExtent = new Extent(-95.271, 38.933, -95.228, 38.976,
            new SpatialReference({ wkid:4326 }) );
  
    myMap.setExtent(startExtent);
    var mapServiceURL = "https://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer";
    myMap.addLayer(new ArcGISTiledMapServiceLayer(mapServiceURL));
  }
  

• As a variation of #2, set each property of the extent separately.

  function init() {
    myMap = new Map("mapDiv");
    var spatialRef = new SpatialReference({ wkid:4326 });
    var startExtent = new Extent();
    startExtent.xmin = -124.71;
    startExtent.ymin = 31.89;
    startExtent.xmax = -113.97;
    startExtent.ymax = 42.63;
    startExtent.spatialReference = spatialRef;
  
    myMap.setExtent(startExtent);
    var mapServiceURL = "https://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer";
    myMap.addLayer(new ArcGISTiledMapServiceLayer(mapServiceURL));
  }
  

Setting the beginning extent when using multiple services

When you include multiple services in the same application, the default extent is the initial extent of the base layer. If you want the beginning extent to be something new, and you know the extent ahead of time, you can include that extent in the Map constructor.

In some cases, you may not know the extent ahead of time. In other cases, you know you want to use the extent of a secondary layer. For example, the ArcGIS Online services all have a world extent. Instead of the world extent, you may want your map extent to be the extent of your local data.

In the following example, two services or layers are used. The base layer is an ArcGIS Online layer with a world extent. The second layer has an extent of the State of Kansas, which is the desired extent to use. The initLayers() function creates the two layers. You must create a second function to set the extent since you cannot call properties or events on a class before the class has been loaded. In this case, the function createMapAddLayers() is called after the layer onLoad has been fired for both map services. This function creates the map, sets the extent to myService2, and then adds both map services to the map. The initial map extent uses the Layer.fullExtent property as defined by the map service. If you want to use the initial extent instead, you would use Layer.initialExtent.

function initLayers() {
  var primaryMapServiceURL = "https://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer";
  var myService1 = new ArcGISTiledMapServiceLayer(primaryMapServiceURL);

  var secondaryMapServiceURL = "https://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Petroleum/KGS_OilGasFields_Kansas/MapServer";
  var myService2 = new ArcGISDynamicMapServiceLayer(secondaryMapServiceURL, {opacity:0.75});

  var layerLoadCount = 0;
  //When both layers have loaded, run addLayersSetExtent
  myService1.on("load", function(service) {
    layerLoadCount += 1;
    if (layerLoadCount === 2) {
      createMapAddLayers(myService1,myService2);
    }
  });

  myService2.on("load", function(service) {
    layerLoadCount += 1;
    if (layerLoadCount === 2) {
      createMapAddLayers(myService1,myService2);
    }
  });
}

//Create a map, set the extent, and add the services to the map.
function createMapAddLayers(myService1,myService2) {
  //create map
  myMap = new Map("mapDiv", { extent:myService2.fullExtent });
  myMap.addLayer(myService1);
  myMap.addLayer(myService2);
}

Getting the current extent using Map events

You can get the current extent of the map by using the Map.onExtentChange event.

In the following example, Map.onExtentChange is referenced in the init() function. When a user pans or zooms the map, a callback is made to the showExtent() function. The onExtentChange event has built in objects. The first object is the extent. In this example, the object is named ext, and the object properties include xmin, ymin, xmax, and ymax. In the showExtent() function, the four extent values are concatenated together in a string for display on the HTML page.

function init(){
 var myMap = new Map("mapDiv");

 var mapServiceURL = "https://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer";
 myMap.addLayer(new ArcGISTiledMapServiceLayer(mapServiceURL));
 myMap.addLayer(mapServiceURL);

 myMap.on("extent-change", showExtent);
}

function showExtent(ext){
 var extentString = "";
 extentString = "XMin: " + ext.xmin +
   " YMin: " + ext.ymin +
   " XMax: " + ext.xmax +
   " YMax: " + ext.ymax;
 document.getElementById("onExtentChangeInfo").innerHTML = extentString;
}

Getting the current extent using Map.extent

You can get the current extent of the map by using the Map.extent property. This property is a read-only property. If you want to set the extent, you need to use the Map.setExtent method.