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 Maps SDK for JavaScript 4.7

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

length Number

集合中项目数。

方法概述

方法详细说明

add(item, index)

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

参数

item * 要添加的项目。

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

示例

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

addHandles(handleOrHandles, groupKey)inherited

起始版本：GeoScene Maps SDK for JavaScript 4.25

添加一个或多个与对象的生命周期相关联的句柄。当对象被销毁时，将移除句柄。

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

// Handle gets removed when the object is destroyed.
this.addHandles(handle);

参数

handleOrHandles WatchHandle|WatchHandle[] 对象销毁后，标记为要移除的句柄。

groupKey * optional 标识句柄应添加到的组的键。组中的所有句柄稍后都可使用 Accessor.removeHandles() 进行删除。如果未提供键，则句柄将被添加到默认组。

addMany(items, index)

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

参数

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

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

示例

// 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 Maps SDK 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()。

返回

类型	描述
Collection	调用此方法的集合的克隆。

另请参阅

• slice()

示例

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

concat(value){Collection}

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

参数

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

返回

类型	描述
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 Maps SDK for JavaScript 4.5

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

参数

type String 事件的名称。

event Object optional 事件有效负载。

返回

类型	描述
Boolean	如果监听器收到通知，则为true

every(callback){Boolean}

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

参数

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

返回

类型	描述
Boolean	如果对 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 函数定义的测试过滤 Collection 的项目。每个项目都被传递到 callback 函数中，如果项目通过测试，则返回 true，否则返回 false。

参数

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

返回

类型	描述
Collection	返回包含通过过滤器测试的项目的新集合。

另请参阅

• 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 函数中定义的测试，则返回 Collection 中的项目。每个项目都被传递到 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 函数中定义的测试，则返回 Collection 中项目的索引。每个项目都被传递到 callback 函数中，如果项目通过测试，则返回 true，否则返回 false。

参数

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

返回

类型	描述
Number	返回满足测试函数的集合项目的索引。如果项目未通过测试，则返回 -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}

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

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

参数

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

返回

类型	描述
Collection	返回原始集合中所有项目及其子项的平面集合。

示例

// 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 事件的名称。

返回

类型	描述
Boolean	如果类支持输入事件，则返回 true。

hasHandles(groupKey){Boolean}inherited

起始版本：GeoScene Maps SDK for JavaScript 4.25

如果存在指定的句柄组，则返回 true。

参数

groupKey * optional 组键。

返回

类型	描述
Boolean	如果存在指定的句柄组，则返回 true。

示例

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

includes(searchElement){Boolean}

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

参数

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

返回

类型	描述
Boolean	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 optional 如果您不想搜索整个集合或不想从头开始搜索，请使用该选项。

返回

类型	描述
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 * 要检查的值。

返回

类型	描述
Boolean	如果测试通过，则为 true，否则为 false。

join(separator){String}

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

参数

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

返回

类型	描述
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 optional 如果您不想搜索整个集合或不想从末尾搜索，请使用该选项。

返回

类型	描述
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 处理集合中的每个项目并在原始项目的相同索引处返回新值的函数。

返回

类型	描述
Collection	返回一个新集合，其中包含从 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 Function 调用时，从事件中移除监听器。

示例

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 * 要添加到集合末尾的项目或以逗号分隔的项目列表。

返回

类型	描述
Number	集合的新长度。

另请参阅

• 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 * optional 用作在 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);

removeHandles(groupKey)inherited

起始版本：GeoScene Maps SDK for JavaScript 4.25

移除对象拥有的句柄组。

参数

groupKey * optional 要移除的组键或组键的数组或集合。

示例

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

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}

适当地反向集合。

返回

类型	描述
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 optional 要提取的第一个项目的索引。

end Number optional 要提取的最后一个项目的索引。

返回

类型	描述
Collection	返回包含指定范围内项目的新集合。

另请参阅

• 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 定义每个集合项的测试的函数。

返回

类型	描述
Boolean	如果集合中的任何项目均通过 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 optional 定义集合中两个项目的比较的函数。

另请参阅

• 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	以前属于集合的已删除项目数组。

另请参阅

• 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}

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

返回

类型	描述
Array	包含集合项目的数组。

示例

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

unshift(items){Number}

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

参数

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

返回

类型	描述
Number	集合的新长度。

另请参阅

• 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 * 比较中的第二个项目。

返回

类型	描述
Number	如果 firstItem 小于 secondItem，则为 -1；如果 firstItem 大于 secondItem，则为 1；如果两者相等，则为 0。

ItemMapCallback(item, index){*}

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

参数

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

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

返回

类型	描述
*	替换项目的新值。

ItemReduceCallback(previousValue, currentValue, index){*}

定义缩减器的函数。

参数

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

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

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

返回

类型	描述
*	要传递给下一个缩减器的值。

ItemTestCallback(item, index){Boolean}

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

参数

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

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

返回

类型	描述
Boolean	如果测试通过，则为 true，否则为 false。

事件概述

事件详细说明

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
});