import Collection from "@arcgis/core/core/Collection.js";const Collection = await $arcgis.import("@arcgis/core/core/Collection.js");- Inheritance:
- Collection→
Accessor
- Subclasses:
- SceneModifications
- Since
- ArcGIS Maps SDK for JavaScript 4.0
Collection stores an array of items of the same type. It provides useful utility methods for working with items in the Collection, including filter(), find(), and reduce().
A Collection can be of any type. For example, GraphicsLayer.graphics is a collection of graphics that are stored in the GraphicsLayer. You can use the methods found in the Collection class to add, remove, re-order, or manipulate graphics in a GraphicsLayer.
Another example of a Collection is Map.layers, which is a Collection of operational layers included in the Map.
// Removes a layer from the map using Collection.remove();map.layers.remove(layer);The change event fires each time an item is added, moved, or removed from the Collection.
As of version 4.18, you can iterate through the items of a Collection using for...of.
// a collection of graphics displayed in the viewconst graphics = view.graphics;
for (const graphic of graphics){ // do something with each view graphic}As of version 4.23, reactiveUtils can be utilized to watch for property changes on items in a Collection.
// reactiveUtils watch method can be used to watch the visible// property of each layer within the map.allLayer's collectionconst handle = reactiveUtils.watch( () => view.map.allLayers.every((layer) => layer.visible), (allVisible) => { console.log(`All layers are visible = ${allVisible}`); });- See also
Constructors
Constructor
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| items | A collection of items to initialize the Collection with. | |
Properties
| Property | Type | Class |
|---|---|---|
declaredClass readonly inherited | ||
| |
length
- Type
- number
The number of items in the Collection. Like a native Array, setting the length of a Collection can be used to remove items from the end of the collection. However, unlike a native Array, you cannot increase the length of the collection to reserve space for new items.
Methods
| Method | Signature | Class |
|---|---|---|
isCollection static | isCollection<T>(value: T): value is Extract<T, Collection<unknown>> | |
ofType static | ofType<T extends Base, Base = T>(type: (new (...args: any[]) => T) | Types<T, Base>): new (items?: ReadonlyArrayOrCollection<T> | { items?: ReadonlyArrayOrCollection<T>; }) => Collection<T> | |
[Symbol.iterator](): IterableIterator<T> | | |
add(item: T, index?: number): this | | |
addMany(items: ReadonlyArrayOrCollection<T>, index?: number): this | | |
at(index: number): T | undefined | | |
clone(): Collection<T> | | |
concat(value: ReadonlyArrayOrCollection<T>): Collection<T> | | |
destroyAll(): void | | |
destroyMany(items: ReadonlyArrayOrCollection<T>): T[] | | |
drain(callback: ItemCallback<T>, thisArg?: any): void | | |
emit inherited | emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean | |
every(callback: ItemTestCallback<T>, thisArg?: any): boolean | | |
filter<S extends T>(callback: (item: T, index: number, array: T[]) => item is S, thisArg?: any): Collection<S> | | |
filter(callback: ItemTestCallback<T>, thisArg?: any): Collection<T> | | |
find(callback: ItemTestCallback<T>, thisArg?: any): T | undefined | | |
findIndex(callback: ItemTestCallback<T>, thisArg?: any): number | | |
flatten(callback: ItemFlattenCallback<T>, thisArg?: any): Collection<T> | | |
flatten<U>(callback: ItemFlattenCallback<U>, thisArg?: any): Collection<U> | | |
forEach(callback: ItemCallback<T>, thisArg?: any): void | | |
getItemAt(index: number): T | undefined | | |
hasEventListener inherited | hasEventListener<Type extends EventNames<this>>(type: Type): boolean | |
includes(searchElement: T): boolean | | |
indexOf(searchElement: T, fromIndex?: number): number | | |
join(separator?: string): string | | |
lastIndexOf(searchElement: T, fromIndex?: number): number | | |
map<TRet>(callback: ItemMapCallback<T, TRet>, thisArg?: any): Collection<TRet> | | |
on inherited | on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle | |
pop(): T | undefined | | |
push(...items: T[]): number | | |
reduce<R = T>(callback: ItemReduceCallback<T, R>, initialValue?: R): R | | |
reduceRight<R = T>(callback: ItemReduceCallback<T, R>, initialValue?: R): R | | |
remove(item: T): T | undefined | | |
removeAll(): T[] | | |
removeAt(index: number): T | undefined | | |
removeMany(items: ReadonlyArrayOrCollection<T>): T[] | | |
reorder(item: T, index?: number): T | undefined | | |
reverse(): this | | |
shift(): T | undefined | | |
slice(begin?: number, end?: number): Collection<T> | | |
some(callback: (item: T, index: number, array: T[]) => boolean, thisArg?: any): boolean | | |
sort(compareFunction?: ItemCompareCallback<T>): this | | |
splice(start: number, deleteCount?: number, ...items: T[]): T[] | | |
toArray(): T[] | | |
toString(): string | | |
unshift(...items: T[]): number | |
isCollection
- Signature
-
isCollection <T>(value: T): value is Extract<T, Collection<unknown>>
- Type parameters
- <T>
Determines whether the passed value is a Collection.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| value | T | The value to be checked. | |
- Returns
- value is Extract<T, Collection<unknown>>
true if the test passes, false otherwise.
ofType
- Signature
-
ofType <T extends Base, Base = T>(type: (new (...args: any[]) => T) | Types<T, Base>): new (items?: ReadonlyArrayOrCollection<T> | { items?: ReadonlyArrayOrCollection<T>; }) => Collection<T>
- Type parameters
- <T extends Base, Base = T>
Creates a subclass of Collection containing a typed object.
Parameters
- Returns
- new (items?: ReadonlyArrayOrCollection
| { items?: ReadonlyArrayOrCollection ; }) => Collection The typed collection.
Example
const [Collection, Point] = await $arcgis.import([ "@arcgis/core/core/Collection.js", "@arcgis/core/geometry/Point.js"]);let PointCollection = Collection.ofType(Point);let collection = new PointCollection();collection.add([-100,40]);let point = collection.at(0);// point.x = -100; point.y = 40}); add
- Signature
-
add (item: T, index?: number): this
Adds a single item to the collection. The change event is fired after an item is added to the Collection.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| item | T | The item to add. | |
| index | Zero-based index of where in the collection to add the item. If not specified, the items will be added at the end. | |
- Returns
- this
Example
let gpc = new Graphic(); // Creates a new graphiclet layer = new GraphicsLayer(); // Creates a new graphics layerlayer.graphics.add(gpc); // Adds graphic to layer's graphics collection addMany
- Signature
-
addMany (items: ReadonlyArrayOrCollection<T>, index?: number): this
Adds multiple items to the collection. The change event is fired after items are added to the Collection.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| items | An array or collection of items to add. | | |
| index | Zero-based index of where in the collection to add the items. If not specified, the items will be added at the end. | |
- Returns
- this
Example
// Creates two new graphicslet gpc1 = new Graphic();let gpc2 = new Graphic();
let layer = new GraphicsLayer(); // Creates a new graphics layer
// Adds both graphics to layer's graphics collectionlayer.graphics.addMany([gpc1, gpc2]); at
- Signature
-
at (index: number): T | undefined
- Since
- ArcGIS Maps SDK for JavaScript 4.23
Returns the item at the specified index, allowing for positive and negative integers. Negative integers count back from the last item in the array.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| index | Index of the item in the Collection to retrieve. It can be a relative index from the end of the Collection. | |
- Returns
- T | undefined
The item in the Collection stored at the specified index.
Example
// get the layer at the first positionlet firstLayer = map.layers.at(0);// get the layer at the last positionlet lastLayer = map.layers.at(-1); clone
- Signature
-
clone (): Collection<T>
Creates a deep clone of the Collection. To create a shallow clone of the collection, use slice().
- See also
- Returns
- Collection
A clone of the Collection that invoked this method.
Example
// slides is a clone of the scene slideslet slides = scene.presentation.slides.clone(); concat
- Signature
-
concat (value: ReadonlyArrayOrCollection<T>): Collection<T>
Creates a new Collection containing the items in the original Collection joined with the items in the input array or Collection.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| value | The array or Collection to append to the existing Collection. | |
- Returns
- Collection
A new Collection comprised of the items in the Collection that invoked this method combined with the input items.
Example
// creating a collection of all the basemap's layers.let basemap = map.basemap;let basemapLayers = basemap.baseLayers.concat(basemap.referenceLayers); destroyAll
- Signature
-
destroyAll (): void
- Since
- ArcGIS Maps SDK for JavaScript 4.30
Removes and destroys instances of all the items of the Collection.
- Returns
- void
destroyMany
- Signature
-
destroyMany (items: ReadonlyArrayOrCollection<T>): T[]
- Since
- ArcGIS Maps SDK for JavaScript 4.30
Removes each item in the input array and destroys it. If an item is present multiple times in the collection, only the first occurrence is removed and destroyed. The change event is fired after an item is removed from the Collection.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| items | The items to remove and destroy. | |
- Returns
- T[]
The removed and destroyed items present in the collection.
drain
- Signature
-
drain (callback: ItemCallback<T>, thisArg?: any): void
- Since
- ArcGIS Maps SDK for JavaScript 4.33
Removes all the items of the Collection and executes the input function for each item.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | The function to call for each item in the Collection. | | |
| thisArg | Value to use as | |
- Returns
- void
emit
- Signature
-
emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean
- Type parameters
- <Type extends EventNames<this>>
- Since
- ArcGIS Maps SDK for JavaScript 4.5
Emits an event on the instance. This method should only be used when creating subclasses of this class.
every
- Signature
-
every (callback: ItemTestCallback<T>, thisArg?: any): boolean
Determines whether all items in the Collection pass a test defined by callback. Each item
in the Collection is passed into the callback until one returns a value of false.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | The function to call for each item in the Collection. | | |
| thisArg | Value to use as | |
- Returns
- boolean
Returns
trueif every call to thecallbackfunction returnedtrue. Returnsfalseif at least one call to thecallbackreturnedfalse.
Example
let meetsStandardSize = graphicsLayer.graphics.every(function(item, i){ // Tests each geometry's area to see if it is greater than 1,000 acres return calculateArea(item.geometry) > 1000;}); filter
- Signature
-
filter <S extends T>(callback: (item: T, index: number, array: T[]) => item is S, thisArg?: any): Collection<S>
- Type parameters
- <S extends T>
Filters the Collection's items based on a test defined by the
callback function. Each item is passed into the callback function, which
returns true if the item passes the test and false if it does not.
- See also
Parameters
- Returns
- Collection
Returns a new Collection containing the items that passed the filter test.
Example
// filteredLayers is a Collection of all the non-visible layers in the maplet filteredLayers = map.layers.filter(function(layer){ return !layer.visible;}); filter
- Signature
-
filter (callback: ItemTestCallback<T>, thisArg?: any): Collection<T>
Filters the Collection's items based on a test defined by the
callback function. Each item is passed into the callback function, which
returns true if the item passes the test and false if it does not.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | The function that defines a test for determining whether to return the item in a new Collection. | | |
| thisArg | Value to use as | |
- Returns
- Collection
Returns a new Collection containing the items that passed the filter test.
Example
// filteredLayers is a Collection of all the non-visible layers in the maplet filteredLayers = map.layers.filter(function(layer){ return !layer.visible;}); find
- Signature
-
find (callback: ItemTestCallback<T>, thisArg?: any): T | undefined
Returns an item in the Collection if that item passes a test as
defined in the callback function. Each item is passed into the
callback function, which
returns true if the item passes the test and false if it does not.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | The testing function that will assess
each item in the Collection. Returns | | |
| thisArg | Value to use as | |
- Returns
- T | undefined
The first item in the Collection that satisfies the test function.
Example
// If the id of a map layer is already known, get the layer that matches the idlet myLayer = map.layers.find(function(layer){ return layer.id === "speciesLyr01";});// myLayer references the layer in map with ID "speciesLyr01" findIndex
- Signature
-
findIndex (callback: ItemTestCallback<T>, thisArg?: any): number
Returns the index of an item in the Collection if that item passes a test as
defined in the callback function. Each item is passed into the callback function, which
returns true if the item passes the test and false if it does not.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | The testing function that will assess each
item in the Collection. Returns | | |
| thisArg | Value to use as | |
- Returns
- number
Returns the index of the Collection item that satisfies the test function. If an item fails the test,
-1is returned.
Example
// gpcIndex is assigned the index of the first graphic whose name// property is 'Redlands'. This result can be used in getItemAt()let gpcIndex = graphicsLyr.graphics.findIndex(function(item){ return item.attributes.name === "Redlands";}); flatten
- Signature
-
flatten (callback: ItemFlattenCallback<T>, thisArg?: any): Collection<T>
Flattens a hierarchical Collection containing at least one child collection.
Each item in the collection is passed into the callback function, which
should check for child collections specified by the developer.
A flat collection of all items (parent and children) is returned.
This is useful for scenarios where the user would like to search all the layers in a map, including a GroupLayer's layers and a MapImageLayer's sublayers. The callback should return the sub-collection of the item. If multiple levels of collections exist in the hierarchy, then this method recursively executes for all sub-collections.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | A function that will assess each item in the Collection. | | |
| thisArg | Value to use as | |
- Returns
- Collection
Returns a flat collection of all items in the original collection and their children.
Example
// create a MapImageLayer with several sublayers and add to a map// containing another GraphicsLayerlet layer = new MapImageLayer({ sublayers: [ ... ] });let map = new Map({ layers: [ layer, new GraphicsLayer() ]});
// A flat collection of all layers and sublayers// (if layer is a MapImageLayer) in the map.// This collection may be searched or used for other purposeslet allLayersAndSublayers = map.layers.flatten(function(item){ return item.layers || item.sublayers;}); flatten
- Signature
-
flatten <U>(callback: ItemFlattenCallback<U>, thisArg?: any): Collection<U>
- Type parameters
- <U>
Flattens a hierarchical Collection containing at least one child collection.
Each item in the collection is passed into the callback function, which
should check for child collections specified by the developer.
A flat collection of all items (parent and children) is returned.
This is useful for scenarios where the user would like to search all the layers in a map, including a GroupLayer's layers and a MapImageLayer's sublayers. The callback should return the sub-collection of the item. If multiple levels of collections exist in the hierarchy, then this method recursively executes for all sub-collections.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | A function that will assess each item in the Collection. | | |
| thisArg | Value to use as | |
- Returns
- Collection
Returns a flat collection of all items in the original collection and their children.
Example
// create a MapImageLayer with several sublayers and add to a map// containing another GraphicsLayerlet layer = new MapImageLayer({ sublayers: [ ... ] });let map = new Map({ layers: [ layer, new GraphicsLayer() ]});
// A flat collection of all layers and sublayers// (if layer is a MapImageLayer) in the map.// This collection may be searched or used for other purposeslet allLayersAndSublayers = map.layers.flatten(function(item){ return item.layers || item.sublayers;}); forEach
- Signature
-
forEach (callback: ItemCallback<T>, thisArg?: any): void
Executes the input function for each item in the Collection.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | The function to call for each item in the Collection. | | |
| thisArg | Value to use as | |
- Returns
- void
Example
graphicsLayer.graphics.forEach(function(item, i){ // Do something here to each graphic like calculate area of its geometry calculateArea(item.geometry);}); getItemAt
- Signature
-
getItemAt (index: number): T | undefined
Returns the item at the specified index.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| index | Zero-based index of the item in the Collection to retrieve. | |
- Returns
- T | undefined
The item in the Collection stored at the specified index.
Example
// Assigns the base layer at index 0 to baseLayerlet baseLayer = map.basemap.baseLayers.getItemAt(0); hasEventListener
- Signature
-
hasEventListener <Type extends EventNames<this>>(type: Type): boolean
- Type parameters
- <Type extends EventNames<this>>
Indicates whether there is an event listener on the instance that matches the provided event name.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | The name of the event. | |
- Returns
- boolean
Returns true if the class supports the input event.
includes
- Signature
-
includes (searchElement: T): boolean
Tests if an item is present in the new Collection.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| searchElement | T | The item to search for in the collection. | |
- Returns
- boolean
trueif the item is in the collection.
Example
// check if a layer is in the map's operational layers.if (view.map.layers.includes(myLayer)) { // ...} indexOf
- Signature
-
indexOf (searchElement: T, fromIndex?: number): number
Returns the index of an element in the collection.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| searchElement | T | Item to search for in the collection. | |
| fromIndex | Use if you don't want to search the whole collection or you don't want to search from the start. | |
- Returns
- number
The location of the first match found in the collection, or -1 if there is no match.
Example
// index is the index of the first graphic in the// graphics layer that matches the input graphiclet index = graphicsLayer.graphics.indexOf(graphic); join
- Signature
-
join (separator?: string): string
Creates a string representation of the items in the Collection.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| separator | = , - The separator used between each item in the final string. | |
- Returns
- string
The string representation of the items.
Example
let stringCollection = new Collection(["how", "are", "you", "doing?"]);let phrase = stringCollection.join(" ");
// Prints "how are you doing?"console.log(phrase); lastIndexOf
- Signature
-
lastIndexOf (searchElement: T, fromIndex?: number): number
Returns the last index of an element in the collection.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| searchElement | T | Item to search for in the collection. | |
| fromIndex | Use if you don't want to search the whole collection, or you don't want to search from the end. | |
- Returns
- number
The location of the last match found in the collection, or -1 if there is no match.
Example
// index is the index of the first graphic in the// graphics layer that matches the input graphiclet index = graphicsLayer.graphics.lastIndexOf(graphic); map
- Signature
-
map <TRet>(callback: ItemMapCallback<T, TRet>, thisArg?: any): Collection<TRet>
- Type parameters
- <TRet>
Passes each Collection item into the callback function and returns a new array of the
returned values. For example, if you have a Collection of numbers and would like to add each number
by 10, you can use map() to create a new Collection with the same numbers incremented by 10.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | ItemMapCallback<T, TRet> | The function that processes each item in the Collection and returns a new value at the same index of the original item. | |
| thisArg | Value to use as | |
- Returns
- Collection
Returns a new collection containing the new items generated from the
callback.
Example
// Gets the geometries of the graphics and assigns them to a new Collectionlet geometries = graphicsLayer.graphics.map(function(item, i){ return item.geometry;}); on
- Signature
-
on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle
- Type parameters
- <Type extends EventNames<this>>
Registers an event handler on the instance. Call this method to hook an event with a listener.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | An event or an array of events to listen for. | |
| listener | EventedCallback<this["@eventTypes"][Type]> | The function to call when the event fires. | |
- Returns
- ResourceHandle
Returns an event handler with a
remove()method that should be called to stop listening for the event(s).Property Type Description remove Function When called, removes the listener from the event.
Example
view.on("click", function(event){ // event is the event handle returned after the event fires. console.log(event.mapPoint);}); pop
- Signature
-
pop (): T | undefined
Removes the last item from the collection and returns it.
- See also
- Returns
- T | undefined
The last item in the collection.
Example
// Removes the last layer in the map and stores it in lastLayerlet lastLayer = map.layers.pop(); push
- Signature
-
push (...items: T[]): number
Adds an item(s) to the end of the collection.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| items | T[] | An item or comma-separated list of items to add to the end of the collection. | |
- Returns
- number
The new length of the collection.
Examples
// Adds a new graphic to the end of the graphics collection on a GraphicsLayergraphicsLyr.graphics.push(newGraphic);// Adds three new graphics to the end of the GraphicsLayer's graphics collectiongraphicsLyr.graphics.push(g1, g2, g3); reduce
- Signature
-
reduce <R = T>(callback: ItemReduceCallback<T, R>, initialValue?: R): R
- Type parameters
- <R = T>
Reduces all items in the collection (from left to right) into a single variable using callback.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | ItemReduceCallback<T, R> | The function that processes each item in the Collection and appends it to the previous item. | |
| initialValue | R | Item to use as the first element to process in | |
- Returns
- R
Returns the value representing the reduction of the Collection's items.
reduceRight
- Signature
-
reduceRight <R = T>(callback: ItemReduceCallback<T, R>, initialValue?: R): R
- Type parameters
- <R = T>
Reduces all items in the collection (from right to left) into a single variable using callback.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | ItemReduceCallback<T, R> | The function that processes each item in the Collection and appends it to the previous item. | |
| initialValue | R | Item to use as the first element to process in | |
- Returns
- R
Returns the value representing the reduction of the Collection's items.
remove
- Signature
-
remove (item: T): T | undefined
Removes an item from the collection. The change event is fired after an item is removed from the Collection.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| item | T | The item to remove. | |
- Returns
- T | undefined
Example
let layer = map.layers.at(4);// Removes the fifth layer from the mapmap.layers.remove(layer); removeAt
- Signature
-
removeAt (index: number): T | undefined
Removes an item from the collection at a specified index. The change event is fired after an item is removed from the Collection.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| index | The index of the item to remove. | |
- Returns
- T | undefined
The removed item if present in the collection,
undefinedotherwise.
Example
// Removes the layer at index 4 of the mapmap.layers.removeAt(4); removeMany
- Signature
-
removeMany (items: ReadonlyArrayOrCollection<T>): T[]
Removes each item in the input array. If an item is present multiple times in the collection, only the first occurrence is removed. The change event is fired after an item is removed from the Collection.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| items | The items to remove. | |
- Returns
- T[]
The removed items present in the collection.
Example
let refLayers = [refLyr1, refLyr2, refLyr3];// Removes three reference layers in the refLayers// collection from the basemap's referenceLayersmap.basemap.referenceLayers.removeMany(refLayers); reorder
- Signature
-
reorder (item: T, index?: number): T | undefined
Moves an item in the Collection to a specified index. The change event is fired after an item is moved in the Collection.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| item | T | The item to move. | |
| index | The index to move the item to. | |
- Returns
- T | undefined
The item that was moved.
undefinedifitemis not in the collection
Example
// Get the first two layers in a maplet layer1 = map.layers.at(0);let layer2 = map.layers.at(1);
// Moves the second layer to the first position in the map.layers Collection// effectively swapping the positions of layer1 and layer2map.layers.reorder(layer2, 0); reverse
- Signature
-
reverse (): this
Reverses the collection in place.
- See also
- Returns
- this
The reversed collection.
Example
// Reverse layers from the mapmap.layers.reverse(); shift
- Signature
-
shift (): T | undefined
Removes the first item from the collection (at index 0), and returns it. The remaining items of the collection are then shifted down one index from their previous location.
- See also
- Returns
- T | undefined
The first item in the collection.
Example
// Removes the first layer in the map and stores it in firstLyrlet firstLyr = map.layers.shift(); slice
- Signature
-
slice (begin?: number, end?: number): Collection<T>
Creates a new Collection comprised of a portion of the original Collection.
- See also
Parameters
- Returns
- Collection
Returns a new Collection containing the items in the specified range.
Example
// get the graphics from index 50 to 100;let selection = graphicsLayer.graphics.slice(50, 100); some
- Signature
-
some (callback: (item: T, index: number, array: T[]) => boolean, thisArg?: any): boolean
Determines whether an item in the Collection passes a test defined by callback. Each item
in the Collection is passed into the callback until one returns a value of true.
- See also
Parameters
- Returns
- boolean
Returns
trueif any of the items in the Collection pass the test defined incallback. Returnsfalseif all items fail the test.
Example
// If at least one of the point graphics has a geometry whose// elevation is above 1000m, then passes will have a value of true.// Otherwise, it will be false.let passes = graphicsLayer.graphics.some(function(item, i){ return item.geometry.z > 1000;}); sort
- Signature
-
sort (compareFunction?: ItemCompareCallback<T>): this
Sorts the Collection in place.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| compareFunction | The function that defines a comparison of two items in the collection. | |
- Returns
- this
Example
// Sort graphics based on their elevation or z-valuelet sortedGraphics = graphicsLayer.graphics.sort(function(a, b){ if(a.geometry.z > b.geometry.z){ return 1; } else if (a.geometry.z < b.geometry.z){ return -1; } else { return 0; }}); splice
- Signature
-
splice (start: number, deleteCount?: number, ...items: T[]): T[]
Removes existing items and/or adds new items to the collection.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| start | Index at which to start changing the collection. | | |
| deleteCount | Indicates the number of collection items to remove.
If omitted, or if greater than or equal to the number of elements after the position specified by start,
then all the elements from start to the end will be deleted. If | | |
| items | T[] | The item or comma-separated list of items to add to the collection. | |
- Returns
- T[]
An array of the deleted items formerly part of the collection.
Examples
// map.layers is a collection of 6 layers// Adds a seventh layer to the map at index 3map.layers.splice(3, 0, layer7);// Removes two layers starting from index 2 and adds the// specified layers in the positions of the former layerslet oldLayers = map.layers.splice(2, 2, layer8, layer9, layer10);
// oldLayers = [layer2, layer3] unshift
- Signature
-
unshift (...items: T[]): number
Adds one or more items to the beginning of the collection.
- See also
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| items | T[] | The item(s) to add to the beginning of the collection. | |
- Returns
- number
The new length of the collection.
Example
// If a map's basemap has 3 baseLayers: baseLyr0, baseLyr1, baseLyr2map.basemap.baseLayers.unshift(baseLyr3);
// Now the baseLayers collection is: baseLyr3, baseLyr0, baseLyr1, baseLyr2Events
| Name | Type |
|---|---|
after-add
after-add: CustomEvent<CollectionAfterItemEvent> Fires after an item has been added to the collection.
Example
// indicates a layer has been added to the mapmap.layers.on("after-add", function(event){ console.log(event.item, " has been added to the map.");}); after-changes
after-changes: CustomEvent<CollectionAfterEvent> Fires after an item has been added, reordered or removed from the collection.
Example
map.layers.on("after-changes", function(event){ console.log(event, " layer was added/removed from the map.");}); after-remove
after-remove: CustomEvent<CollectionAfterItemEvent> Fires after an item has been removed from the collection.
Example
// indicates a layer has been removed from the mapmap.layers.on("after-remove", function(event){ console.log(event.item, " has been removed from the map.");}); before-add
before-add: CustomEvent<CollectionEventObject> Fires before an item is added to the collection. This event
can be used to prevent an item from being added to the collection
by cancelling it with the event.preventDefault() method.
Example
// prevents a layer from being added to the map more than once.map.layers.on("before-add", function(event){ if(map.layers.includes(event.item)){ event.preventDefault(); console.log("layer already exists in map."); }}); before-changes
before-changes: CustomEvent<CollectionEventObject> Fires before any modifications are performed on the collection. This event
can be used to prevent an item from being added or removed from the collection
by cancelling it with the event.preventDefault() method.
Example
map.layers.on("before-changes", function(event){ // prevents layers from being added/removed from the map event.preventDefault();}); before-remove
before-remove: CustomEvent<CollectionEventObject> Fires before an item has been removed from the collection. This event
can be used to prevent an item from being removed from the collection
by cancelling it with the event.preventDefault() method.
Example
// prevents a layer from being removed from the basemapmap.basemap.baseLayers.on("before-remove", function(event){ if(map.basemap.baseLayers.includes(event.item)){ event.preventDefault(); console.log("layer cannot be removed from basemap."); }}); change
change: CustomEvent<CollectionChangeEvent> Fires after an item has been added, reordered, or removed from the Collection. Using methods of other classes that affect properties of type Collection will also cause this event to fire, such as Map.add(), Map.remove(), Map.reorder().
For example, map.layers.add(newLyr) and map.add(newLyr) which uses Map.add()
to add a new layer to the map.layers collection will cause this event to fire.
The change event can be used to notify the developer/user of changes to the collection. The arrays in the collection event objects are reused. Make a copy of the collection event object if these objects need to be processed in your application.
Example
// This function will fire each time a layer is either added,// moved, or removed from the map.layers Collection// make a copy of the collection event object for processingmap.layers.on("change", function(event){ const copiedEvent = JSON.parse(JSON.stringify(event)); let newLayers = copiedEvent.added; // An array of layers added to the map.layers Collection let reorderedLayers = copiedEvent.moved; // An array of layers moved in the Collection let removedLayers = copiedEvent.removed; // An array of layers removed from map});Type definitions
ReadonlyArrayOrCollection
- Type parameters
- <T>
- Type
- readonly T[] | ReadonlyCollection
CollectionChangeEvent
- Type parameters
- <T = any>
- Since
- ArcGIS Maps SDK for JavaScript 5.0
Event object emitted when a Collection changes. It contains arrays of added, removed, and moved items.
removed
- Type
- T[]
- Since
- ArcGIS Maps SDK for JavaScript 5.0
An array of items removed from the collection using either remove(), removeMany(), removeAt(), or removeAll().
moved
- Type
- T[]
- Since
- ArcGIS Maps SDK for JavaScript 5.0
An array of items that moved in the collection using reorder().
CollectionEventObject
- Type parameters
- <T>
defaultPrevented
- Type
- boolean
Indicates if this event has previously been cancelled by another event handler.
- Default value
- false
preventDefault
- Signature
-
preventDefault (): void
A method that prevents the item from being added or removed from the collection.
- Returns
- void
ReadonlyCollection
- Type parameters
- <T>
- Supertypes
- EventedMixin ‚ Pick<Collection
‚ "addHandles" | "at" | "clone" | "concat" | "declaredClass" | "destroyed" | "every" | "filter" | "find" | "findIndex" | "flatten" | "forEach" | "getItemAt" | "hasHandles" | "includes" | "initialized" | "indexOf" | "join" | "lastIndexOf" | "map" | "reduce" | "reduceRight" | "removeHandles" | "slice" | "some" | "toArray" | "toString" | "watch" | typeof Symbol.iterator>
ItemCallback
- Type parameters
- <T>
The function that is called for each Collection item.
ItemFlattenCallback
- Type parameters
- <T>
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| item | T | The current item being assessed in the collection. | |
| index | The index of the item being assessed. | |
- Returns
- T[] | Collection
ItemTestCallback
- Type parameters
- <T>
The function that defines a test and is called for each Collection item.
ItemMapCallback
- Type parameters
- <T, TRet>
The function that defines a mapping and is called for each Collection item.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| item | T | The current item being assessed in the collection. | |
| index | The index of the item being assessed. | |
- Returns
- TRet
the new value that replaces item.
ItemReduceCallback
- Type parameters
- <T, R>
The function that defines a reducer.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| previousValue | R | The item previously reduced value. | |
| currentValue | T | The current item being assessed in the collection. | |
| index | The index of the item being assessed. | |
- Returns
- R
the value to be passed to the next reducer.
ItemCompareCallback
- Type parameters
- <T>
The function that defines a comparison.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| firstItem | T | the first item in the comparison. | |
| secondItem | T | the second item in the comparison. | |
- Returns
- number
-1 if firstItem is smaller than secondItem, 1 if it is larger, and 0 if both are equal.