LabelCollection

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

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


示例标签


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

为了获得最佳性能，最好选择几个集合，每个集合都有很多标签，而不是多个集合，每个集合只有几个标签。避免有一些标签每帧都会改变而其他标签不会改变的集合；相反，为静态标签创建一个或多个集合，为动态标签创建一个或多个集合。

Name Type Description
options Object 具有以下属性的 可选 对象:
姓名 类型 默认 描述
modelMatrix 矩阵4 Matrix4.IDENTITY 可选 将每个标签从模型转换为世界坐标的 4x4 转换矩阵。
debugShowBoundingVolume 布尔值 false 可选 仅用于调试。确定是否显示此原语的命令的边界球。
scene 场景 可选 必须为使用高度参考属性的标签传递，否则将针对地球进行深度测试。
blendOption 混合选项 BlendOption.OPAQUE_AND_TRANSLUCENT 可选 标签混合选项。默认值用于呈现不透明和半透明标签。但是，如果所有标签都完全不透明或完全半透明，则将技术设置为 BlendOption.OPAQUE 或 BlendOption.TRANSLUCENT 可以将性能提高多达 2 倍。
show 布尔值 true 可选 确定是否显示集合中的标签。
Example: 
// Create a label collection with two labels
const 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 686

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

debugShowBoundingVolume : Boolean
Scene/LabelCollection.js 673

该属性仅用于调试；它不是用于生产用途，也不是优化的。

为图元中的每个绘制命令绘制边界球体。

Default Value: false

length : Number
Scene/LabelCollection.js 700

返回此集合中的标签数。这通常与 LabelCollection#get 一起使用以遍历集合中的所有标签。

modelMatrix : Matrix4
Scene/LabelCollection.js 659

将此集合中的每个标签从模型转换为世界坐标的 4x4 转换矩阵。当这是单位矩阵时，标签是在世界坐标系中绘制的，即地球的 WGS84 坐标系。可以通过提供不同的变换矩阵来使用本地参考帧，就像 Transforms.eastNorthUpToFixedFrame 返回的那样。
Default Value: Matrix4.IDENTITY
Example: 
const 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'
});

show : Boolean
Scene/LabelCollection.js 628

确定是否显示此集合中的标签。
Default Value: true

Methods

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

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

调用 add 是预期的恒定时间。但是，集合的顶点缓冲区被重写；此操作是 O(n) 并且还会导致 CPU 到 GPU 开销。为了获得最佳性能，请在调用 update 之前添加尽可能多的广告牌。

Name Type Description
options Object 可选 描述标签属性的模板，如示例 1 所示。
Returns:
添加到集合中的标签。
Throws:
Examples: 
// Example 1:  Add a label, specifying all the default values.
const 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
});
// Example 2:  Specify only the label's cartographic position,
// text, and font.
const l = labels.add({
  position : Cesium.Cartesian3.fromRadians(longitude, latitude, height),
  text : 'Hello World',
  font : '24px Helvetica',
});
See:

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

检查此集合是否包含给定标签。
Name Type Description
label Label 要检查的标签。
Returns:
如果此集合包含标签，则为 true，否则为 false。
See:

destroy ()
Scene/LabelCollection.js 984

销毁此对象持有的 WebGL 资源。销毁一个对象允许确定性地释放 WebGL 资源，而不是依赖垃圾收集器来销毁这个对象。

一旦一个对象被销毁，它就不应该被使用；调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。因此，如示例中所做的那样，将返回值 ( undefined ) 分配给对象。
Throws:
Example: 
labels = labels && labels.destroy();
See:

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

返回集合中指定索引处的标签。索引从零开始，随着标签的添加而增加。删除标签会将其后的所有标签向左移动，从而更改它们的索引。此函数通常与 LabelCollection#length 一起使用，以遍历集合中的所有标签。
Performance:

预期的恒定时间。如果从集合中删除标签并且未调用 Scene#render ，则执行隐式 O(n) 操作。

Name Type Description
index Number 广告牌的从零开始的索引。
Returns:
指定索引处的标签。
Throws:
Example: 
// Toggle the show property of every label in the collection
const len = labels.length;
for (let i = 0; i < len; ++i) {
  const l = billboards.get(i);
  l.show = !l.show;
}
See:

isDestroyed () → Boolean
Scene/LabelCollection.js 964

如果此对象被销毁，则返回 true；否则为假。

如果该对象被销毁，则不应使用；调用 isDestroyed 以外的任何函数都会导致 DeveloperError 异常。
Returns:
如果此对象被销毁，则为真；否则为假。
See:

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

从集合中删除标签。删除后，标签将不再可用。
Performance:

调用 remove 是预期的恒定时间。但是，集合的顶点缓冲区被重写 - 一个 O(n) 操作，也会导致 CPU 到 GPU 开销。为了获得最佳性能，请在调用 update 之前删除尽可能多的标签。如果您打算暂时隐藏标签，调用 Label#show 通常比删除并重新添加标签更有效。

Name Type Description
label Label 要删除的标签。
Returns:
如果标签被移除，则为 true ；如果在集合中找不到标签，则 false 。
Throws:
Example: 
const l = labels.add(...);
labels.remove(l);  // Returns true
See:

removeAll ()
Scene/LabelCollection.js 820

从集合中删除所有标签。
Performance:

O(n) 。从集合中删除所有标签然后添加新标签比完全创建新集合更有效。

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