LabelCollection

new Cesium.LabelCollection(options)
Scene/LabelCollection.js 536

标签的可渲染集合。标签是位于3D场景中与视口对齐的文本。每个标签可以具有不同的字体，颜色，比例等。


标签示例


使用LabelCollection#add和LabelCollection#remove从集合中添加和删除标签。
Performance:

为了获取更好的性能，最好是创建较少的集合，每个集合有较多的标签，而不是较多的集合，每个集合中有较少的标签。 组织集合的时候，将有相同更新频率的标签放在一个集合，不更新的标签放在一个集合。

Name Type Description
options Object optional 具有下列属性的对象：
Name Type Default Description
modelMatrix Matrix4 Matrix4.IDENTITY optional 4x4转换矩阵，将每个标签从模型坐标转换为世界坐标。
debugShowBoundingVolume Boolean false optional 仅用于调试。确定是否显示此图元的包围球。
scene Scene optional 对于具有高度参考属性和进行深度测试的标签，必须传入此对象。
blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT optional 标签混合选项。默认值用于渲染不透明和半透明的标签。但是，如果所有标签都完全不透明或全部完全透明，将技术设置为BlendOption.OPAQUE或BlendOption.TRANSLUCENT最多可以将性能提高2倍。
Example:
// 创建一个标签集合并添加两个标签。
var labels = scene.primitives.add(new Cesium.LabelCollection());
labels.add({
  position : new Cesium.Cartesian3(1.0, 2.0, 3.0),
  text : 'A label'
});
labels.add({
  position : new Cesium.Cartesian3(4.0, 5.0, 6.0),
  text : 'Another label'
});
Demo:
See:

Members

blendOption : BlendOption
Scene/LabelCollection.js 613

标签混合选项。默认值用于渲染不透明和半透明的标签。但是，如果所有标签都完全不透明或全部完全透明，将技术设置为BlendOption.OPAQUE或BlendOption.TRANSLUCENT最多可以将性能提高2倍。
Default Value: BlendOption.OPAQUE_AND_TRANSLUCENT

debugShowBoundingVolume : Boolean
Scene/LabelCollection.js 606

此属性仅用于调试;它既不用于生产，也不是最优的。

是否显示图元的包围球。

Default Value: false

length : Number
Scene/LabelCollection.js 622

返回集合中标签的个数，这通常与LabelCollection#get一起使用，用于迭代集合中的所有标签。

modelMatrix : Matrix4
Scene/LabelCollection.js 594

4x4转换矩阵，可将每个标签从模型坐标转换为世界坐标。 当这是单位矩阵时，将以世界坐标（即地球的WGS84坐标）绘制标签。 可以通过Transforms.eastNorthUpToFixedFrame获取。
Default Value: Matrix4.IDENTITY
Example:
var center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
labels.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
labels.add({
  position : new Cesium.Cartesian3(0.0, 0.0, 0.0),
  text     : 'Center'
});
labels.add({
  position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0),
  text     : 'East'
});
labels.add({
  position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0),
  text     : 'North'
});
labels.add({
  position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0),
  text     : 'Up'
});

Methods

add(options) → Label
Scene/LabelCollection.js 678

创建具有指定初始属性的标签并将其添加到集合中。 将返回添加的标签，以便以后可以修改或从集合中删除它。
Performance:

调用add是预期的不变时间。 然而，集合的顶点缓冲区被重写；这个操作是O(n)，也会增加CPU到GPU的开销。 为了获得最佳性能，在调用update之前，请尽可能地添加标签。

Name Type Description
options Object optional 描述标签属性的模板，如示例1所示。
Returns:
将要添加到集合中的标签。
Throws:
Examples:
// 例1：添加一个标签，指定所有的默认值。
var l = labels.add({
  show : true,
  position : Cesium.Cartesian3.ZERO,
  text : '',
  font : '30px sans-serif',
  fillColor : Cesium.Color.WHITE,
  outlineColor : Cesium.Color.BLACK,
  outlineWidth : 1.0,
  showBackground : false,
  backgroundColor : new Cesium.Color(0.165, 0.165, 0.165, 0.8),
  backgroundPadding : new Cesium.Cartesian2(7, 5),
  style : Cesium.LabelStyle.FILL,
  pixelOffset : Cesium.Cartesian2.ZERO,
  eyeOffset : Cesium.Cartesian3.ZERO,
  horizontalOrigin : Cesium.HorizontalOrigin.LEFT,
  verticalOrigin : Cesium.VerticalOrigin.BASELINE,
  scale : 1.0,
  translucencyByDistance : undefined,
  pixelOffsetScaleByDistance : undefined,
  heightReference : HeightReference.NONE,
  distanceDisplayCondition : undefined
});
// 例2：只指定标签的绘图位置、文本和字体。
var l = labels.add({
  position : Cesium.Cartesian3.fromRadians(longitude, latitude, height),
  text : 'Hello World',
  font : '24px Helvetica',
});
See:

contains(label) → Boolean
Scene/LabelCollection.js 752

检查此集合是否包含给定的标签。
Name Type Description
label Label 要查找的标签。
Returns:
如果包含该标签返回true。
See:

destroy()
Scene/LabelCollection.js 880

销毁此对象持有的WebGL资源。

一旦对象被销毁，它将不能在使用；调用除isDestroyed之外的任何函数都会导致DeveloperError异常。 因此，将返回值(undefined)赋给对象，如示例所示。
Throws:
Example:
labels = labels && labels.destroy();
See:

get(index) → Label
Scene/LabelCollection.js 778

返回集合中指定索引处的标签。 这个函数通常与LabelCollection#length一起使用，用于迭代集合中的所有标签。
Performance:

期望的不变时间。如果从集合中删除了标签，并且没有调用Scene#render，则执行隐式O(n)操作。

Name Type Description
index Number 索引
Returns:
索引处的标签。
Throws:
Example:
// 切换集合中每个标签的show属性
var len = labels.length;
for (var i = 0; i < len; ++i) {
  var l = billboards.get(i);
  l.show = !l.show;
}
See:

isDestroyed() → Boolean
Scene/LabelCollection.js 863

如果该对象没被销毁，返回false。

如果该对象已经被销毁，使用isDestroyed 会触发 DeveloperError 异常。
Returns:
false
See:

remove(label) → Boolean
Scene/LabelCollection.js 706

从集合中移除标签。一旦移除，标签将不再可用。
Performance:

如果您打算暂时隐藏标签，通常可以调用Label#show 而不是删除并重新添加标签。

Name Type Description
label Label 将要被移除的标签。
Returns:
移除成功返回true,如果标签不在集合中返回false。
Throws:
Example:
var l = labels.add(...);
labels.remove(l);  // Returns true
See:

removeAll()
Scene/LabelCollection.js 733

移除集合中的所有标签。
Performance:

从集合中删除所有标签然后添加新标签比完全创建新集合效率更高。

Throws:
Example:
labels.add(...);
labels.add(...);
labels.removeAll();
See: