Collection

// Removes a layer from the map using Collection.remove();
map.layers.remove(layer);

// a collection of graphics displayed in the view
const graphics = view.graphics;

for (const graphic of graphics){
  // do something with each view graphic
}

// reactiveUtils watch method can be used to watch the visible
// property of each layer within the map.allLayer's collection
const handle = reactiveUtils.watch(
  () => view.map.allLayers.every((layer) => layer.visible),
  (allVisible) => {
    console.log(`All layers are visible = ${allVisible}`);
  }
);

属性概述

属性详情

declaredClass Stringreadonly inherited

起始版本：GeoScene API for JavaScript 4.7

类的名称。声明的类名的格式为 geoscene.folder.className。

length Number

集合中的项目数。

方法概述

方法详情

add(item, index)

将单个项添加到集合中。将项目添加到集合后会触发更改事件。

参数：

item * 要添加的项。

index Number 可选 集合中要添加项的位置的从零开始的索引。如果未指定，则将在末尾添加项目。

示例：

let gpc = new Graphic();  // Creates a new graphic
let layer = new GraphicsLayer(); // Creates a new graphics layer
layer.graphics.add(gpc);  // Adds graphic to layer's graphics collection

addMany(items, index)

将多个项添加到集合中。将项目添加到集合后会，将触发更改事件。

参数：

items Array|Collection 要添加的项的数组或集合。

index Number 可选 集合中要添加项的位置的从零开始的索引。如果未指定，则将在末尾添加项目。

示例：

// Creates two new graphics
let gpc1 = new Graphic();
let gpc2 = new Graphic();

let layer = new GraphicsLayer(); // Creates a new graphics layer

// Adds both graphics to layer's graphics collection
layer.graphics.addMany([gpc1, gpc2]);

at(index){*}

起始版本：GeoScene API for JavaScript 4.23

返回指定索引处的项，允许使用正整数和负整数。负整数从数组中的最后一项开始计数。

参数：

index Number 要检索的集合中项的索引。它可以是集合末尾的相对索引。

返回：

类型	说明
*	集合中存储在指定索引处的项。

另请参阅：

• Array.prototype.at()

示例：

// get the layer at the first position
let firstLayer = map.layers.at(0);
// get the layer at the last position
let lastLayer = map.layers.at(-1);

clone(){Collection}

创建集合的深层克隆。若要创建集合的浅克隆，请使用 slice()。

返回：

类型	说明
集合	调用此方法的集合的克隆。

另请参阅：

• slice()

示例：

// slides is a clone of the scene slides
let slides = scene.presentation.slides.clone();

concat(value){Collection}

创建一个新集合，其中包含原始集合中的项目以及输入数组或集合中的项目。

参数：

value Array|Collection 要追加到现有集合的数组或集合。

返回：

类型	说明
集合	一个新的集合，由集合中调用此方法的项与输入项组合而成。

另请参阅：

• Array.prototype.concat()

示例：

// creating a collection of all the basemap's layers.
let basemap = map.basemap;
let basemapLayers = basemap.baseLayers.concat(basemap.referenceLayers);

emit(type, event){Boolean}

起始版本：GeoScene API for JavaScript 4.5

在实例上发出事件。此方法仅应在创建此类的子类时使用。

参数：

type String 事件的名称。

event Object 可选 事件负载。

返回：

类型	说明
布尔值	true 如果通知了侦听器

every(callback){Boolean}

确定集合中的所有项目是否通过 callback 定义的测试。集合中的每个项目都被传递到回调中，直到返回 false 值。

参数：

callback ItemTestCallback 为集合中的每个项目调用的函数。

返回：

类型	说明
布尔值	如果对 callback 函数的每次调用都返回 true，则返回 true 。如果至少一个 callback 调用返回 false，则返回 false。

另请参阅：

• Array.prototype.every()

示例：

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(callback){Collection}

根据 callback 函数定义的测试过滤集合的项目。每个项目都被传递到 callback 函数中，如果项目通过测试，则返回 true ，否则返回 false 。

参数：

callback ItemTestCallback 定义用于确定是否在新集合中返回项的测试的函数。

返回：

类型	说明
集合	返回包含通过筛选器测试的项的新集合。

另请参阅：

• Array.prototype.filter()

示例：

// filteredLayers is a Collection of all the non-visible layers in the map
let filteredLayers = map.layers.filter(function(layer){
  return !layer.visible;
});

find(callback){*}

如果该项目通过 callback 中定义的测试，则返回集合中的项目。每个项目都被传递到 callback 函数中，如果项目通过测试，则返回 true ，否则返回 false 。

参数：

callback ItemTestCallback 将评估集合中每个项目的测试函数。如果项目通过测试，则返回 true ，如果失败，则返回 false 。

返回：

类型	说明
*	集合中满足测试功能的第一个项目。

另请参阅：

• Array.prototype.find()

示例：

// If the id of a map layer is already known, get the layer that matches the id
let myLayer = map.layers.find(function(layer){
  return layer.id === "speciesLyr01";
});
// myLayer references the layer in map with ID "speciesLyr01"

findIndex(callback){Number}

如果该项目通过 callback 函数中定义的测试，则返回集合中项目的索引。每个项目都被传递到 callback 函数中，如果项目通过测试，则返回 true ，否则返回 false 。

参数：

callback ItemTestCallback 将评估集合中每个项目的测试函数。如果项目通过测试，则返回 true ，如果失败，则返回 false 。

返回：

类型	说明
整数	返回满足测试功能的集合项的索引。如果项目未通过测试，则返回 -1。

另请参阅：

• Array.prototype.findIndex()

示例：

// 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(callback){Collection}

展平包含至少一个子集合的分图层集合。集合中的每个项目都传递给 callback 函数，该函数应检查开发人员指定的子集合。返回所有项目（父项和子项）的平面集合。

这对于用户想要搜索地图中的所有图层（包括 GroupLayer 的图层和 MapImageLayer 的子图层）的场景很有用。回调应该返回项目的子集合。如果层次结构中存在多个级别的集合，则此方法对所有子集合递归执行。

参数：

callback ItemCallback 将评估集合中的每个项的函数。

返回：

类型	说明
集合	返回原始集合中所有项及其子项的平面集合。

示例：

// create a MapImageLayer with several sublayers and add to a map
// containing another GraphicsLayer
let 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 purposes
let allLayersAndSublayers = map.layers.flatten(function(item){
  return item.layers || item.sublayers;
});

forEach(callback)

为集合中的每个项目执行输入函数。

参数：

callback ItemCallback 为集合中的每个项目调用的函数。

另请参阅：

• Array.prototype.forEach()

示例：

graphicsLayer.graphics.forEach(function(item, i){
  // Do something here to each graphic like calculate area of its geometry
  calculateArea(item.geometry);
});

getItemAt(index){*}

返回指定索引处的项目。

参数：

index Number 要检索的集合中项的从零开始的索引。

返回：

类型	说明
*	集合中存储在指定索引处的项。

示例：

// Assigns the base layer at index 0 to baseLayer
let baseLayer = map.basemap.baseLayers.getItemAt(0);

hasEventListener(type){Boolean}

指示实例上是否存在与提供的事件名称匹配的事件侦听器。

参数：

type String 事件的名称。

返回：

类型	说明
布尔值	如果类支持输入事件，则返回 true。

includes(searchElement){Boolean}

测试新集合中是否存在项目。

参数：

searchElement * 要在集合中搜索的项目。

返回：

类型	说明
布尔值	true 如果该项目在集合中。

另请参阅：

• Array.prototype.includes()

示例：

// check if a layer is in the map's operational layers.
if (view.map.layers.includes(myLayer)) {
  // ...
}

indexOf(searchElement, fromIndex){Number}

返回集合中元素的索引。

参数：

searchElement * 要在集合中搜索的项目。

fromIndex Number 可选 如果您不想搜索整个集合或不想从头开始搜索，请使用。

返回：

类型	说明
整数	在集合中找到的第一个匹配项的位置，如果没有匹配项，则为 -1。

另请参阅：

• Array.prototype.indexOf()

示例：

// index is the index of the first graphic in the
// graphics layer that matches the input graphic
let index = graphicsLayer.graphics.indexOf(graphic);

isCollection(value){Boolean}static

确定传递的值是否是一个集合。

参数：

value * 要检查的值。

返回：

类型	说明
布尔值	如果测试通过，则为 true，否则为 false。

join(separator){String}

创建集合中项目的字符串表示形式。

参数：

separator String 可选 默认值：, 最终字符串中每个项目之间使用的分隔符。

返回：

类型	说明
字符串	项目的字符串表示形式。

另请参阅：

• Array.prototype.join()

示例：

let stringCollection = new Collection(["how", "are", "you", "doing?"]);
let phrase = stringCollection.join(" ");

// Prints "how are you doing?"
console.log(phrase);

lastIndexOf(searchElement, fromIndex){Number}

返回集合中元素的最后一个索引。

参数：

searchElement * 要在集合中搜索的项目。

fromIndex Number 可选 如果您不想搜索整个集合，或者不想从末尾搜索，请使用。

返回：

类型	说明
整数	在集合中找到的最后一个匹配项的位置，如果没有匹配项，则为 -1。

另请参阅：

• Array.prototype.lastIndexOf()

示例：

// index is the index of the first graphic in the
// graphics layer that matches the input graphic
let index = graphicsLayer.graphics.lastIndexOf(graphic);

map(callback){Collection}

将每个集合项传递给 callback 函数并返回一个新的返回值数组。例如，如果您有一个数字集合，并且希望将每个数字加 10，则可以使用 map() 创建一个新集合，其中相同的数字增加 10。

参数：

callback ItemMapCallback 处理集合中的每个项目并在原始项目的相同索引处返回新值的函数。

返回：

类型	说明
集合	返回一个新集合，其中包含从 callback 生成的新项目。

另请参阅：

• Array.prototype.map()

示例：

// Gets the geometries of the graphics and assigns them to a new Collection
let geoms = graphicsLayer.graphics.map(function(item, i){
  return item.geometry;
});

ofType(type){Object}static

创建包含类型化对象的集合的子类。

参数：

type Object 分配集合的类型。

返回：

类型	说明
Object	类型化的集合。

示例：

require(["geoscene/core/Collection", "geoscene/geometry/Point"],
  function(Collection, Point){
    let PointCollection = Collection.ofType(Point);
    let collection = new PointCollection();
    collection.add([-100,40]);
    let point = collection.getItemAt(0);
    // point.x = -100; point.y = 40
});

on(type, listener){Object}

在实例上注册事件处理程序。调用此方法以将事件与侦听器挂钩。

参数：

type String|String[] 要侦听的事件或事件数组。

listener Function 事件触发时调用的函数。

返回：

类型	说明
Object	返回带有 remove() 方法的事件处理程序，应调用该方法以停止侦听事件。 属性 类型 说明 remove 函数 调用时，从事件中删除侦听器。

示例：

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

pop(){*}

从集合中删除最后一项并将其返回。

返回：

类型	说明
*	集合中的最后一项。

另请参阅：

• Array.prototype.pop()

示例：

// Removes the last layer in the map and stores it in lastLayer
let lastLayer = map.layers.pop();

push(item){Number}

将项目添加到集合的末尾。

参数：

item * 要添加到集合末尾的项目或以逗号分隔的项目列表。

返回：

类型	说明
整数	集合的新长度。

另请参阅：

• Array.prototype.push()

示例：

// Adds a new graphic to the end of the graphics collection on a GraphicsLayer
graphicsLyr.graphics.push(newGraphic);

// Adds three new graphics to the end of the GraphicsLayer's graphics collection
graphicsLyr.graphics.push(g1, g2, g3);

reduce(callback){*}

使用 callback 将集合中的所有项目（从左到右）减少为单个变量。

参数：

callback ItemReduceCallback 处理集合中的每个项并将其追加到上一项的函数。

返回：

类型	说明
*	处理集合中的每个项并将其追加到上一项的函数。

另请参阅：

• Array.prototype.reduce()

• reduceRight

reduceRight(callback, initialValue){*}

使用 callback 将集合中的所有项目（从右到左）减少为单个变量。

参数：

callback ItemReduceCallback 处理集合中的每个项并将其追加到上一项的函数。

initialValue * 可选 用作在 callback 中处理的第一个元素的项目。

返回：

类型	说明
*	处理集合中的每个项并将其追加到上一项的函数。

另请参阅：

• Array.prototype.reduceRight()

• reduce

remove(item)

从集合中移除一个项目。从集合中删除项目后，将触发更改事件 。

参数：

item * 要删除的项。

示例：

let layer = map.layers.getItemAt(4);
// Removes the fifth layer from the map
map.layers.remove(layer);

removeAll()

从集合中删除所有项目。

示例：

// Removes all layers from the map
map.layers.removeAll();

removeAt(index){*}

从集合中移除指定索引处的项目。从集合中删除项目后，将触发更改事件 。

参数：

index Number 要移除的项目的索引

返回：

类型	说明
*	如果集合中存在，则删除的项目，否则 undefined。

示例：

// Removes the layer at index 4 of the map
map.layers.removeAt(4);

removeMany(items){*}

删除输入数组中的每个项目。如果一个项目在集合中多次出现，则仅删除第一次出现。从集合中删除项目后，将触发更改事件 。

参数：

items Array|Collection 要删除的项目。

返回：

类型	说明
*	集合中存在的已删除项目。

示例：

let refLayers = [refLyr1, refLyr2, refLyr3];
// Removes three reference layers in the refLayers
// collection from the basemap's referenceLayers
map.basemap.referenceLayers.removeMany(refLayers);

reorder(item, index){*}

将集合中的项目移动到指定的索引。在集合中移动项目后，将触发更改事件 。

参数：

item * 要删除的项目。

index Number 要将项目移动到的索引。

返回：

类型	说明
*	被移动的项目。如果 item 不在集合中，则 undefined。

示例：

// Get the first two layers in a map
let layer1 = map.layers.getItemAt(0);
let layer2 = map.layers.getItemAt(1);

// Moves the second layer to the first position in the map.layers Collection
// effectively swapping the positions of layer1 and layer2
map.layers.reorder(layer2, 0);

reverse(){Collection}

将集合反转到位。

返回：

类型	说明
集合	反向集合。

另请参阅：

• Array.prototype.reverse()

示例：

// Reverse layers from the map
map.layers.reverse();

shift(){*}

从集合中删除第一项（在索引 0 处），并将其返回。然后集合的其余项目从它们之前的位置向下移动一个索引。

返回：

类型	说明
*	集合中的第一项。

另请参阅：

• Array.prototype.shift()

示例：

// Removes the first layer in the map and stores it in firstLyr
let firstLyr = map.layers.shift();

slice(begin, end){Collection}

创建一个由原始集合的一部分组成的新集合。

参数：

begin Number 可选 要提取的第一项的索引。

end Number 可选 要提取的最后一项的索引。

返回：

类型	说明
集合	返回包含指定范围内项目的新集合。

另请参阅：

• Array.prototype.slice()

示例：

// get the graphics from index 50 to 100;
let selection = graphicsLayer.graphics.slice(50, 100);

some(callback){Boolean}

确定集合中的项目是否通过 callback 定义的测试。集合中的每个项目都被传递到回调中，直到返回 true 值。

参数：

callback ItemCallback 定义每个集合项的测试的函数。

返回：

类型	说明
布尔值	如果集合中的任何项目通过 callback 中定义的测试，则返回 true。如果所有项目都未通过测试，则返回 false。

另请参阅：

• Array.prototype.some()

示例：

// 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(compareFunction)

对集合进行就地排序。

参数：

compareFunction ItemCompareCallback 可选 定义集合中两个项的比较的函数。

另请参阅：

• Array.prototype.sort()

示例：

// Sort graphics based on their elevation or z-value
let 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(start, deleteCount, items){Array}

删除现有项目和/或将新项目添加到集合中。

参数：

start Number 要开始更改集合的索引。

deleteCount Number 要开始更改集合的索引。如果使用 0，则不会删除任何元素，并且应在 items 参数中添加至少一个新项目。

items * 要添加到集合中的项或以逗号分隔的项列表。

返回：

类型	说明
数组	以前属于集合的已删除项的数组。

另请参阅：

• Array.prototype.splice()

示例：

// map.layers is a collection of 6 layers
// Adds a seventh layer to the map at index 3
map.layers.splice(3, 0, layer7);

// Removes two layers starting from index 2 and adds the
// specified layers in the positions of the former layers
let oldLayers = map.layers.splice(2, 2, layer8, layer9, layer10);

// oldLayers = [layer2, layer3]

toArray(){Array}

返回一个包含集合项的新数组对象。

返回：

类型	说明
数组	包含集合项的数组。

示例：

// Creates an array populated with the map's layers
let mapLayersArray = map.layers.toArray();

unshift(items){Number}

将一个或多个项目添加到集合的开头。

参数：

items * 要添加到集合开头的项目。

返回：

类型	说明
整数	集合的新长度。

另请参阅：

• Array.prototype.unshift()

示例：

// If a map's basemap has 3 baseLayers: baseLyr0, baseLyr1, baseLyr2
map.basemap.baseLayers.unshift(baseLyr3);

// Now the baseLayers collection is: baseLyr3, baseLyr0, baseLyr1, baseLyr2

类型定义

ItemCallback(item, index)

为每个集合项目调用的函数。

参数：

item * 集合中正在评估的当前项目。

index Number 正在评估的项的索引。

ItemCompareCallback(firstItem, secondItem){Number}

定义比较的函数。

参数：

firstItem * 比较中的第一项。

secondItem * 比较中的第二项。

返回：

类型	说明
整数	如果 firstItem 小于 secondItem，则为 -1;如果它们较大，则为 1;如果两者都相等，则为 0。

ItemMapCallback(item, index){*}

定义映射并为每个集合项调用的函数。

参数：

item * 集合中正在评估的当前项目。

index Number 正在评估的项的索引。

返回：

类型	说明
*	替换项的新值。

ItemReduceCallback(previousValue, currentValue, index){*}

定义化简器的函数。

参数：

previousValue * 项目之前已减少价值。

currentValue * 集合中正在评估的当前项目。

index Number 正在评估的项的索引。

返回：

类型	说明
*	要传递给下一个减速器的值。

ItemTestCallback(item, index){Boolean}

定义测试并为每个集合项调用的函数。

参数：

item * 集合中正在评估的当前项目。

index Number 正在评估的项的索引。

返回：

类型	说明
布尔值	如果测试通过，则为 true，否则为 false。

事件概述

{item: *}

{item: *}

{cancellable: Boolean,defaultPrevented: Boolean,item: *,preventDefault: Function}

{cancellable: Boolean,defaultPrevented: Boolean,item: *,preventDefault: Function}

{cancellable: Boolean,defaultPrevented: Boolean,item: *,preventDefault: Function}

{added: Array,moved: Array,removed: Array}

事件详情

after-add

在将项添加到集合后激发。

属性：

item * 将添加到集合中的项。

示例：

// indicates a layer has been added to the map
map.layers.on("after-add", function(event){
  console.log(event.item, " has been added to the map.");
});

after-changes

在添加、重新排序或从集合中删除项目后触发。

示例：

map.layers.on("after-changes", function(event){
  console.log(event, " layer was added/removed from the map.");
});

after-remove

从集合中删除项目后激发。

属性：

item * 要从集合中移除的项目。

示例：

// indicates a layer has been removed from the map
map.layers.on("after-remove", function(event){
  console.log(event.item, " has been removed from the map.");
});

before-add

在将项添加到集合之前激发。此事件可用于通过使用 event.preventDefault() 方法取消项目来防止将项目添加到集合中。

属性：

cancellable Boolean 指示是否可以取消更改事件。

defaultPrevented Boolean 指示此事件之前是否已被另一个事件处理程序取消。

item * 要添加到集合中的项目。

preventDefault Function 一种防止将项目添加到集合中的方法。

示例：

// 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

在对集合执行任何修改之前触发。此事件可用于通过使用 event.preventDefault() 方法取消项目来防止从集合中添加或删除项目。

属性：

cancellable Boolean 指示是否可以取消更改事件。

defaultPrevented Boolean 指示此事件之前是否已被另一个事件处理程序取消。

item * 要从集合中添加或删除的项目。

preventDefault Function 一种防止从集合中添加或删除项目的方法。

示例：

map.layers.on("before-changes", function(event){
  // prevents layers from being added/removed from the map
  event.preventDefault();
});

before-remove

在从集合中删除项目之前触发。此事件可用于通过使用 event.preventDefault() 方法取消项目来防止从集合中添加或删除项目。

属性：

cancellable Boolean 指示是否可以取消更改事件。

defaultPrevented Boolean 指示此事件之前是否已被另一个事件处理程序取消。

item * 要从集合中移除的项目。

preventDefault Function 一种防止从集合中删除项目的方法。

示例：

// prevents a layer from being removed from the basemap
map.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

在收藏中添加、重新排序或 删除物品后触发。使用影响 Collection 类型属性的其他类的方法也会导致此事件触发，例如 Map.add()、Map.remove()、 Map.reorder()。

例如，使用 Map.add() 向 map.layers 集合添加新图层的 map.layers.add(newLyr) 和 map.add(newLyr)将触发此事件。

更改事件可用于通知开发人员/用户对集合的更改。

属性：

added Array 使用 add() 或 addMany() 添加到集合中的项目数组。

moved Array 使用 reorder() 在集合中移动的项目数组。

removed Array 使用 remove()， removeMany()， removeAt() 或 removeAll() 从集合中删除的项目数组。

示例：

// This function will fire each time a layer is either added,
// moved, or removed from the map.layers Collection
map.layers.on("change", function(event){
  let newLayers = event.added; // An array of layers added to the map.layers Collection
  let reorderedLayers = event.moved;  // An array of layers moved in the Collection
  let removedLayers = event.removed;  // An array of layers removed from map
});