Collection

集合存储相同类型的项的数组。它为处理集合中的项提供了有用的实用方法，包括filter()、find()和reduce()。

集合可以是任何类型的。例如GraphicsLayer。图形是存储在GraphicsLayer中的图形的集合。可以使用集合类中的方法在GraphicsLayer中添加、删除、重新排序或操作图形。

集合的另一个例子是Map。图层是映射中包含的操作层的集合。

// 使用Collection.remove()从映射中删除一个图层;
map.layers.remove(layer);

每当从集合中添加、移动或移除项时，就会触发更改事件。由于不能监视类型集合的属性，所以应该使用更改事件来通知开发人员/用户对集合的更改。

构造函数

new Collection(properties)：有关可能被传递到构造函数的所有属性的列表，请参阅属性。

属性概述

• length：集合中的项数。类型为Number。

方法概述

• add()：向集合中添加单个项。
• addMany()：向集合中添加多个项。
• clone()：创建集合的深度克隆。
• concat()：创建包含原始集合中与输入数组或集合中的项联接的项的新集合。
• emit()：在实例上发出事件。
• every()：确定集合中的所有项是否通过回调定义的测试。
• filter()：根据回调函数定义的测试筛选集合的项。
• find()：返回集合中的项，如果该项通过回调函数中定义的测试。
• findIndex()：如果集合中的项通过回调函数中定义的测试，则返回该项的索引。
• flatten()：扁平化至少包含一个子集合的分层集合。
• forEach()：为集合中的每个项执行输入函数。
• getItemAt()：返回位于指定索引处的项。
• hasEventListener()：指示实例上是否有与所提供的事件名称匹配的事件侦听器。
• includes()：测试新集合中是否存在项。
• indexOf()：返回集合中元素的索引。
• isCollection()：确定传递的值是否是一个集合。
• join()：创建集合中项的字符串表示形式。
• lastIndexOf()：返回集合中元素的最后一个索引。
• map()：将每个集合项传递到回调函数并返回返回值的新数组。
• ofType()：创建包含类型化对象的集合的子类。
• on()：在实例上注册一个事件处理程序。
• pop()：从集合中移除最后一项并返回它。
• push()：将项添加到集合的末尾。
• reduce()：使用回调将集合中的所有项(从左到右)减少为单个变量。
• reduceRight()：使用回调将集合中的所有项(从右到左)减少为单个变量。
• remove()：从集合中删除项。
• removeAll()：从集合中删除所有项。
• removeAt()：从集合中指定索引处移除项。
• removeMany()：删除输入数组中的每个项。
• reorder()：将集合中的项移动到指定索引。
• reverse()：在适当的位置反转集合。
• shift()：从集合中删除第一项(在索引0处)，并返回它。
• slice()：创建由原始集合的一部分组成的新集合。
• some()：确定集合中的项是否通过回调定义的测试。
• sort()：对集合进行适当的排序。
• splice()：删除现有项和/或向集合中添加新项。
• toArray()：返回包含集合项的新数组对象。
• unshift()：将一个或多个项添加到集合的开头。

方法详情

• add(item, index)：向集合中添加单个项。在将项添加到集合后触发更改事件。参数：
  • item：要添加的项目。
  • index ：要添加项的集合中位置的从零开始的索引。如果未指定，则项目将添加到末尾。

var gpc = new Graphic();  // 创建一个新图形
var layer = new GraphicsLayer(); // 创建一个新的图形层
layer.graphics.add(gpc);  // 添加图形到层的图形集合

• addMany(items, index)：向集合中添加多个项。在将项添加到集合后触发更改事件。参数：
  • items ：要添加的项的数组或集合。
  • index ：集合中要添加项的位置的从零开始的索引。如果未指定，则项目将添加到末尾。

//创建两个新图形
var gpc1 = new Graphic();
var gpc2 = new Graphic();
var layer = new GraphicsLayer(); // Creates a new graphics layer
// 添加这两个图形到层的图形集合
layer.graphics.addMany([gpc1, gpc2]);

• clone()：创建集合的深度克隆。要创建集合的浅克隆，请使用slice()。

var slides = scene.presentation.slides.clone();

• concat(value)：创建包含原始集合中与输入数组或集合中的项联接的项的新集合。参数：
  • value ：要追加到现有集合的数组或集合。

// 创建所有基础地图层的集合。
var basemap = map.basemap;
var basemapLayers = basemap.baseLayers.concat(basemap.referenceLayers);

• emit(type, event)：在实例上发出事件。此方法只应在创建该类的子类时使用。参数：
  • type ：事件的名称。
  • event ：事件有效负载。

• every(callback)：确定集合中的所有项是否通过回调定义的测试。集合中的每一项都被传递到回调中，直到其中一项返回false值。参数：
  • callback ：要为集合中的每个项调用的函数。

var meetsStandardSize = graphicsLayer.graphics.every(function(item, i){
  // 测试每个几何图形的面积，看看是否大于1000英亩
  return calculateArea(item.geometry) > 1000;
});

• filter(callback)：根据回调函数定义的测试筛选集合的项。每个项目都被传递到回调函数中，如果项目通过测试，则返回true，如果没有通过测试，则返回false。参数：
  • callback ：定义用于确定是否返回新集合中的项的测试的函数。

var filteredLayers = map.layers.filter(function(layer){
  return !layer.visible;
});

• find(callback)：返回集合中的项，如果该项通过回调函数中定义的测试。每个项目都被传递到回调函数中，如果项目通过测试，则返回true，如果没有通过测试，则返回false。参数：
  • callback ：将评估集合中的每个项的测试功能。如果项目通过测试，则返回true;如果项目失败，则返回false。

var myLayer = map.layers.find(function(layer){
  return layer.id === "speciesLyr01";
});

• findIndex(callback)：如果集合中的项通过回调函数中定义的测试，则返回该项的索引。每个项目都被传递到回调函数中，如果项目通过测试，则返回true，如果没有通过测试，则返回false。参数
  • callback ：将评估集合中的每个项的测试功能。如果项目通过测试，则返回true;如果项目失败，则返回false。

var gpcIndex = graphicsLyr.graphics.findIndex(function(item){
  return item.attributes.name === "Redlands";
});

• flatten(callback)：扁平化至少包含一个子集合的分层集合。集合中的每个项都被传递到回调函数中，该函数应该检查开发人员指定的子集合。返回所有项目(父项目和子项目)的平面集合。这对于用户希望搜索地图中的所有层(包括GroupLayer的层和MapImageLayer的子层)的场景非常有用。回调应该返回项的子集合。如果层次结构中存在多个级别的集合，则此方法对所有子集合递归执行。参数：
  • callback ：对集合中的每个项进行评估的函数。

//创建一个带有几个子层的MapImageLayer，并将其添加到包含另一个GraphicsLayer的map中
var layer = new MapImageLayer({ sublayers: [ ... ] });
var map = new Map({
  layers: [ layer, new GraphicsLayer() ]
});
// map中所有层和子层的平面集合(如果层是MapImageLayer)。此集合可能被搜索或用于其他目的
var allLayersAndSublayers = map.layers.flatten(function(item){
  return item.layers || item.sublayers;
});

• forEach(callback):为集合中的每个项执行输入函数。
  • callback :要为集合中的每个项调用的函数。

graphicsLayer.graphics.forEach(function(item, i){
  // 对每个图形做点什么，比如计算几何图形的面积
  calculateArea(item.geometry);
});

• getItemAt(index):返回位于指定索引处的项。参数
  • index ：要检索的集合中项的从零开始的索引。

// 将索引为0的基础层分配到基线层
var baseLayer = map.basemap.baseLayers.getItemAt(0);

• hasEventListener(type)：指示实例上是否有与所提供的事件名称匹配的事件侦听器。返回值类型Boolean。参数
  • type ：事件的名称。

• includes(searchElement)：测试新集合中是否存在项。返回值类型Boolean。参数
  • searchElement ：要在集合中搜索的项。

// 检查一个图层是否在地图的操作层中。
if (view.map.layers.includes(myLayer)) {
  // ...
}

• indexOf(searchElement, fromIndex)：返回集合中元素的索引。参数
  • searchElement ：要在集合中搜索的项。
  • fromIndex ：如果不想搜索整个集合，或者不想从一开始就搜索，可以使用。

// index是图形层中与输入图形匹配的第一个图形的索引
var index = graphicsLayer.graphics.indexOf(graphic);

• isCollection(value)：确定传递的值是否是一个集合。返回值类型Boolean。参数
  • value ：要检查的值。

• join(separator)：创建集合中项的字符串表示形式。参数
  • separator ：最后字符串中每个项之间使用的分隔符。返回值类型为String。默认值是‘，’

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

• lastIndexOf(searchElement, fromIndex)：返回集合中元素的最后一个索引。返回类型为Number。参数
  • searchElement ：要在集合中搜索的项。
  • fromIndex ：如果不想搜索整个集合，或者不想从末尾开始搜索，可以使用。

var index = graphicsLayer.graphics.lastIndexOf(graphic);

• map(callback)：将每个集合项传递到回调函数并返回返回值的新数组。例如，如果您有一个数字集合，并且希望将每个数字增加10，那么可以使用map()创建一个新的集合，使相同的数字增加10。返回值类型Collection。参数
  • callback ：处理集合中的每个项并在原始项的相同索引处返回新值的函数。

var geoms = graphicsLayer.graphics.map(function(item, i){
  return item.geometry;
});

• ofType(type)：创建包含类型化对象的集合的子类。返回值类型Object。参数
  • type ：要分配集合的类型。

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

• on(type, listener)：在实例上注册一个事件处理程序。调用此方法将事件与侦听器挂钩。返回值类型为Object。参数
  • type ：要侦听的事件类型或事件类型数组。
  • listener ：事件触发时要调用的函数。

view.on("click", function(event){
  console.log(event.mapPoint);
});

• pop()：从集合中移除最后一项并返回它。

//删除地图的最后一层并将其存储在lastLayer中
var lastLayer = map.layers.pop();

• push(item)：将项添加到集合的末尾。返回值类型为Number。参数
  • item ：要添加到集合末尾的项或以逗号分隔的项列表。

//在GraphicsLayer上将新图形添加到图形集合的末尾
graphicsLyr.graphics.push(newGraphic);
//在GraphicsLayer的图形集合的末尾添加三个新的图形
graphicsLyr.graphics.push(g1, g2, g3);

• reduce(callback)：使用回调将集合中的所有项(从左到右)减少为单个变量。参数
  • callback ：处理集合中的每一项并将其附加到前一项的函数。

• reduceRight(callback, initialValue)：使用回调将集合中的所有项(从右到左)减少为单个变量。参数
  • callback ：处理集合中的每一项并将其附加到前一项的函数。
  • initialValue ：项作为回调中要处理的第一个元素。

• remove(item)：从集合中删除项。在从集合中删除项后触发更改事件。参数
  • item ：要删除的项。

var layer = map.layers.getItemAt(4);
// 从地图中移除第五层
map.layers.remove(layer);

• removeAll()：从集合中删除所有项。

// 从地图中删除所有图层
map.layers.removeAll();

• removeAt(index)：从集合中指定索引处移除项。在从集合中删除项后触发更改事件。参数
  • index ：要删除的项的索引。

//移除地图索引4处的图层
map.layers.removeAt(4);

• removeMany(items)：删除输入数组中的每个项。如果一个项在集合中出现多次，则只删除第一个项。在从集合中删除项后触发更改事件。参数
  • items ：要删除的项目。

var refLayers = [refLyr1, refLyr2, refLyr3];
// 从basemap的referencelers中删除refLayers集合中的三个引用层
map.basemap.referenceLayers.removeMany(refLayers);

• reorder(item, index)：将集合中的项移动到指定索引。在集合中移动项后触发更改事件。参数
  • item：要移动的项目。
  • index：要将项移动到的索引。

// 在一个地图中获得前两层
var layer1 = map.layers.getItemAt(0);
var layer2 = map.layers.getItemAt(1);

// 将第二层移动到地图的第一个位置。layer Collection有效的交换layer1和layer2的位置
map.layers.reorder(layer2, 0);

• reverse()：在适当的位置反转集合。返回值类型Collection。

// 从地图反向图层
map.layers.reverse();

• shift()：从集合中删除第一项(在索引0处)，并返回它。然后，将集合的其余项从它们以前的位置向下移动一个索引。

// 删除地图的第一层，并将其存储在firstLyr中
var firstLyr = map.layers.shift();

• slice(begin, end)：创建由原始集合的一部分组成的新集合。返回值类型Collection。参数
  • begin ：要提取的第一项的索引。
  • end ：要提取的最后一项的索引。

// 从索引50到100获取图形;
var selection = graphicsLayer.graphics.slice(50, 100);

• some(callback)：确定集合中的项是否通过回调定义的测试。集合中的每一项都被传递到回调中，直到其中一项返回true值为止。返回值类型为Boolean。参数
  • callback ：为每个集合项定义测试的函数。

//如果至少有一个点图形具有高程在1000米以上的几何图形，那么通道的值将为true。否则，为false。
var passes = graphicsLayer.graphics.some(function(item, i){
  return item.geometry.z > 1000;
});

• sort(compareFunction)：对集合进行适当的排序。参数
  • compareFunction ：定义集合中两个项的比较的函数。

// 根据高度或z值对图形进行排序
var 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 ：从其中开始更改集合的索引。
  • deleteCount ：指示要删除的集合项的数目。如果使用0，则不删除任何元素，并且至少应该在items参数中添加一个新项。
  • items ：要添加到集合中的项或以逗号分隔的项列表。

// map.layers 是6层的集合
// 在地图索引3处添加第7层
map.layers.splice(3, 0, layer7);
// 从索引2开始删除两个层，并将指定的层添加到前两个层的位置
var oldLyrs = map.layers.splice(2, 2, layer8, layer9, layer10);

• toArray()：返回包含集合项的新数组对象。返回值类型为Array。

// 创建一个填充了地图层的数组
var mapLyrsArray = map.layers.toArray();

• unshift(items)：将一个或多个项添加到集合的开头。返回值类型为Number。参数
  • items ：要添加到集合开头的项。

map.basemap.baseLayers.unshift(baseLyr3);

类型定义

• ItemCallback(item, index)：为每个集合项调用的函数。参数
  • item ：在集合中被评估的当前项。
  • index ：被评估项目的指标。

• ItemCompareCallback(firstItem, secondItem)：定义比较的函数。返回值类型为Number。参数
  • firstItem ：较中的第一项。
  • secondItem ：比较中的第二项。

• ItemMapCallback(item, index)：定义映射并为每个集合项调用的函数。参数
  • item ：在集合中被评估的当前项。
  • index ：被评估项目的指标。

• ItemReduceCallback(previousValue, currentValue, index)：定义减速的函数。参数
  • previousValue ：项之前对比值
  • currentValue ：在集合中当前项正在被使用的。
  • index ：正在被使用项的索引

• ItemTestCallback(item, index)：定义测试并为每个集合项调用的函数。返回值类型Boolean。参数
  • item ：在集合中被使用的当前项。
  • index ：正在被使用项的索引。

事件概述

名称	类型	概要
after-add	{ item: * }	在将项添加到集合后触发。
after-changes		在添加、重新排序或从集合中移除项后触发。
after-remove	{ item: * }	在从集合中移除项后触发。
before-add	{ cancellable: Boolean, defaultPrevented: Boolean, item: *, preventDefault: Function }	在将项添加到集合之前触发。
before-changes	{ cancellable: Boolean, defaultPrevented: Boolean, item: *, preventDefault: Function }	在对集合执行任何修改之前触发。
before-remove	{ cancellable: Boolean, defaultPrevented: Boolean, item: *, preventDefault: Function }	在项目从集合中移除之前触发。
change	{ added: Array, moved: Array, removed: Array }	在添加、重新排序或从集合中删除项后触发。

事件详情

• after-add：在将项添加到集合后触发。属性
  • item ：添加到集合中的项。

// 指示一个图层被添加到地图中
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 ：要从集合中移除的项。

// 表示一个图层已经从地图中删除
map.layers.on("after-remove", function(event){
  console.log(event.item, " has been removed from the map.");
});

• before-add：在将项添加到集合之前触发。此事件可用于通过使用event. preventdefault()方法取消某个项，从而阻止该项被添加到集合中。属性
  • cancellable ：指示更改事件是否可以取消。
  • defaultPrevented ：指示此事件以前是否已被另一个事件处理程序取消。
  • item ：要添加到集合中的项。
  • preventDefault ：阻止将项添加到集合中的方法。

// 防止一个图层被添加到地图中不止一次。
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 ：指示更改事件是否可以取消。
  • defaultPrevented ：指示此事件以前是否已被另一个事件处理程序取消。
  • item ：要从集合中添加或移除的项。
  • preventDefault ：阻止从集合中添加或删除项的方法。

map.layers.on("before-changes", function(event){
  // 防止图层被添加/删除
  event.preventDefault();
});

• before-remove：在项目从集合中移除之前触发。此事件可用于使用event. preventdefault()方法取消某个项，从而防止该项从集合中删除。属性
  • cancellable ：指示更改事件是否可以取消。
  • defaultPrevented ：指示此事件以前是否已被另一个事件处理程序取消。
  • item ：要从集合中移除的项。
  • preventDefault ：阻止从集合中删除项的方法。

// 防止从基本地图中删除一个层
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：在添加、重新排序或从集合中删除项后触发。使用影响类型集合属性的其他类的方法也会触发此事件，如Map.add()、Map.remove()、Map.reorder()。

例如，map.layers.add(newLyr) and map.add(newLyr)使用map.add()为地图添加一个新图层。层集合将触发此事件。

不能监视类型集合的属性。变更事件应该用来通知开发人员/用户集合的变更。

属性

• added ：使用add()或addMany()添加到集合中的项数组。
• moved ：使用reorder()在集合中移动的项数组。
• removed ：使用remove()、removeMany()、removeAt()或removeAll()从集合中删除的项的数组。

// 每当一个图层被添加、移动或从图层集合中移除时，此函数将触发。 
map.layers.on("change", function(event){
  var newLayers = event.added; //添加到地图的图层集合。
  var reorderedLayers = event.moved;  // 在集合中移动的层数组  var removedLayers = event.removed;  // 从地图中删除的层数组
});