arcgis-utility-networks

ArcGIS Utility Networks

将此技能用于公用设施网络：对连通基础设施进行追踪、关联关系管理、拓扑验证和网络分析。

导入模式

ESM（npm）

// Core network class
import UtilityNetwork from "@arcgis/core/networks/UtilityNetwork.js";

// Widgets
import UtilityNetworkTrace from "@arcgis/core/widgets/UtilityNetworkTrace.js";
import UtilityNetworkAssociations from "@arcgis/core/widgets/UtilityNetworkAssociations.js";
import UtilityNetworkValidateTopology from "@arcgis/core/widgets/UtilityNetworkValidateTopology.js";

// Support
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",
);

核心概念

公用设施网络用于对连通基础设施（电力、燃气、水务、电信）建模。核心概念：

• 网络追踪 — 沿网络中的连通关系进行追踪
• 关联关系 — 连通、包含和结构附着关系
• 子网络 — 网络中彼此隔离的部分
• 拓扑 — 网络连通性验证

地图组件实现方式

Utility Network Trace 组件

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

Utility Network Associations 组件

<arcgis-map item-id="e53b1054b29f4579baf878dcf2effe7a">
  <arcgis-utility-network-associations
    slot="top-right"
  ></arcgis-utility-network-associations>
</arcgis-map>

Utility Network Validate Topology 组件

<arcgis-map item-id="YOUR_WEBMAP_ID">
  <arcgis-utility-network-validate-topology
    slot="top-right"
  ></arcgis-utility-network-validate-topology>
</arcgis-map>

Utility Network Trace Analysis 组件

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

组件汇总

组件	用途
arcgis-utility-network-trace	交互式追踪 UI
arcgis-utility-network-associations	关联关系可视化
arcgis-utility-network-trace-analysis	详细的追踪分析
arcgis-utility-network-validate-topology	拓扑验证

核心 API 实现方式

UtilityNetworkTrace 微件

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	MapView	地图视图（必填）
flags	MapPoint[]	起点和障碍物
selectedTraces	string[]	加载时要选中的追踪项的全局 ID
showSelectionAttributes	boolean	将结果显示为整理后的列表
selectOnComplete	boolean	追踪完成后自动选择要素
enableResultArea	boolean	显示结果区域图形
resultAreaColor	Color	聚合追踪几何的颜色

UtilityNetworkTrace 事件

事件	描述
trace-complete	追踪完成后触发
result-area-added	添加结果区域图形时触发
result-area-removed	移除结果区域图形时触发

UtilityNetworkAssociations 微件

view.when(async () => {
  await webMap.load();

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

    const unAssociations = new UtilityNetworkAssociations({
      view,
      utilityNetwork,
    });

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

关联类型

• 连通 — 要素之间的电气连接或流体流通连接
• 包含 — 一个要素包含在另一个要素内部
• 结构附着 — 要素附着在结构上

Associations 可见元素

const unAssociations = new UtilityNetworkAssociations({
  view,
  utilityNetwork,
  visibleElements: {
    maxAllowableAssociationsSlider: true,
    connectivityAssociationsSettings: {
      arrowsToggle: false,
      capSelect: false,
      colorPicker: true,
      stylePicker: true,
      widthInput: true,
    },
    structuralAttachmentAssociationsSettings: {
      arrowsToggle: false,
      capSelect: false,
      colorPicker: true,
      stylePicker: true,
      widthInput: true,
    },
  },
});

访问公用设施网络

从 WebMap 获取 Utility Network

await webMap.load();

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

  console.log("Title:", utilityNetwork.title);
  console.log("Dataset name:", utilityNetwork.datasetName);
  console.log("Domain networks:", utilityNetwork.domainNetworks);
  console.log("Network attributes:", utilityNetwork.networkAttributes);
  console.log("Terminal configs:", utilityNetwork.terminalConfigurations);
}

UtilityNetwork 属性

属性	类型	描述
title	string	网络标题
datasetName	string	数据集名称
domainNetworks	object[]	公用设施网络中的域网络
networkAttributes	object[]	网络属性
terminalConfigurations	object[]	终端配置
sharedNamedTraceConfigurations	object[]	共享追踪配置

UtilityNetwork 方法

方法	描述
load()	加载公用网络元数据
trace(traceParams)	同步执行追踪
submitTraceJob(traceParams)	异步执行追踪
queryAssociations(params)	查询关联
synthesizeAssociationGeometries(extent)	获取关联几何
loadAssociationsTable()	加载关联表（建议在查询前执行）

网络追踪

追踪类型

追踪类型	描述
Connected	查找所有连通要素
Upstream	朝源头方向追踪
Downstream	远离源头方向追踪
Subnetwork	查找同一子网中的要素
Isolation	查找隔离点
Loops	查找网络中的环路

以编程方式执行追踪

const utilityNetwork = webMap.utilityNetworks.getItemAt(0);
await utilityNetwork.load();

const traceResult = await utilityNetwork.trace(traceParams);

// For long-running traces
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,
  },
});

完整示例

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <link
      rel="stylesheet"
      href="https://js.arcgis.com/5.0/esri/themes/light/main.css"
    />
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
    <script
      type="module"
      src="https://js.arcgis.com/map-components/5.0/arcgis-map-components.esm.js"
    ></script>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>
  </head>
  <body>
    <arcgis-map item-id="YOUR_WEBMAP_ID">
      <arcgis-utility-network-trace
        slot="top-right"
      ></arcgis-utility-network-trace>
      <arcgis-utility-network-associations
        slot="bottom-right"
      ></arcgis-utility-network-associations>
    </arcgis-map>
  </body>
</html>

常见问题

1. 需要身份验证：公用网络服务通常需要身份验证——请配置 esriConfig.portalUrl 和凭据。

2. 需要 WebMap：必须通过 WebMap 访问公用网络，无法在客户端创建。

3. 关联需要高缩放级别：关联仅在非常高的缩放级别下显示——请使用 TileInfo.create({ numLODs: 32 }) 并设置 snapToZoom: false。

4. 加载顺序：必须先加载 WebMap，再加载 UtilityNetwork，然后才能创建微件。

5. Enterprise 门户：通常托管在 ArcGIS Enterprise 上——请将 esriConfig.portalUrl 设置为门户 URL。

6. 拓扑验证：必须启用并验证网络拓扑，才能获得准确的追踪结果。

7. 命名追踪配置：追踪微件需要共享的命名追踪配置（Enterprise 10.9+）。

参考示例

• utility-network-trace — 运行公用网络追踪
• utility-network-associations — 查看关联
• widgets-untrace — 公用网络追踪微件

相关技能

• arcgis-layers — 图层配置和 WebMap 加载
• arcgis-authentication — 门户身份验证设置
• arcgis-widgets-ui — 微件放置和 UI 自定义