@arcgis/core/layers/TileLayer.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type Collection from "../core/Collection.js";
import type Layer from "./Layer.js";
import type Sublayer from "./support/Sublayer.js";
import type { MultiOriginJSONSupportMixin } from "../core/MultiOriginJSONSupport.js";
import type { AbortOptions } from "../core/promiseUtils.js";
import type { MapImageLayerEvents } from "./MapImageLayer.js";
import type { APIKeyMixin, APIKeyMixinProperties } from "./mixins/APIKeyMixin.js";
import type { ArcGISCachedService, ArcGISCachedServiceProperties } from "./mixins/ArcGISCachedService.js";
import type { ArcGISMapService, ArcGISMapServiceProperties } from "./mixins/ArcGISMapService.js";
import type { BlendLayer, BlendLayerProperties } from "./mixins/BlendLayer.js";
import type { CustomParametersMixin, CustomParametersMixinProperties } from "./mixins/CustomParametersMixin.js";
import type { OperationalLayer, OperationalLayerProperties } from "./mixins/OperationalLayer.js";
import type { PortalLayer, PortalLayerProperties } from "./mixins/PortalLayer.js";
import type { RefreshableLayer, RefreshableLayerProperties } from "./mixins/RefreshableLayer.js";
import type { ScaleRangeLayer, ScaleRangeLayerProperties } from "./mixins/ScaleRangeLayer.js";
import type { SublayersOwner, SublayersOwnerProperties } from "./mixins/SublayersOwner.js";
import type { LayerProperties } from "./Layer.js";

export interface TileLayerProperties extends LayerProperties, CustomParametersMixinProperties, APIKeyMixinProperties, RefreshableLayerProperties, PortalLayerProperties, OperationalLayerProperties, ArcGISMapServiceProperties, ArcGISCachedServiceProperties, SublayersOwnerProperties, ScaleRangeLayerProperties, BlendLayerProperties, Partial<Pick<TileLayer, "resampling" | "sourceJSON" | "url">> {
  /**
   * The title of the layer used to identify it in places such as the [Legend](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/)
   * and [LayerList](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/).
   *
   * When loading a layer by service url, the title is derived from the service name.
   * If the service has several layers, then the title of each layer will be the concatenation of the service name
   * and the layer name.
   * When the layer is loaded from a portal item, the title of the portal item will be used instead.
   * Finally, if a layer is loaded as part of a webmap or a webscene, then the title of the layer as stored in the webmap/webscene will be used.
   */
  title?: string | null;
}

export interface TileLayerEvents extends MapImageLayerEvents {}

/**
 * The TileLayer allows you work with a cached [map service](https://enterprise.arcgis.com/en/server/latest/publish-services/windows/what-is-a-map-service.htm)
 * exposed by the ArcGIS Server REST API and add it to
 * a [Map](https://developers.arcgis.com/javascript/latest/references/core/Map/) as a tile layer.
 * A cached service accesses tiles from a cache instead of dynamically rendering images.
 * Because they are cached, tiled layers render faster than
 * [MapImageLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/MapImageLayer/). To create an
 * instance of TileLayer, you must reference the URL of the cached map service.
 *
 * ```js
 * const TileLayer = await $arcgis.import("@arcgis/core/layers/TileLayer.js");
 * let layer = new TileLayer({
 *   url: "https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer"
 * });
 * // Add layer to map
 * ```
 *
 * If the image is requested from a different domain, a [CORS enabled server](https://developers.arcgis.com/javascript/latest/cors/) or a [proxy](https://developers.arcgis.com/javascript/latest/proxies/) is
 * required.
 *
 * To display a non-cached map service as a dynamic layer, see [MapImageLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/MapImageLayer/).
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > When adding a TileLayer to a map in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/),
 * > the following limitations exist:
 * > This layer needs to be published from ArcGIS Server 10.3 and later.
 * > If [SceneView.viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) is `global`, then
 * > only services with ArcGIS Online/Bing Maps/Google Maps (Web Mercator), WGS84 Geographic Coordinate System or CGCS2000,
 * > Version 2 tiling scheme are supported.
 * > If [SceneView.viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) is `local`, then
 * > only services with projected coordinate systems are supported.
 * > When adding layers via the API: raster [TileLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/TileLayer/) can only be added when all other TileLayers in the map have the same tile size. [VectorTileLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/VectorTileLayer/) can adapt to 512 or 256 tiles, with 256 being selected by default for empty maps.
 * > If the TileLayer is the first added layer, the tiling scheme of the layer will lock the view and
 * > any features outside of the tiling scheme will not be displayed.
 * > Restrictions to layer ordering of tiled layers are described in [Map.layers](https://developers.arcgis.com/javascript/latest/references/core/Map/#layers).
 * >
 * > Only Tile layers with the following tiling scheme specifications are supported:
 * > 256x256 or 512x512 pixel tiles
 * > Scale levels must increase or decrease by a power of two
 * > At level `0` there shouldn't be more than 30 root tiles.
 * > All tiled layers must have the same tiling scheme and [SpatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/SpatialReference/).
 *
 * > [!WARNING]
 * >
 * > Esri requires that when you use an ArcGIS Online basemap in your app, the map must include Esri attribution and you must be licensed to use the content.
 * > For detailed guidelines on working with attribution, please visit the official [attribution in your app](https://developers.arcgis.com/terms/attribution/) documentation.
 * > For information, see the [Terms of Use documentation](https://developers.arcgis.com/documentation/terms-of-use/).
 *
 * @since 4.0
 * @see [MapImageLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/MapImageLayer/)
 * @see [Map](https://developers.arcgis.com/javascript/latest/references/core/Map/)
 * @see [Intro to TileLayer](https://developers.arcgis.com/javascript/latest/sample-code/layers-tilelayer/)
 */
export default class TileLayer extends TileLayerSuperclass {
  /**
   * @deprecated
   * Do not directly reference this property.
   * Use EventNames and EventTypes helpers from \@arcgis/core/Evented
   */
  "@eventTypes": TileLayerEvents;
  /**
   * @example
   * // Typical usage
   * let layer = new TileLayer({
   *   // URL points to a cached tiled map service
   *   url: "https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer"
   * });
   */
  constructor(properties?: TileLayerProperties);
  /**
   * A flat [Collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/) of all the [sublayers](https://developers.arcgis.com/javascript/latest/references/core/layers/TileLayer/#sublayers)
   * in the TileLayer including the sublayers of its sublayers.
   * All sublayers are referenced in the order in which they are drawn in the view (bottom to top).
   *
   * @since 4.9
   * @example
   * // finds the census tracts sublayer from a parent sublayer of the
   * // TileLayer containing various census sublayers
   * let tractsId = 5;
   * let tracksSublayer = layer.allSublayers.find(function(sublayer){
   *   return sublayer.id === tracksId;
   * });
   */
  readonly allSublayers: Collection<Sublayer>;
  /** The URL that points to the location of the layer's attribution data. */
  get attributionDataUrl(): string | null;
  /** Indicates if the layer has attribution data. */
  get hasAttributionData(): boolean;
  /**
   * Resampling is enabled by default in 2D [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/) and 3D [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
   * This means that tile images are resampled at a lower level of detail and displayed at levels
   * where tiles may not be available. Setting this property to `false` disables this behavior. Instead,
   * if a tile is not available, a transparent image is displayed.
   *
   * @default true
   * @since 4.11
   */
  accessor resampling: boolean;
  /**
   * The [tiled map service's metadata JSON](https://developers.arcgis.com/rest/services-reference/map-service.htm)
   * exposed by the ArcGIS REST API. While most commonly used properties
   * are exposed on the TileLayer class directly, this property gives access to all information returned
   * by the tiled map service. This property is useful if working in an application built using an older version of the API
   * which requires access to tiled map service properties from a more recent version.
   *
   * @since 4.13
   */
  accessor sourceJSON: any;
  /**
   * A [Collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/) of [Sublayer](https://developers.arcgis.com/javascript/latest/references/core/layers/support/Sublayer/) objects.
   * All sublayers are referenced in the order in which they are drawn in the view (bottom to top).
   * Sublayer properties on TileLayer are read-only, with the following exceptions:
   *   - [Sublayer.legendEnabled](https://developers.arcgis.com/javascript/latest/references/core/layers/support/Sublayer/#legendEnabled)
   *   - [Sublayer.popupEnabled](https://developers.arcgis.com/javascript/latest/references/core/layers/support/Sublayer/#popupEnabled)
   *   - [Sublayer.popupTemplate](https://developers.arcgis.com/javascript/latest/references/core/layers/support/Sublayer/#popupTemplate)
   *   - [Sublayer.title](https://developers.arcgis.com/javascript/latest/references/core/layers/support/Sublayer/#title)
   *
   * @since 4.9
   */
  get sublayers(): Collection<Sublayer> | null | undefined;
  /** An array of tile servers used for changing map tiles. */
  get tileServers(): string[];
  /**
   * The title of the layer used to identify it in places such as the [Legend](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/)
   * and [LayerList](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/).
   *
   * When loading a layer by service url, the title is derived from the service name.
   * If the service has several layers, then the title of each layer will be the concatenation of the service name
   * and the layer name.
   * When the layer is loaded from a portal item, the title of the portal item will be used instead.
   * Finally, if a layer is loaded as part of a webmap or a webscene, then the title of the layer as stored in the webmap/webscene will be used.
   */
  accessor title: string | null | undefined;
  /** The layer type provides a convenient way to check the type of the layer without the need to import specific layer modules. */
  get type(): "tile";
  /**
   * The URL of the REST endpoint of the layer. The URL may either point to a
   * resource on ArcGIS Enterprise or ArcGIS Online.
   *
   * @example
   * // URL points to a cached tiled map service
   * let layer = new TileLayer({
   *  url: "https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer"
   * });
   */
  accessor url: string | null | undefined;
  /**
   * This method fetches a tile for the given level, row and column present in the view.
   *
   * @param level - Level of detail of the tile to fetch. This value is provided by [LayerView](https://developers.arcgis.com/javascript/latest/references/core/views/layers/LayerView/).
   * @param row - The row(y) position of the tile fetch. This value is provided by [LayerView](https://developers.arcgis.com/javascript/latest/references/core/views/layers/LayerView/).
   * @param col - The column(x) position of the tile to fetch. This value is provided by [LayerView](https://developers.arcgis.com/javascript/latest/references/core/views/layers/LayerView/).
   * @param options - Optional settings for the tile request. The options have the following properties.
   * @returns Returns a promise that resolves to an
   * [HTMLImageElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement).
   */
  fetchTile(level: number, row: number, col: number, options?: AbortOptions): Promise<HTMLImageElement>;
  /**
   * This method returns a URL to a tile for a given level, row and column.
   *
   * @param level - The requested tile's level.
   * @param row - The requested tile's row.
   * @param col - The requested tile's column.
   * @returns Returns the tile URL.
   */
  getTileUrl(level: number, row: number, col: number): string;
  /**
   * Loads all of the sublayers. See [loaded](https://developers.arcgis.com/javascript/latest/references/core/layers/TileLayer/#loaded) or [loadStatus](https://developers.arcgis.com/javascript/latest/references/core/layers/TileLayer/#loadStatus)
   * properties to check the status.
   *
   * @returns Resolves when all the loadable resources have been [loaded](https://developers.arcgis.com/javascript/latest/references/core/layers/TileLayer/#loaded).
   *   Rejects if at least one of the loadable resources failed to load.
   * @since 4.26
   * @see [load()](https://developers.arcgis.com/javascript/latest/references/core/layers/TileLayer/#load)
   * @example
   * // Load all resources but ignore if one or more of them failed to load
   * mapImageLayer.loadAll()
   *   .catch(function(error) {
   *     // Ignore any failed resources
   *   })
   *   .then(function() {
   *     console.log("All loaded");
   *   });
   */
  loadAll(): Promise<this>;
}
declare const TileLayerSuperclass: typeof Layer & typeof CustomParametersMixin & typeof APIKeyMixin & typeof RefreshableLayer & typeof MultiOriginJSONSupportMixin & typeof PortalLayer & typeof OperationalLayer & typeof ArcGISMapService & typeof ArcGISCachedService & typeof SublayersOwner & typeof ScaleRangeLayer & typeof BlendLayer