▾
import "@arcgis/map-components/components/arcgis-utility-network-trace-locations";- Inheritance
- ArcgisUtilityNetworkTraceLocations→
HTMLElement
- Since
- ArcGIS Maps SDK for JavaScript 5.2
The Utility Network Trace Locations component selects and manages trace locations. Users can add locations from the map, remove individual locations, clear the list, select terminals, and configure filter barriers where applicable. This component does not execute traces.
To use this component independently, set view to a ready map view, utilityNetwork to its loaded utility network, and filterLayers to the network layers available for selection. Use traceLocationType to choose starting points, barriers, or stopping points. Selected locations and their display information are stored in traceLocations.
Use heading to customize the heading and messageOverrides to customize messages. spatialTolerance controls duplicate detection along the same line feature. Listen for @arcgisError and read error for selection errors. autoDestroyDisabled controls automatic destruction when the component is removed from the DOM.
- Example
Display starting-point controls for a web map containing a utility network and its layers.
<arcgis-map id="trace-map" item-id="471eb0bf37074b1fbb972b1da70fb310"></arcgis-map><arcgis-utility-network-trace-locations heading="Starting points"></arcgis-utility-network-trace-locations>After importing the map and trace locations components, initialize the controls with the web map's utility network and its feature layers. The web map may require authentication.
const mapElement = document.getElementById("trace-map");const locations = document.querySelector("arcgis-utility-network-trace-locations");await Promise.all([mapElement.viewOnReady(), locations.componentOnReady()]);const utilityNetwork = mapElement.map.utilityNetworks.at(0);await utilityNetwork.load();locations.view = mapElement.view;locations.utilityNetwork = utilityNetwork;locations.filterLayers = mapElement.map.allLayers.filter((layer) =>utilityNetwork.isUtilityLayer(layer) &&(layer.type === "feature" || layer.type === "subtype-group"),);locations.traceLocationType = "starting-point";locations.addEventListener("arcgisTraceLocationSelectEnd", () => {console.log("Current trace location details:", locations.traceLocations.toArray());});
Properties
| Property | Attribute | Type |
|---|---|---|
| auto-destroy-disabled | ||
| error | ||
| | ||
| heading | ||
| | ||
| spatial-tolerance | ||
| | ||
| trace-location-type | ||
| | ||
| |
autoDestroyDisabled
- Type
- boolean
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() method when you are done to prevent memory leaks.
- Attribute
- auto-destroy-disabled
- Default value
- false
- Example
- <arcgis-utility-network-trace-locations auto-destroy-disabled></arcgis-utility-network-trace-locations>utilityNetworkTraceLocationsElement.autoDestroyDisabled = true;
error
The most recent selection error or warning reported through @arcgisError. Read this property when the event fires to display feedback to users or record it for troubleshooting, such as explaining why a trace location could not be added.
This message is not rendered by the component and is not automatically cleared after
a successful selection. It is undefined until a message is assigned.
- Attribute
- error
filterLayers
- Type
- Collection<Layer>
The utility network layers users can select trace locations from. These layers also provide features for snapping, helping users select locations accurately.
Set this collection to the network's feature layers or subtype group layers before users start selecting locations. For subtype group layers, the component uses their sublayers for snapping. The collection is initially empty.
heading
The heading displayed above the location controls. When undefined, the component uses
a localized heading for the current
traceLocationType.
- Attribute
- heading
spatialTolerance
- Type
- number
Controls how close two trace locations can be along the same polyline feature before they are treated as duplicates. Use a smaller value to allow locations closer together, or a larger value to keep them farther apart.
This value is a fraction of the polyline's length, not a distance in map units. With the default
value of 0.05, an attempt to add a new trace location is rejected if another trace location is
found within five percent of the polyline's total length, measured along the same polyline.
Trace locations placed exactly at that distance are also rejected.
Locations are compared using their percentAlong values. This tolerance does not apply to point or polygon features, for which a second location on the same feature is rejected.
- Attribute
- spatial-tolerance
- Default value
- 0.05
traceLocations
The selected trace locations and the information used to display them. Use this collection to read the trace locations users have selected, prepare inputs for a trace, or display details about those locations.
The collection is initially empty. Each entry contains a TraceLocation, display properties such as the title and selected terminal IDs, and spatial information such as the selected feature and its map marker.
Adding or removing locations through the component's UI updates this collection and the map markers.
When a user selects terminals, these choices are stored in flagProperties.selectedTerminals; they do not
create a separate traceLocation for each selected terminal. When constructing trace inputs, account for
the selected terminals rather than using only each entry's traceLocation.terminalId.
traceLocationType
- Type
- TraceLocationType
The type assigned to newly selected trace locations. Also determines the default heading, selection button text, and map marker symbol. Changing this property does not change the type of locations already in traceLocations.
- Attribute
- trace-location-type
- Default value
- "starting-point"
utilityNetwork
- Type
- UtilityNetwork | undefined
The utility network used to obtain terminal configurations and identify network sources when creating trace locations. Set this property to a loaded UtilityNetwork before selecting locations. The component does not load the utility network.
view
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
viewproperty which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-utility-network-trace-locations component will be associated with a map or scene component rather than using theviewproperty.
Methods
| Method | Signature |
|---|---|
| inherited | componentOnReady(): Promise<this> |
| destroy(): Promise<void> |
componentOnReady
- Signature
-
componentOnReady (): Promise<this>
Creates a promise that resolves once the component is fully loaded.
- Returns
- Promise<this>
- Example
- const arcgisUtilityNetworkTraceLocations = document.createElement("arcgis-utility-network-trace-locations");document.body.append(arcgisUtilityNetworkTraceLocations);await arcgisUtilityNetworkTraceLocations.componentOnReady();console.log("arcgis-utility-network-trace-locations is ready to go!");
Events
arcgisError
arcgisError: CustomEvent<void> Fires when the component reports a selection error or warning, such as a duplicate location or a map hit test with no usable results. Read error for the message. The event does not include error details and does not report every failure logged by the component.
arcgisTraceLocationSelectEnd
arcgisTraceLocationSelectEnd: CustomEvent<void> Fires when map selection ends, including when a location is added or selection is canceled. It can also fire when selection ends without adding a location because no usable feature is available. Read traceLocations for the current locations; this event does not guarantee that a location was added.
arcgisTraceLocationSelectStart
arcgisTraceLocationSelectStart: CustomEvent<SelectStartPayload> Fires before starting map selection for a trace location. Call preventDefault() on the
event to prevent selection from starting. The event's detail.cancelSelect callback
cancels the sketch after selection has started. This event also fires when the component
restarts selection after an unsuccessful attempt.
Type definitions
TraceLocationDetails
A trace location with its display, terminal, and spatial information maintained by arcgis-utility-network-trace-locations.
flagProperties
- Type
- { title: string; expanded?: boolean; terminalConfiguration?: TerminalConfiguration; selectedTerminals?: Set<number>; }
Display settings and terminal selections for the location.