▾
import type { UtilityNetworkTraceAnalysisDisplayMode, UtilityNetworkTraceResultItemState, UtilityNetworkTraceResultItem } from "@arcgis/map-components/components/arcgis-utility-network-trace-analysis/types.js";Type definitions
UtilityNetworkTraceAnalysisDisplayMode
- Type
- "add-spatial-feature" | "add-spatial-instructions" | "default"
UtilityNetworkTraceResultItem
- Since
- ArcGIS Maps SDK for JavaScript 5.2
Describes the properties and lifecycle methods used by the built-in trace result item components.
Use this interface as a reference when creating a custom trace result item component to place in the default slot of arcgis-utility-network-trace-results. It describes the context, configuration, readiness, and cleanup behavior you may want to implement, depending on what your custom result item component displays or does.
A custom result item component only needs the optional context and configuration properties it uses.
The trace results component does not assign these properties to slotted custom result item components. Set the properties your custom result item component needs, for example by reading the trace result from the parent trace results component. Listen for the parent's arcgis-utility-network-trace-results.@arcgisPropertyChange event to handle subsequent changes, ignoring events whose target is not the parent. Remove event listeners when the custom result item component disconnects.
Coordinate result readiness
Set UtilityNetworkTraceResultItem
to true before slotting a custom item if the trace results component should wait for that result item to emit
arcgisResultReady before displaying trace results. For example, a result item that queries features should
set emitsArcgisResultReady to true and emit arcgisResultReady after the feature queries finish and the
result item is ready to display its results.
The trace results component stays in its loading state
until every participating result item (including default result items) has signaled completion by emitting arcgisResultReady.
The trace results component then emits arcgis-utility-network-trace-results.@arcgisResultsReady.
Signal completion even when processing produces no applicable results or fails, after displaying any error. Otherwise, the trace results component keeps waiting.
Set emitsArcgisResultReady to false for an item that does not need to delay readiness,
such as static content about the trace results.
Clear output between trace results
Specify a UtilityNetworkTraceResultItem
method to clean up a custom result item component's side effects. The trace results component calls this method
when its trace result changes or
arcgis-utility-network-trace-results.clearResults() is called.
For example, if a custom result item adds graphics to the map, its clearResult callback may
remove the graphics from the map.
Cleanup is independent of readiness: an item with emitsArcgisResultReady set to false can still provide
clearResult. Cleanup must be safe to repeat and must not emit arcgisResultReady or destroy the item.
Keep the item ready to process the next trace result.
Adding any content to the trace results component's default slot replaces all default result items, so include each built-in or custom item you want to display.
layers
The layers and tables used to query features associated with the trace result.
The elements result item uses this configuration to restrict feature queries to specific utility network layers and tables. An empty array uses the map's layers and tables that belong to the selected utility network.
The trace results component forwards its layers only to its internally created elements result item. Custom result items decide how to use this property.
heading
The heading displayed by the result item.
Configure this on the custom result item component, not on the trace results component. The trace results component heading describes the whole trace rather than an individual item.
For example, the functions result item displays this heading above its table and uses a localized default when it is omitted or empty. Custom items control where the heading appears and whether a default is provided.
traceResult
- Type
- TraceResult | undefined
The trace result processed and displayed by the result item.
Read this value from the parent trace results component. Built-in items process the relevant part of the result: elements, aggregated geometry, or function results. Custom items can process any part they need.
To access the full trace response in JSON format, including fields not exposed by the TraceResult class, use
TraceResult.sourceJSON.
Handle an undefined value when no result is available, and replace output from the previous result when a
new result arrives.
If the item participates in readiness tracking, signal completion even when the result contains no data relevant to the item.
utilityNetwork
- Type
- UtilityNetwork | undefined
The utility network associated with the trace result.
Read this value from the parent trace results component. The elements result item uses it to identify utility network layers and resolve trace elements to features.
view
The map view used to display and interact with the trace result.
Read this value from the parent trace results component. The elements result item uses it to query layers and highlight features. The aggregated geometry result item uses it to display graphics.
emitsArcgisResultReady
- Type
- boolean
Indicates whether the result item emits an arcgisResultReady event after processing a trace result.
Set this to true before adding the item to the trace results component to participate in readiness tracking.
Dispatch arcgisResultReady from the custom result item component after processing a trace result. No event detail is required.
Once all participating result item components (including default result items) emit arcgisResultReady,
the trace results component changes its state to "ready" and emits
arcgis-utility-network-trace-results.@arcgisResultsReady.
Signal completion when processing finishes, including when there are no applicable results or processing fails.
If this property is true and a custom result item never emits arcgisResultReady, the trace results component remains
in its "loading" state and does not emit arcgisResultsReady.
Do not emit arcgisResultReady for work canceled by clearResult.
Set this to false when the trace results component does not need to wait for the custom result item,
e.g., displaying static content for the trace result.
- Example
Set the property and dispatch the event after the current result has finished processing:
class MyTraceResultItem extends HTMLElement {emitsArcgisResultReady = true;finishProcessing(): void {this.dispatchEvent(new CustomEvent("arcgisResultReady"));}}
clearResult
- Type
- () => void
Clears the result item's rendered output and side effects, such as graphics added to the map.
The trace results component calls this function when its arcgis-utility-network-trace-results.clearResults() method is called or its trace result changes.
Cancel pending work, clear the item's stored trace result and rendered output, and undo other side effects here.
Ensure canceled work cannot restore stale output or emit arcgisResultReady.
It must be safe to call this function when the item is already clear.
This function is synchronous and must not emit arcgisResultReady. It does not destroy the item or remove
its context listeners; the item can be reused for subsequent trace results.
- Example
This excerpt shows cleanup for the query example above. Abort the pending query, remove only the graphics created by this component, and clear any displayed error:
import type Graphic from "@arcgis/core/Graphic.js";import type MapView from "@arcgis/core/views/MapView.js";class MyTraceResultItem extends HTMLElement {#controller?: AbortController;#view?: MapView;#graphics: Graphic[] = [];clearResult(): void {this.#controller?.abort();this.#controller = undefined;this.#view?.graphics.removeMany(this.#graphics);this.#view = undefined;this.#graphics = [];this.replaceChildren();}}
- Examples
After registering a custom element named
my-trace-result-item, add it alongside a built-in result item. The custom item is responsible for reading its context from the trace results component and processing each trace result.<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310"><arcgis-utility-network-trace-analysis slot="bottom-left"><arcgis-utility-network-trace-results slot="results"><arcgis-utility-network-trace-elements-result-item></arcgis-utility-network-trace-elements-result-item><my-trace-result-item></my-trace-result-item></arcgis-utility-network-trace-results></arcgis-utility-network-trace-analysis></arcgis-map>This custom element excerpt queries up to 25 point features in the current view extent, adds them to the map, and removes them when
clearResultis called.import type FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";import type Graphic from "@arcgis/core/Graphic.js";import type MapView from "@arcgis/core/views/MapView.js";class MyTraceResultItem extends HTMLElement {emitsArcgisResultReady = true;#controller?: AbortController;#view?: MapView;#graphics: Graphic[] = [];async processResult(layer: FeatureLayer, view: MapView): Promise<void> {this.clearResult();const controller = new AbortController();this.#controller = controller;try {const query = layer.createQuery();query.geometry = view.extent;query.num = 25;query.returnGeometry = true;query.outSpatialReference = view.spatialReference;const { features } = await layer.queryFeatures(query, { signal: controller.signal });if (controller.signal.aborted) {return;}this.#view = view;this.#graphics = features;view.graphics.addMany(features);} catch (error) {if (!controller.signal.aborted) {console.error(error);this.textContent = "Could not load trace results.";}} finally {if (this.#controller === controller) {this.#controller = undefined;this.dispatchEvent(new CustomEvent("arcgisResultReady"));}}}clearResult(): void {this.#controller?.abort();this.#controller = undefined;this.#view?.graphics.removeMany(this.#graphics);this.#view = undefined;this.#graphics = [];this.replaceChildren();}}clearResultaborts an in-flight query; its canceled work does not emitarcgisResultReady. The sample's extent query is illustrative; use a query appropriate to the trace result in your component.