Legend

图例微件描述了用于表示地图中图层的符号。此微件中使用的所有符号和文本都在图层的渲染器中进行配置。图例将仅显示视图中可见的图层和子图层。

图例在以下情况下自动更新：

图层或子图层的可见性发生变化
在地图中添加或删除图层
图层的 renderer、opacity 或 title 已更改
legendEnabled 属性已更改（在图层上设置为 true 或 false）

您可以使用视图的 DefaultUI 通过视图上的 ui 属性将微件添加到视图的用户界面。

已知限制

目前，图例微件不支持以下图层类型ElevationLayer、GraphicsLayer、IntegratedMeshLayer、KMLLayer、MapNotesLayer、OpenStreetMapLayer、VectorTileLayer 和 WebTileLayer。
不支持具有多个符号图层的 3D 符号。
不支持 DictionaryRenderer。

展开下面的“阅读更多”部分，查看基于渲染器类型的各种图例示例。

Unique values

Continuous color

Classed color

Continuous size

Size - above and below

Dot density

Predominance

Relationship

另请参阅：

示例：

let legend = new Legend({
  view: view
});

view.ui.add(legend, "bottom-right");

构造函数

new Legend(properties)

参数：

properties Object

optional

有关可能传递到构造函数中的所有属性的列表，请参阅属性。

示例：

// typical usage
let legend = new Legend({
  view: view
});

属性概述

可以设置、检索或侦听任何属性。请参阅使用属性主题。

显示继承的属性

隐藏继承的属性

类型	描述	类：
Collection<ActiveLayerInfo>	更多详情图例视图用于在图例中显示数据的 ActiveLayerInfo 对象的集合。	更多详情	Legend
Boolean	更多详情指示是否在图例中显示底图图层。	更多详情	Legend
String\|HTMLElement	更多详情表示包含微件的 DOM 元素的 ID 或节点。	更多详情	Widget
String	更多详情类的名称。	更多详情	Accessor
Number	更多详情指示要用于图例标题的标题级别。	更多详情	Legend
Boolean	更多详情当 `true` 时，仅当图层在视图的扩展范围内可见时，这些图层才会显示在图例中。	更多详情	Legend
String	更多详情微件的默认 CSS 图标类。	更多详情	Legend
String	更多详情创建微件时分配给微件的唯一 ID。	更多详情	Widget
String	更多详情微件的默认标注。	更多详情	Legend
Object []	更多详情指定要在图例中显示的图层的子集。	更多详情	Legend
Boolean	更多详情确定是否遵循地图中控制图例可见性的图层的属性（`minScale`、`maxScale`、`legendEnabled`）。	更多详情	Legend
Object\|String	更多详情指示图例的样式。	更多详情	Legend
MapView\|SceneView	更多详情对 MapView 或 SceneView 的引用。	更多详情	Legend
LegendViewModel	更多详情此微件的视图模型。	更多详情	Legend
Boolean	更多详情指示微件是否可见。	更多详情	Widget

属性详细信息

activeLayerInfos Collection<ActiveLayerInfo>autocast Autocasts from Object []

图例视图用于在图例中显示数据的 ActiveLayerInfo 对象的集合。图例微件监视此属性，以便在从此集合中移除或添加 ActiveLayerInfo 时隐藏或显示图层的图例。

basemapLegendVisible Boolean

指示是否在图例中显示底图图层。如果将此属性设置为 true 并指定 layerInfos，则还必须在 layerInfos 中指定要包含在图例中的底图图层。

默认值：false

示例：

legend.basemapLegendVisible = true;

container String|HTMLElement inherited

表示包含微件的 DOM 元素的 ID 或节点。此属性只能设置一次。以下示例是使用微件时的所有有效用例。

示例：

// Create the HTML div element programmatically at runtime and set to the widget's container
const basemapGallery = new BasemapGallery({
  view: view,
  container: document.createElement("div")
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// Specify an already-defined HTML div element in the widget's container

const basemapGallery = new BasemapGallery({
  view: view,
  container: basemapGalleryDiv
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// HTML markup
<body>
  <div id="viewDiv"></div>
  <div id="basemapGalleryDiv"></div>
</body>

// Specify the widget while adding to the view's UI
const basemapGallery = new BasemapGallery({
  view: view
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

declaredClass Stringreadonly inherited 起始版本：GeoScene API for JavaScript 4.7

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

headingLevel Number 起始版本：GeoScene API for JavaScript 4.20

指示要用于图例标题的标题级别。默认情况下，图例标题渲染为级别 3 标题（例如 <h3>Legend title</h3>）。根据应用中的图例位置，你可能需要调整此标题以获得正确的语义。这对于满足辅助功能标准非常重要。

默认值：3

另请参阅：

Heading Elements

示例：

// legend title will render as an <h2>
legend.headingLevel = 2;

hideLayersNotInCurrentView Boolean 起始版本：GeoScene API for JavaScript 4.21

当 true 时，仅当图层在视图的扩展范围内可见时，这些图层才会显示在图例中。当图层中的数据在视图中不可见时，图层的图例信息将被隐藏。

要从图例中完全隐藏图层，应将图层的 legendEnabled 属性设置为 false。

默认值：false

另请参阅：

respectLayerVisibility

示例：

// layers not displayed in the view
// will not be shown in the legend
legend.hideLayersNotInCurrentView = true;

iconClass String 起始版本：GeoScene API for JavaScript 4.7

微件的默认 CSS 图标类。

id String inherited

创建微件时分配给构件的唯一 ID。如果未由开发人员设置，它将默认为容器 ID，或者如果不存在，则将自动生成。

label String 起始版本：GeoScene API for JavaScript 4.7

微件的默认标注。

layerInfos Object []

指定要在图例中显示的图层的子集。这包括您希望在图例中可见的任何底图图层。如果未设置此属性，则地图中的所有图层都将显示在图例中，包括底图图层（如果 basemapLegendVisible 为 true）。此数组中的对象是使用下面列出的属性定义的。

属性：

title String

optional

指定图层在其符号和描述上方显示的标题。如果未指定标题，则使用服务名称。

layer Layer

要在图例中显示的图层。

sublayerIds Number []

optional

仅当 layer 是 MapImageLayer 时才适用。要为其显示图例信息的 MapImageLayer 子图层的 ID。自版本 4.23 起。

respectLayerVisibility Boolean 起始版本：GeoScene API for JavaScript 4.13

确定是否遵循地图中控制图例可见性的图层的属性（minScale、maxScale、legendEnabled）。默认情况下，在满足以下条件的情况下，图层的图例元素将不会渲染在图例中：

图层的 legendEnabled 属性设置为 false。
如果视图的比例超出图层的 minScale 和 maxScale 属性定义的可见性范围。

当图例的 respectLayerVisibility 属性设置为 false 时，地图中每个图层的图例元素将始终显示，因此忽略地图中每个图层的 minScale、maxScale 和 legendEnabled 属性。

默认值：true

另请参阅：

hideLayersNotInCurrentView

示例：

// Always displays legend elements for the map's layers
// regardless of their minScale, maxScale, and legendEnabled properties
legend.respectLayerVisibility = false;

style Object|String 起始版本：GeoScene API for JavaScript 4.7

指示图例的样式。样式决定了图例的布局和行为。您可以指定字符串或对象来指示样式。已知字符串值与 type 属性内的表中列出的值相同。

属性：

type String

指定图例的样式。下表列出了两个可能的值：

值	说明
classic	图例具有纵向方向。当图例的内容中包含许多元素时，用户可以垂直滚动。
card	在宽视图中，图例具有横向，允许用户水平滚动以查看所有图例元素。这种样式可以响应式，使其成为移动 Web 应用的理想选择。在较小的视图中，图例会坍塌以占用较少的空间。在卡片样式布局中一次显示一个元素，用户可以水平导航。

可能的值："classic"|"card"

layout String

optional

默认值：stack

指定 card 类型后，可以指定以下布局选项之一。

值	说明
auto	此布局具有响应性，因此在宽视图中，图例具有 `side-by-side` 布局，而在较小的（移动）视图中具有 `stack` 布局。
side-by-side	图例具有横向，允许用户水平滚动以一次查看多个图例卡。
stack	图例卡堆叠在一起，这样可以节省空间，但会限制用户一次只能看到一张卡。

可能的值："auto"|"side-by-side"|"stack"

默认值：classic

示例：

// renders the legend in the card style with a "stack" layout
legend.style = "card";

// renders the legend in the card style with a responsive
// layout that toggles between "stack" and "side-by-side"
legend.style = {
  type: "card",
  layout: "auto"
};

// renders the legend in the classic layout
legend.style = "classic";

view MapView|SceneView

对 MapView 或 SceneView 的引用。设置此选项可将微件链接到特定视图。

viewModel LegendViewModelautocast

此微件的视图模型。这是一个包含控制此微件行为的所有逻辑（属性和方法）的类。请参阅 LegendViewModel 类以访问微件上的所有属性和方法。

visible Boolean inherited

指示微件是否可见。

如果 false，则该微件将不再呈现在 web 文档中。这可能会影响文档中其他元素或微件的布局。例如，如果此微件是与视图 UI 右上角关联的三个微件中的第一个，则当此微件变为不可见时，其他微件将重新定位。有关详细信息，请参阅 "none" 的 CSS 显示值。

默认值：true

示例：

// Hides the widget in the view
widget.visible = false;

方法概述

显示继承的方法

隐藏继承的方法

返回类型	描述	类：
String	更多详情用于为微件的 `class` 属性构建值的实用程序方法。	更多详情	Widget
	更多详情销毁微件实例。	更多详情	Widget
Boolean	更多详情在实例上发出事件。	更多详情	Widget
Boolean	更多详情指示实例上是否存在与提供的事件名称匹配的事件侦听器。	更多详情	Widget
Boolean	更多详情 `isFulfilled()` 可用于验证是否满足类的创建实例（已解决或已拒绝）。	更多详情	Widget
Boolean	更多详情 `isRejected()` 可用于验证创建类的实例是否被拒绝。	更多详情	Widget
Boolean	更多详情 `isResolved()` 可用于验证是否解析了类的创建实例。	更多详情	Widget
Object	更多详情在实例上注册事件处理程序。	更多详情	Widget
	更多详情微件拆解助手。	更多详情	Widget
	更多详情此方法主要由开发人员在实现自定义微件时使用。	更多详情	Widget
Object	更多详情此方法主要由开发人员在实现自定义微件时使用。	更多详情	Widget
	更多详情立即将微件渲染给 DOM。	更多详情	Widget
	更多详情此方法主要由开发人员在实现自定义微件时使用。	更多详情	Widget
Promise	更多详情 `when()` 可以在创建类的实例后利用。	更多详情	Widget

方法详细信息

classes(classNames){String}inherited 起始版本：GeoScene API for JavaScript 4.7

用于为微件的 class 属性构建值的实用程序方法。这有助于简化 CSS 类设置。

参数：

classNames String|String []|Object

repeatable

类名称

类型	说明
String	计算的类名。

另请参阅：

指南 - 微件开发（渲染）

示例：

// .tsx syntax showing how to set CSS classes while rendering the widget

render() {
  const dynamicIconClasses = {
    [CSS.myIcon]: this.showIcon,
    [CSS.greyIcon]: !this.showIcon
  };

  return (
    <div class={classes(CSS.root, CSS.mixin, dynamicIconClasses)} />
  );
}

destroy()inherited

销毁微件实例。

emit(type, event){Boolean}inherited 起始版本：GeoScene API for JavaScript 4.5

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

参数：

type String

事件的名称。

event Object

optional

事件负载。

类型	说明
Boolean	`true` 如果听取了侦听者的通知

hasEventListener(type){Boolean}inherited

指示实例上是否存在与提供的事件名称匹配的事件侦听器。

参数：

type String

事件的名称。

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

isFulfilled(){Boolean}inherited 起始版本：GeoScene API for JavaScript 4.19

isFulfilled() 可用于验证是否满足类的创建实例（已解决或已拒绝）。如果已完成，将返回 true。

类型	说明
Boolean	指示是否已完成创建类的实例（已解决或已拒绝）。

isRejected(){Boolean}inherited 起始版本：GeoScene API for JavaScript 4.19

isRejected() 可用于验证创建类的实例是否被拒绝。如果被拒绝，将返回 true。

类型	说明
Boolean	指示创建类的实例是否已被拒绝。

isResolved(){Boolean}inherited 起始版本：GeoScene API for JavaScript 4.19

isResolved() 可用于验证是否解析了类的创建实例。如果被解析，将返回 true。

类型	说明
Boolean	指示是否已解析创建类的实例。

on(type, listener){Object}inherited

在实例上注册事件处理程序。调用此方法将事件与侦听器挂钩。

参数：

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

own(handles)inherited

微件拆解助手。当微件被销毁时，添加到其中的任何句柄都将自动删除。

参数：

handles WatchHandle|WatchHandle []

在微件被销毁后标记为删除的句柄。

postInitialize()inherited

此方法主要由开发人员在实现自定义微件时使用。在微件准备好进行渲染后执行。

render(){Object}inherited

此方法主要由开发人员在实现自定义微件时使用。它必须由子类实现以进行渲染。

类型	说明
Object	渲染的虚拟节点。

renderNow()inherited

立即将微件渲染给 DOM。

scheduleRender()inherited

此方法主要由开发人员在实现自定义微件时使用。计划微件渲染。此方法对于影响 UI 的更改很有用。

when(callback, errback){Promise}inherited 起始版本：GeoScene API for JavaScript 4.19

when() 可以在创建类的实例后利用。此方法采用两个输入参数：callback 函数和 errback 函数。在类的实例加载时执行 callback。如果类的实例无法加载，则执行 errback。

参数：

callback Function

optional

解析 promise 时要调用的函数。

errback Function

optional

promise 失败时要执行的函数。

类型	说明
Promise	返回回调结果的新 promise，`callback` 结果可用于链接其他函数。

示例：

// Although this example uses the BasemapGallery widget, any class instance that is a promise may use when() in the same way
let bmGallery = new BasemapGallery();
bmGallery.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});

GeoScene API for JavaScript参考手册

Unique values

Continuous color

Classed color

Continuous size

Size - above and below

Dot density

Predominance

Relationship

构造函数

属性概述

属性详细信息

方法概述

方法详细信息