arcgis-utility-networks

用途

ArcGIS Utility Networks 技能面向公共设施网络的建模与分析，适用于电力、燃气、供水、电信等连通基础设施。它帮助开发者在 ArcGIS Maps SDK for JavaScript 中实现网络追踪、关联关系可视化、拓扑校验和网络分析。

主要能力

网络追踪（Network tracing）：沿网络连通性进行追踪，支持 Connected（查找所有连通要素）、Upstream（向源方向追踪）、Downstream（远离源方向追踪）、Subnetwork（查找同一子网内的要素）、Isolation（查找隔离点）、Loops（查找网络中的环路）等追踪类型。
关联关系（Associations）：处理连通（Connectivity，要素间的电气/流动连接）、包含（Containment，要素被包含在其他要素内）、结构附着（Structural Attachment，要素附着到结构上）三类关系。
子网（Subnetworks）：识别网络中相互隔离的部分。
拓扑（Topology）：进行网络连通性校验。

使用方式

导入模式

ESM（npm）：

import UtilityNetwork from "@arcgis/core/networks/UtilityNetwork.js";
import UtilityNetworkTrace from "@arcgis/core/widgets/UtilityNetworkTrace.js";
import UtilityNetworkAssociations from "@arcgis/core/widgets/UtilityNetworkAssociations.js";
import UtilityNetworkValidateTopology from "@arcgis/core/widgets/UtilityNetworkValidateTopology.js";
import TileInfo from "@arcgis/core/layers/support/TileInfo.js";
import WebMap from "@arcgis/core/WebMap.js";
import MapView from "@arcgis/core/views/MapView.js";
import esriConfig from "@arcgis/core/config.js";

CDN（动态导入）：

const UtilityNetwork = await $arcgis.import("@arcgis/core/networks/UtilityNetwork.js");
const UtilityNetworkTrace = await $arcgis.import("@arcgis/core/widgets/UtilityNetworkTrace.js");
const UtilityNetworkAssociations = await $arcgis.import("@arcgis/core/widgets/UtilityNetworkAssociations.js");

Map Components 组件方式

<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
  <arcgis-utility-network-trace slot="top-right"></arcgis-utility-network-trace>
</arcgis-map>

组件包括：arcgis-utility-network-trace（交互式追踪 UI）、arcgis-utility-network-associations（关联可视化）、arcgis-utility-network-trace-analysis（详细追踪分析）、arcgis-utility-network-validate-topology（拓扑校验）。

核心 API 方式

esriConfig.portalUrl = "https://www.arcgis.com";

const webmap = new WebMap({ portalItem: { id: "YOUR_WEBMAP_ID" } });
const view = new MapView({ container: "viewDiv", map: webmap });

const utilityNetworkTrace = new UtilityNetworkTrace({
  view: view,
  showSelectionAttributes: true,
  selectOnComplete: true,
});

view.ui.add(utilityNetworkTrace, "top-right");

UtilityNetworkTrace 属性包括 view（必填）、flags、selectedTraces、showSelectionAttributes、selectOnComplete、enableResultArea、resultAreaColor；事件包括 trace-complete、result-area-added、result-area-removed。

访问公共设施网络

await webMap.load();
if (webMap.utilityNetworks && webMap.utilityNetworks.length > 0) {
  const utilityNetwork = webMap.utilityNetworks.getItemAt(0);
  await utilityNetwork.load();
}

UtilityNetwork 属性包括 title、datasetName、domainNetworks、networkAttributes、terminalConfigurations、sharedNamedTraceConfigurations；方法包括 load()、trace(traceParams)、submitTraceJob(traceParams)、queryAssociations(params)、synthesizeAssociationGeometries(extent)、loadAssociationsTable()。

编程式追踪与关联查询

const traceResult = await utilityNetwork.trace(traceParams);
const jobInfo = await utilityNetwork.submitTraceJob(traceParams);

await utilityNetwork.loadAssociationsTable();
const result = await utilityNetwork.queryAssociations(queryParams);

高缩放级别支持

关联关系仅在非常高的缩放级别可见，需配置额外 LOD：

const tileInfo = TileInfo.create({
  spatialReference: { wkid: 102100 },
  numLODs: 32,
});

const view = new MapView({
  container: "viewDiv",
  map: webMap,
  zoom: 25,
  constraints: { lods: tileInfo.lods, snapToZoom: false },
});

适用场景

公共设施网络的连通性追踪与上下游分析
关联关系（连通、包含、结构附着）的可视化与查询
网络拓扑校验
子网与环路识别

限制与注意事项

需要身份验证：公共设施网络服务通常需要认证，需配置 esriConfig.portalUrl 和凭据。
必须通过 WebMap：公共设施网络必须通过 WebMap 访问，无法在客户端创建。
关联关系需高缩放：关联关系仅在非常高的缩放级别显示，需使用 TileInfo.create({ numLODs: 32 }) 并设置 snapToZoom: false。
加载顺序：必须先加载 WebMap，再加载 UtilityNetwork，然后才能创建组件。
企业门户：通常托管在 ArcGIS Enterprise 上，需将 esriConfig.portalUrl 设置为门户 URL。
拓扑校验：网络拓扑必须启用并校验后才能获得准确的追踪结果。
命名追踪配置：追踪组件需要共享命名追踪配置（Enterprise 10.9+）。

技能介绍

用途