require(["esri/symbols/support/symbolUtils"], (symbolUtils) => { /* code goes here */ });
import * as symbolUtils from "@arcgis/core/symbols/support/symbolUtils.js";
esri/symbols/support/symbolUtils
Utilities for generating small preview images of symbols.
Method Overview
Name | Return Type | Summary | Object |
---|---|---|---|
Returns a color representing the input graphic's symbol. | symbolUtils | ||
Returns a symbol representing the input Graphic. | symbolUtils | ||
Returns a label corresponding to the symbol of the input Graphic as displayed in the Legend. | symbolUtils | ||
Generates a preview image of a color ramp to display in a DOM element. | symbolUtils | ||
Generates an HTML element representing the legend of a PieChartRenderer. | symbolUtils | ||
Generates a preview image of a given symbol that can be displayed in a DOM element. | symbolUtils | ||
Generates an HTML element representing the square or diamond legend element of a relationship renderer. | symbolUtils |
Method Details
-
Since: ArcGIS Maps SDK for JavaScript 4.19symbolUtils since 4.11, getDisplayedColor added at 4.19. -
Returns a color representing the input graphic's symbol. This method is useful when you need to know the exact color of a Graphic's symbol, particularly when the graphic comes from the result of a hitTest() and its symbol properties may be empty. A symbol's properties won't be populated when a Renderer defines the visualization of a layer rather than symbols set individually on each graphic of a layer. This is the case for FeatureLayer, and any other layer that has a
renderer
property.ParametersSpecificationgraphic GraphicThe graphic from which to retrieve the displayed color. This commonly comes from a hitTest() or layer view query operation.
options ObjectoptionalOptions for generating the display color of the input graphic. These must be specified if the input graphic comes from a layer with a renderer that has visual variables applied. See the object specification below.
Specificationscale NumberoptionalThe view scale at which the graphic is displayed.
viewingMode StringoptionalThe viewingMode of the view, if the graphic is displayed in a SceneView.
spatialReference SpatialReferenceoptionalThe spatial reference of the view in which the graphic is displayed.
renderer RendereroptionalThe renderer of the layer associated with the
graphic
.resolution NumberoptionalThe resolution of the view at which the graphic is displayed.
ReturnsExampleview.on("click", async (event) => { const { results } = await view.hitTest(event, { include: layer }); const graphic = results[0].graphic; // do something with the result color const color = await symbolUtils.getDisplayedColor(graphic); });
-
Returns a symbol representing the input Graphic. This method is useful when you need to know the exact visual properties of a Graphic's symbol, particularly when the graphic comes from the result of a hitTest() and its symbol properties may be empty. A symbol's properties won't be populated when a Renderer defines the visualization of a layer rather than symbols set individually on each graphic of a layer. This is the case for FeatureLayer, and any other layer that has a
renderer
property.ParametersSpecificationgraphic GraphicThe graphic from which to retrieve the displayed symbol. This commonly comes from a hitTest() operation.
options ObjectoptionalOptions for generating the display symbol of the input graphic. These must be specified if the input graphic comes from a layer with a renderer that has visual variables applied. See the object specification below.
Specificationscale NumberoptionalThe view scale at which the symbol is displayed.
viewingMode StringoptionalThe viewingMode of the view, if the symbol is displayed in a SceneView.
spatialReference SpatialReferenceoptionalThe spatial reference of the view in which the symbol is displayed.
renderer RendereroptionalThe renderer of the layer associated with the
graphic
.resolution NumberoptionalThe resolution of the view at which the symbol is displayed.
ReturnsExampleview.on("click", async (event) => { const { results } = await view.hitTest(event, { include: layer }); const graphic = results[0].graphic; // do something with the result symbol const symbol = await symbolUtils.getDisplayedSymbol(graphic, { scale: view.scale, spatialReference: view.spatialReference, resolution: view.resolution }); });
-
Since: ArcGIS Maps SDK for JavaScript 4.29symbolUtils since 4.11, getLegendLabel added at 4.29. -
ParametersSpecificationgraphic Graphic
The graphic from which to retrieve its associated label as displayed in the legend widget. This commonly comes from a hitTest() operation.
optional The graphic from which to retrieve the displayed symbol. This commonly comes from a hitTest() operation.
options ObjectoptionalOptions for generating the legend label of the input graphic. These must be specified if the input graphic comes from a layer with a renderer that has visual variables applied. See the object specification below.
Specificationscale NumberoptionalThe view scale at which the symbol is displayed.
viewingMode StringoptionalThe viewingMode of the view, if the symbol is displayed in a SceneView.
spatialReference SpatialReferenceoptionalThe spatial reference of the view in which the symbol is displayed.
renderer RendereroptionalThe renderer of the layer associated with the
graphic
.resolution NumberoptionalThe resolution of the view at which the symbol is displayed.
ReturnsExampleview.on("click", async (event) => { const { results } = await view.hitTest(event, { include: layer }); const graphic = results[0].graphic; // do something with the result symbol const label = await symbolUtils.getLegendLabel(graphic, view, { scale: view.scale, spatialReference: view.spatialReference, resolution: view.resolution }); });
-
renderColorRampPreviewHTML
renderColorRampPreviewHTML(colors, options){HTMLElement}
Since: ArcGIS Maps SDK for JavaScript 4.13symbolUtils since 4.11, renderColorRampPreviewHTML added at 4.13. -
Generates a preview image of a color ramp to display in a DOM element.
ParametersSpecificationAn array of colors from which to construct the color ramp.
options ObjectoptionalFormatting options for the color ramp.
Specificationalign StringoptionalDefault Value: verticalSpecifies the alignment of the color ramp.
Possible Values:"horizontal"|"vertical"
gradient BooleanoptionalDefault Value: trueIndicates whether to render the color ramp with a continuous gradient. When
false
, distinct colors will appear in the ramp without a gradient.width NumberoptionalThe width of the ramp in pixels.
height NumberoptionalThe height of the ramp in pixels.
ReturnsType Description HTMLElement Returns a preview of the color ramp for display in the DOM. Examplesconst colors = [ "#d6ffe1", "#8ceda6", "#2ee860", "#00e33d" ]; const colorRamp = symbolUtils.renderColorRampPreviewHTML(colors, { align: "vertical" }); body.appendChild(colorRamp);
// Primary color scheme from colorSchemes.getSchemes() const schemes = colorSchemes.getSchemes({ basemap: "gray-vector", geometryType: "polygon", theme: "above-and-below" }); const colorRamp = symbolUtils.renderColorRampPreviewHTML(schemes.primaryScheme.colors, { align: "horizontal" }); body.appendChild(colorRamp);
-
renderPieChartPreviewHTML
renderPieChartPreviewHTML(colors, options){HTMLElement}
Since: ArcGIS Maps SDK for JavaScript 4.26symbolUtils since 4.11, renderPieChartPreviewHTML added at 4.26. -
Generates an HTML element representing the legend of a PieChartRenderer. Use this method to display the pie chart legend element in a DOM element.
ParametersSpecificationA list of colors used to render the pie chart.
options ObjectoptionalOptions for creating the legend element.
Specificationradius NumberoptionalDefault Value: 40The radius of the pie chart in pixels.
holePercentage NumberoptionalDefault Value: 0The hole percentage of the chart on a scale of 0-1. A percentage of
0
creates a pie chart. Any other value creates a donut chart. This value indicates the percentage of the chart to remove from the center.optional The values used to indicate the area each color should represent as a percentage when creating the pie chart. The number of values should match the number of colors. Value positions correspond with the positions of colors in the
colors
array. For example, if the first color in thecolors
array is red and the first value in thevalues
array is 50, then 50% of the chart should be represented with red. The sum of all values defined here must equal 100. By default all colors are given an equal area.outline SimpleLineSymboloptionalThe outline of the pie chart.
ReturnsType Description HTMLElement Returns the of the pie chart legend element to display in the DOM. Exampleconst { attributes, size, holePercentage, outline } = layer.renderer; const colors = attributes.map( attribute => attribute.color ); const element = symbolUtils.renderPieChartPreviewHTML(colors, { radius: size * 0.5, holePercentage, values: [10,70,20], outline }); legendElement.appendChild(element);
-
renderPreviewHTML
renderPreviewHTML(symbol, options){Promise<HTMLElement>}
-
Generates a preview image of a given symbol that can be displayed in a DOM element.
ParametersSpecificationsymbol SymbolThe symbol for which to generate a preview image.
options ObjectoptionalFormatting options for the symbol preview image.
Specificationnode HTMLElementoptionalThe parent node to append to the symbol.
optional Use a number to set the size (in points) of the symbol preview for any symbol representing a point. Starting at version 4.23, you can provide an object with width and height properties when creating symbol previews for simple symbols. At version 4.25, the width and height properties are supported on all symbols.
Specificationwidth NumberoptionalThe width of the symbol preview in points. Previews for SimpleFillSymbol must have
isSquareFill
enabled insymbolConfig
for this property to take effect.height NumberoptionalThe height of the symbol preview in points. Previews for SimpleFillSymbol must have
isSquareFill
enabled insymbolConfig
for this property to take effect.maxSize NumberoptionalThe maximum size of the symbol preview in points.
opacity NumberoptionalThe opacity of the layer represented by the
symbol
. Must be a number between 0 and 1.scale BooleanoptionalDefault Value: trueWhen
true
the size of the symbol preview will include the outline in the measurement of the entire symbol. Whenfalse
, the symbol preview will not include the outline in the size measurement, thus matching the symbol size in the view.disableUpsampling BooleanoptionalIndicates whether to disable upsampling for raster images.
optional Options for setting the shape of a fill symbol preview. This can be a single string value (
tall
is the only option), or an object with config options. See the table below for specifics on the configuration options available.Possible Values:"tall"
rotation NumberoptionalThe rotation of the symbol.
overrideText StringoptionalSince 4.25 The text that will be displayed in the symbol preview of a TextSymbol. This will override any existing text defined on the symbol.
ReturnsType Description Promise<HTMLElement> Returns a preview of the given symbol to display to the DOM. Example// symbol from SimpleRenderer; const symbol = layer.renderer.symbol.clone(); symbolUtils.renderPreviewHTML(symbol, { node: document.getElementById("preview"), size: 8 });
-
renderRelationshipRampPreviewHTML
renderRelationshipRampPreviewHTML(renderer, options){HTMLElement}
Since: ArcGIS Maps SDK for JavaScript 4.26symbolUtils since 4.11, renderRelationshipRampPreviewHTML added at 4.26. -
Generates an HTML element representing the square or diamond legend element of a relationship renderer. Use this method to display the relationship legend element in a DOM element.
ParametersSpecificationrenderer UniqueValueRendererA relationship renderer instance.
options ObjectoptionalOptions for creating the legend element.
Specificationnode HTMLElementoptionalThe container node in which to place the generated relationship element.
opacity NumberoptionalDefault Value: 1The opacity of the legend element.
ReturnsType Description HTMLElement Returns the relationship legend element to display in the DOM. Exampleconst relationshipElement = symbolUtils.renderRelationshipRampPreviewHTML(layer.renderer); body.appendChild(relationshipElement);