@arcgis/map-components
Version:
ArcGIS Map Components
456 lines (455 loc) • 23.4 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type ActiveLayerInfo from "@arcgis/core/widgets/Legend/support/ActiveLayerInfo.js";
import type Collection from "@arcgis/core/core/Collection.js";
import type LinkChartView from "@arcgis/core/views/LinkChartView.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, HeadingLevel } from "../types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { MapViewOrSceneView } from "@arcgis/core/views/MapViewOrSceneView.js";
import type { LayerInfo } from "@arcgis/core/widgets/types.js";
import type { LegendViewModelState } from "@arcgis/core/widgets/Legend/LegendViewModel.js";
/**
* The Legend component displays the symbols and labels used to represent layers in an [arcgis-map](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/) or [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/).
* Only layers and sublayers visible in the view are shown, unless [ignoreLayerVisibility](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/#ignoreLayerVisibility) is set to `true`.
*
* The legend automatically updates when:
* - the visibility of a layer or sublayer changes
* - a layer is added or removed from the map
* - a layer's `renderer`, `opacity`, or `title` is changed
* - the `legendEnabled` property is changed (set to `true` or `false` on the layer)
*
* ## Known Limitations
*
* * Currently, the legend component does not support the following layer types:
* [ElevationLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/ElevationLayer/),
* [GraphicsLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/GraphicsLayer/),
* [IntegratedMeshLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/IntegratedMeshLayer/),
* [KMLLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/KMLLayer/),
* [MapNotesLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/MapNotesLayer/),
* [OpenStreetMapLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/OpenStreetMapLayer/),
* [VectorTileLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/VectorTileLayer/),
* [VideoLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/VideoLayer/), and
* [WebTileLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/WebTileLayer/).
* * [Symbol3D](https://developers.arcgis.com/javascript/latest/references/core/symbols/Symbol3D/) with more than one
* [symbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/Symbol3DLayer/) are not supported.
* * [DictionaryRenderer](https://developers.arcgis.com/javascript/latest/references/core/renderers/DictionaryRenderer/) is not supported.
* * [TrackInfo](https://developers.arcgis.com/javascript/latest/references/core/layers/support/TrackInfo/) is not supported.
* * CIM Symbol [primitiveOverride](https://developers.arcgis.com/javascript/latest/references/core/symbols/CIMSymbol/#PrimitiveOverride) is not supported.
* * RasterStretchRenderer [dynamicRangeAdjustment](https://developers.arcgis.com/javascript/latest/references/core/renderers/RasterStretchRenderer/#dynamicRangeAdjustment) is not supported.
*
* ## Various examples of legends based on renderer type.
*
* ### Unique values
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/visualization-location-types/)
*
* ### Continuous color
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/visualization-vv-color/)
*
* ### Classed color
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/visualization-classbreaks/)
*
* ### Continuous size
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/visualization-sm-size/)
*
* ### Size - above and below
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/visualization-sm-size-themes/)
*
* ### Dot density
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/visualization-dot-density/)
*
* ### Predominance
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/visualization-arcade/)
*
* ### Relationship
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/visualization-sm-relationship/)
*
*
* ## Legend labels
*
* Legend text is directly controlled through the [layer](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/) and [renderer](https://developers.arcgis.com/javascript/latest/references/core/renderers/Renderer/) properties. For example, `layer.title` is directly used by the legend to present a layer's symbology to the end user. To override this text, you can directly update `layer.title`.
*
* Furthermore, you can control date and number formatting in Legend by using the [FieldConfiguration](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FieldConfiguration/) formatting options on the layer. As an alternative to this, you can override Legend text via the renderer's properties. For example, the renderer may have a [legendOptions](https://developers.arcgis.com/javascript/latest/references/core/renderers/ClassBreaksRenderer/#legendOptions) property (or a label property in the case of visual variable stops or UniqueValueInfos) that can be used to override default legend text describing the renderer element in question. The [Update legend text sample](https://developers.arcgis.com/javascript/latest/sample-code/legend-update/) provides an example of overriding legend text via the renderer.
*
* Note that when you override legend text, all formatting and localization that would otherwise be dynamically applied to labels will no longer apply.
*
* @see [Sample - Legend component](https://developers.arcgis.com/javascript/latest/sample-code/legend/)
* @see [Sample - Add a Legend to the LayerList](https://developers.arcgis.com/javascript/latest/sample-code/layerlist-legend/)
* @see [Sample - Legend component card style](https://developers.arcgis.com/javascript/latest/sample-code/legend-card/)
* @see [Sample - Update legend text](https://developers.arcgis.com/javascript/latest/sample-code/legend-update/)
* @since 4.28
*/
export abstract class ArcgisLegend extends LitElement {
/**
* Collection of [ActiveLayerInfo](https://developers.arcgis.com/javascript/latest/references/core/widgets/Legend/support/ActiveLayerInfo/) objects used by the legend view to
* display data in the legend. The legend component watches this property to hide or display the layer's legend when
* an [ActiveLayerInfo](https://developers.arcgis.com/javascript/latest/references/core/widgets/Legend/support/ActiveLayerInfo/) is removed from or added to this collection.
*/
accessor activeLayerInfos: Collection<ActiveLayerInfo>;
/**
* If true, the component will not be destroyed automatically when it is
* disconnected from the document. This is useful when you want to move the
* component to a different place on the page, or temporarily hide it. If this
* is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/**
* Indicates whether to show the [Basemap](https://developers.arcgis.com/javascript/latest/references/core/Basemap/) layers in the Legend. If you set this property to
* `true` and specify [layerInfos](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/#layerInfos) that include the basemap layers, the basemap will be displayed in the legend.
*
* > **Known limitation:**
* >
* > [VectorTileLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/VectorTileLayer/) in the basemap are not currently supported in the legend.
* > This includes most Esri basemaps such as "Streets", "Topographic", "Navigation", and others that use vector tiles.
*
* @default false
* @example
* Show basemap layers in the legend
*
* ```js
* const mapElement = document.querySelector("arcgis-map");
* const basemapLayer = mapElement.map.basemap.baseLayers.getItemAt(0);
* const legend = document.querySelector("arcgis-legend");
* legend.layerInfos = [{ layer: basemapLayer }];
* legend.basemapLegendVisible = true;
* ```
*/
accessor basemapLegendVisible: boolean;
/**
* Indicates the layout of the legend when the [legendStyle](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/#legendStyle) is set to the string value of `"card"`.
* The layout determines how the legend's content is arranged.
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/legend-card/)
*
* @since 4.34
* @example
* Renders the legend in the card style with a "stack" layout
*
* ```html
* <arcgis-legend legend-style="card" card-style-layout="stack"></arcgis-legend>
* ```
*
* ```js
* const legend = document.querySelector("arcgis-legend");
* legend.legendStyle = "card";
* legend.cardStyleLayout = "stack";
* ```
*/
accessor cardStyleLayout: "auto" | "side-by-side" | "stack" | undefined;
/**
* Indicates the heading level to use for the legend title. By default, legend titles are rendered as level 3 headings (e.g. `<h3>Legend title</h3>`). Depending on the legend placement
* in your app, you may need to adjust this heading for proper semantics. This is important for meeting accessibility standards.
*
* @default 3
* @see [Heading Elements](https://developer.mozilla.org/docs/Web/HTML/Element/Heading_Elements)
* @example
* Legend title will render as an `<h2>`
*
* ```html
* <arcgis-legend heading-level="2"></arcgis-legend>
* ```
*
* ```js
* document.querySelector("arcgis-legend").headingLevel = 2;
* ```
*/
accessor headingLevel: HeadingLevel;
/**
* When `true`, layers will only be shown in the legend if they are visible in the view's extent. When data from a layer
* is not visible in the view, the layer's legend information will be hidden. Only layers that implement the `createQuery()`
* and `queryFeatureCount()` methods are supported by `hideLayersNotInCurrentView`.
*
* To hide layers completely from the legend, you should set the `legendEnabled` property of the layer to `false`.
*
* @default false
* @see [ignoreLayerVisibility](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/#ignoreLayerVisibility)
* @example
* Layers not displayed in the current map extent will not be shown in the legend
*
* ```html
* <arcgis-legend hide-layers-not-in-current-view></arcgis-legend>
* ```
*
* ```js
* document.querySelector("arcgis-legend").hideLayersNotInCurrentView = true;
* ```
* @since 4.21
*/
accessor hideLayersNotInCurrentView: boolean;
/**
* Icon which represents the component.
* Typically used when the component is controlled by another component (e.g. by the Expand component).
*
* @default "legend"
* @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
*/
accessor icon: string | undefined;
/**
* Determines whether to respect the properties of the layers in the map that control the legend's visibility (`minScale`, `maxScale`, `legendEnabled`).
* By default, a layer's legend elements **will not render** in the legend given the following conditions:
*
* - The layer's [legendEnabled](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#legendEnabled) property
* is set to `false`.
* - If the view's scale is outside the visibility range
* defined by the layer's [minScale](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#minScale) and
* [maxScale](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#maxScale) properties.
*
* When the `ignoreLayerVisibility` property of the legend is set to `true`, the legend elements for each
* layer in the map will always display, thus disregarding the `minScale`, `maxScale`,
* and `legendEnabled` properties for each layer in the map.
*
* @default false
* @since 4.34
* @see [hideLayersNotInCurrentView](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/#hideLayersNotInCurrentView)
* @example
* Always displays legend elements for the map's layers regardless of their minScale, maxScale, and legendEnabled properties.
*
* ```html
* <arcgis-legend ignore-layer-visibility></arcgis-legend>
* ```
*
* ```js
* document.querySelector("arcgis-legend").ignoreLayerVisibility = true;
* ```
*/
accessor ignoreLayerVisibility: boolean;
/**
* The component's default label.
*
* @default "Legend"
*/
accessor label: string | undefined;
/**
* Specifies a subset of the layers to display in the legend. This includes any basemap layers
* you want to be visible in the legend. If this property is not set, all layers in the map will display in the legend, including
* basemap layers if [basemapLegendVisible](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/#basemapLegendVisible) is `true`. Objects in this array are defined with the properties in the example below.
*
* @example
* Only show a specific sublayer in the legend
*
* ```js
* const subtypeGroupLayer = webmap.layers.getItemAt(0);
* const subtypeSubLayer = subtypeGroupLayer.sublayers.getItemAt(1);
* const subtypeSublayerId = parseInt(subtypeSubLayer.subtypeCode);
* document.querySelector("arcgis-legend").layerInfos = [
* {
* layer: subtypeGroupLayer,
* sublayerIds: [subtypeSublayerId]
* }
* ];
* });
* ```
*/
accessor layerInfos: Array<LayerInfo>;
/**
* Indicates the style of the legend. The style determines the legend's layout and behavior.
* You can either specify a string or an object to indicate the style. The known string values are the same values listed in
* the table within the `type` property.
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/legend-card/)
*
* @default "classic"
* @see [cardStyleLayout](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/#cardStyleLayout)
* @example
* Renders the legend in the card style with a stack layout
*
* ```js
* document.querySelector("arcgis-legend").legendStyle = {
* type: "card",
* layout: "stack"
* };
* ```
*/
accessor legendStyle: "card" | "classic" | {
type: "card" | "classic";
layout?: "auto" | "side-by-side" | "stack";
};
/**
* Indicates whether the legend is currently loading.
*
* @default false
* @since 4.34
*/
get loading(): boolean;
/**
* Replace localized message strings with your own strings.
*
* _**Note**: Individual message keys may change between releases._
*
* @since 4.34
*/
accessor messageOverrides: {
componentLabel?: string | undefined;
points?: string | undefined;
lines?: string | undefined;
polygons?: string | undefined;
creatingLegend?: string | undefined;
noLegend?: string | undefined;
dotValue?: string | undefined;
currentObservations?: string | undefined;
previousObservations?: string | undefined;
high?: string | undefined;
low?: string | undefined;
esriMetersPerSecond?: string | undefined;
esriKilometersPerHour?: string | undefined;
esriKnots?: string | undefined;
esriFeetPerSecond?: string | undefined;
esriMilesPerHour?: string | undefined;
showNormField?: string | undefined;
showNormPct?: string | undefined;
showRatio?: string | undefined;
showRatioPercent?: string | undefined;
showRatioPercentTotal?: string | undefined;
band0?: string | undefined;
band1?: string | undefined;
band2?: string | undefined;
band3?: string | undefined;
red?: string | undefined;
green?: string | undefined;
blue?: string | undefined;
clusterCountTitle?: string | undefined;
previewAriaLabel?: string | undefined;
previewTemplateAriaLabel?: string | undefined;
previewColorRampAriaLabel?: string | undefined;
previewOpacityRampAriaLabel?: string | undefined;
previewPieChartAriaLabel?: string | undefined;
previewRelationshipRampAriaLabel?: string | undefined;
carousel?: string | undefined;
pagination?: { pageText?: string | undefined; } | undefined;
};
/** @internal */
protected messages: Partial<{
componentLabel: string;
points: string;
lines: string;
polygons: string;
creatingLegend: string;
noLegend: string;
dotValue: string;
currentObservations: string;
previousObservations: string;
high: string;
low: string;
esriMetersPerSecond: string;
esriKilometersPerHour: string;
esriKnots: string;
esriFeetPerSecond: string;
esriMilesPerHour: string;
showNormField: string;
showNormPct: string;
showRatio: string;
showRatioPercent: string;
showRatioPercentTotal: string;
band0: string;
band1: string;
band2: string;
band3: string;
red: string;
green: string;
blue: string;
clusterCountTitle: string;
previewAriaLabel: string;
previewTemplateAriaLabel: string;
previewColorRampAriaLabel: string;
previewOpacityRampAriaLabel: string;
previewPieChartAriaLabel: string;
previewRelationshipRampAriaLabel: string;
carousel: string;
pagination: { pageText: string; };
}> & T9nMeta<{
componentLabel: string;
points: string;
lines: string;
polygons: string;
creatingLegend: string;
noLegend: string;
dotValue: string;
currentObservations: string;
previousObservations: string;
high: string;
low: string;
esriMetersPerSecond: string;
esriKilometersPerHour: string;
esriKnots: string;
esriFeetPerSecond: string;
esriMilesPerHour: string;
showNormField: string;
showNormPct: string;
showRatio: string;
showRatioPercent: string;
showRatioPercentTotal: string;
band0: string;
band1: string;
band2: string;
band3: string;
red: string;
green: string;
blue: string;
clusterCountTitle: string;
previewAriaLabel: string;
previewTemplateAriaLabel: string;
previewColorRampAriaLabel: string;
previewOpacityRampAriaLabel: string;
previewPieChartAriaLabel: string;
previewRelationshipRampAriaLabel: string;
carousel: string;
pagination: { pageText: string; };
}>;
/**
* By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
*
* @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
*/
accessor referenceElement: ArcgisReferenceElement | string | undefined;
/**
* If a layer uses a unique value render, only features that satisfy the layer's
* [definition](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#definitionExpression)
* will be displayed in the legend when set to true.
*
* @default false
* @since 4.30
* @see [definitionExpression](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#definitionExpression)
* @example
* Only display features that satisfy the layer's definitionExpression.
*
* ```html
* <arcgis-legend respect-layer-definition-expression></arcgis-legend>
* ```
*
* ```js
* document.querySelector("arcgis-legend").respectLayerDefinitionExpression = true;
* ```
*/
accessor respectLayerDefinitionExpression: boolean;
/**
* The current state of the component.
*
* @default "disabled"
*/
get state(): LegendViewModelState;
/**
* The view associated with the component.
* > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-legend component will be associated with a map or scene component rather than using the `view` property.
*/
accessor view: LinkChartView | MapViewOrSceneView | null | undefined;
/** Permanently destroy the component. */
destroy(): Promise<void>;
/** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "state"; }>;
/** Emitted when the component associated with a map or scene view is ready to be interacted with. */
readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
readonly "@eventTypes": {
arcgisPropertyChange: ArcgisLegend["arcgisPropertyChange"]["detail"];
arcgisReady: ArcgisLegend["arcgisReady"]["detail"];
};
}