LabelCollection

new Cesium.LabelCollection(options)

engine/Source/Scene/LabelCollection.js 593

可渲染标签的集合。标签是与视口对齐的文本，位于 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 倍。 show boolean true optional 决定集合中的标签是否显示。

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:

• Cesium Sandcastle Labels Demo

See:

• LabelCollection#add
• LabelCollection#remove
• Label
• BillboardCollection

Members

Default Value: BlendOption.OPAQUE_AND_TRANSLUCENT

Default Value: false

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

Default Value: true

Methods

Performance:

调用 add 的预期时间复杂度为常量时间。然而，集合的顶点缓冲区会被重写；这个操作是 O(n)，并且还会产生 CPU 到 GPU 的开销。为了获得最佳性能，尽可能在调用 update 之前添加尽可能多的公告牌。

Returns:

Throws:

• DeveloperError : 此对象已被销毁，即调用了 destroy()。

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:

• LabelCollection#remove
• LabelCollection#removeAll

Returns:

See:

• LabelCollection#get

Throws:

• DeveloperError : 此对象已被销毁，即调用了 destroy()。

Example:

labels = labels && labels.destroy();

See:

• LabelCollection#isDestroyed

Performance:

预计时间复杂度为常量时间。如果从集合中移除标签并且 Scene#render 没有被调用，则会执行隐式的 O(n) 操作。

Returns:

Throws:

• DeveloperError : 此对象已被销毁，即调用了 destroy()。

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:

• LabelCollection#length

Returns:

See:

• LabelCollection#destroy

Performance:

调用 remove 的预期时间复杂度为常量时间。然而，集合的顶点缓冲区会被重写 - 这是一个 O(n) 的操作，并且会产生 CPU 到 GPU 的开销。为了获得最佳性能，尽可能在调用 update 之前移除尽可能多的标签。 如果您打算临时隐藏标签，通常调用 Label#show 会比移除和重新添加标签更有效。

Returns:

Throws:

• DeveloperError : 此对象已被销毁，即调用了 destroy()。

Example:

const l = labels.add(...);
labels.remove(l);  // Returns true

See:

• LabelCollection#add
• LabelCollection#removeAll
• Label#show

Performance:

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

Throws:

• DeveloperError : 此对象已被销毁，即调用了 destroy()。

Example:

labels.add(...);
labels.add(...);
labels.removeAll();

See:

• LabelCollection#add
• LabelCollection#remove