Legend

字数统计: 7k 字

阅读时长: 约 20 分钟

当前版本: 4.29

AMD： require(["geoscene/widgets/Legend"], (Legend) => { /* code goes here */ });

ESM： import Legend from "@geoscene/core/widgets/Legend.js";

类： geoscene/widgets/Legend

继承于：Legend ->Widget->Accessor

起始版本：GeoScene Maps SDK for JavaScript 4.0

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

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

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

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

已知限制

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

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

唯一值

连续颜色

分类颜色

连续大小

大小 - 之上和之下

点密度

众数渲染

关系

有关获得对微件样式完全控制的信息，请参阅样式主题。

另请参阅

示例

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

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

构造函数

Legend

new Legend(properties?)

参数

propertiesObject

optional

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

示例

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

属性概述

所有属性都可以设置、获取和监听。请参阅使用属性主题。

名称	类型	描述	类
activeLayerInfos	Collection<ActiveLayerInfo>	图例视图用于在图例中显示数据的 ActiveLayerInfo 对象的集合。	图例
basemapLegendVisible	Boolean	指示是否在 Legend 中显示底图图层。	图例
container	String\|HTMLElement	包含微件的 DOM 元素的 ID 或节点。	Widget
declaredClass	String	类的名称。	Accessor
headingLevel	Number	指示用于图例标题的标题级别。	图例
hideLayersNotInCurrentView	Boolean	当为 true 时，仅当图层在视图范围内可见，这些图层才会显示在图例中。	Legend
icon	String	表示微件的图标。	Legend
iconClass	String	微件的默认 CSS 图标类。	Legend
id	String	创建微件时分配给微件的唯一 ID。	Widget
label	String	微件的默认的标注。	Legend
layerInfos	Object []	指定要在图例中显示的图层的子集。	Legend
respectLayerVisibility	Boolean	确定是否遵循地图中控制图例可见性的图层属性 (minScale、maxScale、legendEnabled)。	Legend
style	Object\|String	指示图例的样式。	Legend
view	MapView\|SceneView	对 MapView 或 SceneView 的引用。	Legend
viewModel	LegendViewModel	此微件的视图模型。	Legend
visible	Boolean	指示微件是否可见。	Widget

属性详细信息

activeLayerInfos

activeLayerInfos Collection<ActiveLayerInfo>autocast

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

basemapLegendVisible

basemapLegendVisible Boolean

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

默认值false

示例

legend.basemapLegendVisible = true;

container

container String|HTMLElement

继承自：Widget

包含微件的 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"
});

html

// 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

declaredClass Stringreadonly

继承自：Accessor

起始版本：GeoScene Maps SDK for JavaScript 4.7

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

headingLevel

headingLevel Number

起始版本：GeoScene Maps SDK for JavaScript 4.20

指示用于图例标题的标题级别。默认情况下，图例标题呈现为 3 级标题 (例如，<h3>Legend title</h3>)。根据图例在应用程序中的位置，您可能需要调整此标题以获得正确的语义。这对于满足可访问性标准很重要。

默认值3

另请参阅

标题元素

示例

html

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

hideLayersNotInCurrentView

hideLayersNotInCurrentView Boolean

起始版本：GeoScene Maps SDK 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;

icon

icon String

起始版本：GeoScene Maps SDK for JavaScript 4.27

表示微件的图标。它通常在微件由另一微件控制时使用 (例如在 Expand 微件中)。

默认值null

iconClass

iconClass String

起始版本：GeoScene Maps SDK for JavaScript 4.7

微件的默认 CSS 图标类。

id

id String

继承自：Widget

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

label

label String

起始版本：GeoScene Maps SDK for JavaScript 4.7

微件的默认的标注。

layerInfos

layerInfos Object []

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

属性

titleString

optional

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

layerLayer

要在图例中显示的图层。

sublayerIdsNumber []

optional

仅当 layer 为 MapImageLayer、SubtypeGroupLayer 或 WMSLayer 时才适用。要为其显示图例信息的子图层的 ID。从 4.23 版开始。

示例

const subtypeGroupLayer = webmap.layers.getItemAt(0);
const subtypeSubLayer = subtypeGroupLayer.sublayers.getItemAt(1);
const subtypeSublayerId = parseInt(subtypeSubLayer.subtypeCode);
const legend = new Legend({
  view: view,
  layerInfos: [
    {
      layer: subtypeGroupLayer,
      sublayerIds: [subtypeSublayerId]
    }
  ]
});

respectLayerVisibility

respectLayerVisibility Boolean

起始版本：GeoScene Maps SDK 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

style Object|String

起始版本：GeoScene Maps SDK for JavaScript 4.7

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

默认值classic

属性

typeString

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

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

可能值："classic"|"card"

layoutString

optional

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

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

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

默认值：stack

示例

// 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

view MapView|SceneView

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

viewModel

viewModel LegendViewModelautocast

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

visible

visible Boolean

继承自：Widget

指示微件是否可见。

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

默认值true

示例

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

方法概述

名称	返回值类值	描述	类
addHandles()		添加一个或多个与对象的生命周期相关联的句柄。	Accessor
classes()	String	用于为微件的 class 属性构建值的实用方法。	Widget
destroy()		销毁微件实例。	Widget
emit()	Boolean	在实例上触发事件。	Widget
hasEventListener()	Boolean	指示实例上是否存在与提供的事件名称相匹配的事件监听器。	Widget
hasHandles()	Boolean	如果存在指定的句柄组，则返回 true。	Accessor
isFulfilled()	Boolean	isFulfilled() 可用于验证创建类的实例是否已完成 (已解决或已拒绝)。	Widget
isRejected()	Boolean	isRejected() 可用于验证创建类的实例是否被拒绝。	Widget
isResolved()	Boolean	isResolved() 可用于验证创建类的实例是否已解决。	Widget
on()	Object	在实例上注册事件处理程序。	Widget
own()		添加一个或多个与微件的生命周期相关联的句柄。	Widget
postInitialize()		此方法主要由开发人员在实现自定义微件时使用。	Widget
removeHandles()		移除对象拥有的句柄组。	Accessor
render()	Object	此方法主要由开发人员在实现自定义微件时使用。	Widget
renderNow()		立即将微件渲染到 DOM。	Widget
scheduleRender()		此方法主要由开发人员在实现自定义微件时使用。	Widget
when()	Promise	when() 一旦创建了类的实例，就可以利用。	Widget

方法详细说明

addHandles

addHandles(handleOrHandles, groupKey?)

继承自：Accessor

起始版本：GeoScene Maps SDK for JavaScript 4.25

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

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

this.addHandles(handle);

// Destroy the object
this.destroy();

参数

handleOrHandlesWatchHandle|WatchHandle []

对象销毁后，标记为要移除的句柄。

groupKey*

optional

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

classes

classes(){String}

继承自：Widget

起始版本：GeoScene Maps SDK for JavaScript 4.7

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

参数

classNamesString|String []|Object

类名称。

类型	描述
String	计算的类名。

另请参阅

指南 - 自定义微件基础知识 (渲染器)

示例

html

// .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

destroy()

继承自：Widget

销毁微件实例。

emit

emit(type, event?){Boolean}

继承自：Widget

起始版本：GeoScene Maps SDK for JavaScript 4.5

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

参数

typeString

事件的名称。

eventObject

optional

事件有效负载。

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

hasEventListener

hasEventListener(type){Boolean}

继承自：Widget

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

参数

typeString

事件的名称。

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

hasHandles

hasHandles(groupKey?){Boolean}

继承自：Accessor

起始版本：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");
}

isFulfilled

isFulfilled(){Boolean}

继承自：Widget

起始版本：GeoScene Maps SDK for JavaScript 4.19

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

类型	描述
Boolean	指示创建类的实例是否已完成 (已解决或已拒绝)。

isRejected

isRejected(){Boolean}

继承自：Widget

起始版本：GeoScene Maps SDK for JavaScript 4.19

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

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

isResolved

isResolved(){Boolean}

继承自：Widget

起始版本：GeoScene Maps SDK for JavaScript 4.19

isResolved() 可用于验证创建类的实例是否已解决。如果已解决，则返回 true。

类型	描述
Boolean	指示创建类的实例是否已解决。

on

on(type, listener){Object}

继承自：Widget

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

参数

typeString|String []

要监听的事件或事件数组。

listenerFunction

事件触发时要调用的函数。

类型描述

Object

返回一个具有 remove() 方法的事件处理程序，应该调用该方法以停止监听事件。

属性	类型	描述
remove	Function	当调用时，将从事件中移除该监听器。

示例

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

own

own(handleOrHandles)

继承自：Widget

起始版本：GeoScene Maps SDK for JavaScript 4.24

已弃用自 4.28 开始，改为使用 addHandles()。

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

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

this.own(handle); // Handle gets removed when the widget is destroyed.

参数

handleOrHandlesWatchHandle|WatchHandle []

微件销毁后，标记为要移除的句柄。

postInitialize

postInitialize()

继承自：Widget

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

removeHandles

removeHandles(groupKey?)

继承自：Accessor

起始版本：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");

render

render(){Object}

继承自：Widget

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

类型	描述
Object	渲染的虚拟节点。

renderNow

renderNow()

继承自：Widget

立即将微件渲染到 DOM。

scheduleRender

scheduleRender()

继承自：Widget

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

when

when(callback?, errback?){Promise}

继承自：Widget

起始版本：GeoScene Maps SDK for JavaScript 4.19

when() 一旦创建了类的实例，就可以利用。此方法接受两个输入参数：callback 函数和 errback 函数。callback 在类的实例加载时执行。errback 在类的实例无法加载时执行。

参数

callbackFunction

optional

当 promise 解决时调用的函数。

errbackFunction

optional

当 promise 失败时执行的函数。

类型	描述
Promise	为 `callback` 结果返回一个新的 promise。

示例

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

Legend

唯一值 ​

连续颜色 ​

分类颜色 ​

连续大小 ​

大小 - 之上和之下 ​

点密度 ​

众数渲染 ​

关系 ​

构造函数 ​

Legend ​

propertiesObject

属性概述 ​

属性详细信息 ​

activeLayerInfos ​

basemapLegendVisible ​

container ​

declaredClass ​

headingLevel ​

hideLayersNotInCurrentView ​

icon ​

iconClass ​

id ​

label ​

layerInfos ​

titleString

layerLayer

sublayerIdsNumber[]

respectLayerVisibility ​

style ​

typeString

layoutString

view ​

viewModel ​

visible ​

方法概述 ​

方法详细说明 ​

addHandles ​

handleOrHandlesWatchHandle|WatchHandle[]

groupKey*

classes ​

classNamesString|String[]|Object

destroy ​

emit ​

typeString

eventObject

hasEventListener ​

typeString

hasHandles ​

groupKey*

isFulfilled ​

isRejected ​

isResolved ​

on ​

typeString|String[]

唯一值

连续颜色

分类颜色

连续大小

大小 - 之上和之下

点密度

众数渲染

关系

构造函数

Legend

属性概述

属性详细信息

activeLayerInfos

basemapLegendVisible

container

declaredClass

headingLevel

hideLayersNotInCurrentView

icon

iconClass

id

label

layerInfos

sublayerIdsNumber []

respectLayerVisibility

style

view

viewModel

visible

方法概述

方法详细说明

addHandles

handleOrHandlesWatchHandle|WatchHandle []

classes

classNamesString|String []|Object

destroy

emit

hasEventListener

hasHandles

isFulfilled

isRejected

isResolved

on

typeString|String []