ArcGIS Maps SDK for JavaScript 5.0 组件化开发指南

- 前言
- [一、什么是 ArcGIS Maps SDK Components？](#一、什么是 ArcGIS Maps SDK Components？)
- - 组件分类一览
- [二、为什么选择 Components？](#二、为什么选择 Components？)
- - [1. Esri 官方战略方向](#1. Esri 官方战略方向)
  - [2. React 19 完美支持](#2. React 19 完美支持)
  - [3. 与传统开发方式对比](#3. 与传统开发方式对比)
- 三、快速入门
- - [方式一：CDN 引入（推荐用于原型开发）](#方式一：CDN 引入（推荐用于原型开发）)
  - [方式二：NPM 安装（推荐用于生产项目）](#方式二：NPM 安装（推荐用于生产项目）)
- [四、在 Experience Builder 中使用组件](#四、在 Experience Builder 中使用组件)
- - 开发步骤
- 五、组件的高级用法
- - [1. 多个组件组合使用](#1. 多个组件组合使用)
  - [2. 响应式状态管理](#2. 响应式状态管理)
- 六、注意事项
- - [1. 版本兼容性](#1. 版本兼容性)
  - [2. 性能优化建议](#2. 性能优化建议)
  - [3. 天地图集成](#3. 天地图集成)
- 七、总结

前言

随着 Web 技术的不断发展，ArcGIS Maps SDK for JavaScript 也在持续演进。5.0 版本带来了全新的组件化架构------ArcGIS Maps SDK Components，这是一套基于 Web Components 标准构建的可复用 UI 组件库。本文将详细介绍 ArcGIS JS 5.0 的组件化特性，帮助开发者了解这一全新的开发模式。

📌 地图初始化完整示例请参阅姊妹篇：[《ArcGIS JS 5.0 Component 地图初始化实战》]

一、什么是 ArcGIS Maps SDK Components？

ArcGIS Maps SDK Components 是 ArcGIS 官方推出的一套Web Components组件库，将 ArcGIS 核心功能封装为标准的自定义 HTML 元素。这套组件具有以下核心特性：

特性	说明
框架无关性	可在任何 JavaScript 框架或原生 HTML 中使用
响应式设计	组件内部已经处理好了响应式布局
声明式 API	通过 HTML 属性即可配置组件行为
事件驱动	支持标准 DOM 事件监听

组件分类一览

类别	组件	用途
地图与场景	`<arcgis-map>`, `<arcgis-scene>`	显示 2D 地图和 3D 场景
图层与图例	`<arcgis-layer-list>`, `<arcgis-legend>`	管理和展示图层
搜索与定位	`<arcgis-search>`, `<arcgis-locate>`	地理编码和设备定位
底图与导航	`<arcgis-basemap-gallery>`, `<arcgis-home>`, `<arcgis-navigation-toggle>`	底图切换和导航控制
编辑与绘制	`<arcgis-sketch>`	要素绘制和编辑
测量与坐标	`<arcgis-measurement>`, `<arcgis-coordinate-conversion>`	距离面积测量和坐标转换
图表与分析	`<arcgis-chart>`, `<arcgis-charts-action-bar>`	数据可视化

二、为什么选择 Components？

1. Esri 官方战略方向

根据 Esri 官方博客的介绍，Esri 已经全面转向基于标准 Web Components 的开发模式。所有传统的 JavaScript Maps SDK Widget 功能都将被弃用并逐步移除。这意味着组件化开发是未来的主流方向。

2. React 19 完美支持

ArcGIS Experience Builder (版本 1.19+) 已经基于 React 19 构建。React 19 对 Web Components 提供了完整支持：

✅ 全面的自定义元素支持
✅ 改进的事件处理机制
✅ 增强的属性管理

3. 与传统开发方式对比

复制代码

传统方式 (Widget)：
┌─────────────────────────────────────────┐
│  require(['esri/widgets/Legend'], ...),  │
│  new Legend({ view: mapView })          │
└─────────────────────────────────────────┘

组件方式 (Component)：
┌─────────────────────────────────────────┐
│  <arcgis-legend view={view}></arcgis-legend>  │
└─────────────────────────────────────────┘

三、快速入门

方式一：CDN 引入（推荐用于原型开发）

html 复制代码

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <title>ArcGIS Components Demo</title>
    <!-- 引入 ArcGIS CSS -->
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css"/>
    <!-- 引入 ArcGIS SDK -->
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
</head>
<body>
    <arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca"></arcgis-map>
</body>
</html>

方式二：NPM 安装（推荐用于生产项目）

bash 复制代码

npm install @arcgis/map-components

javascript 复制代码

import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-legend";
import "@arcgis/map-components/components/arcgis-search";

四、在 Experience Builder 中使用组件

ArcGIS Experience Builder 是构建 Web App 的低代码平台，可以直接使用 Map Components 来开发自定义组件。

开发步骤

创建自定义组件：在 Experience Builder Developer Edition 中创建组件文件夹和文件
导入组件：在组件的 TypeScript 文件中导入需要的组件

typescript 复制代码

import '@arcgis/map-components/dist/arcgis-map.js';
import '@arcgis/map-components/dist/arcgis-search.js';
import '@arcgis/map-components/dist/arcgis-legend.js';

声明式使用：在 React 组件中直接使用 Web Components

typescript 复制代码

const MyWidget = () => {
  return (
    <div>
      <arcgis-map item-id="your-webmap-item-id"></arcgis-map>
    </div>
  );
};

处理事件：使用标准 DOM 事件监听

typescript 复制代码

useEffect(() => {
  const mapElement = document.querySelector('arcgis-map');
  if (mapElement) {
    mapElement.addEventListener('arcgisViewReadyChange', (event) => {
      const view = event.detail.view;
      console.log('Map view is ready:', view);
    });
  }
}, []);

五、组件的高级用法

1. 多个组件组合使用

html 复制代码

<div style={{ display: 'flex', height: '500px' }}>
  <div style={{ flex: '1' }}>
    <arcgis-map id="my-map" item-id="your-webmap-item-id"></arcgis-map>
  </div>
  <div style={{ width: '250px', padding: '10px' }}>
    <arcgis-legend reference-id="my-map"></arcgis-legend>
    <arcgis-layer-list reference-id="my-map"></arcgis-layer-list>
  </div>
</div>

2. 响应式状态管理

typescript 复制代码

const EnhancedWidget = () => {
  const [mapReady, setMapReady] = useState(false);

  useEffect(() => {
    const mapElement = document.querySelector('arcgis-map');
    if (mapElement) {
      const handleViewReady = (event) => {
        setMapReady(true);
        const view = event.detail.view;
        // 执行额外的视图设置
      };

      mapElement.addEventListener('arcgisViewReadyChange', handleViewReady);
      return () => {
        mapElement.removeEventListener('arcgisViewReadyChange', handleViewReady);
      };
    }
  }, []);

  return (
    <div>
      <arcgis-map ...></arcgis-map>
      {mapReady && <arcgis-search ...></arcgis-search>}
    </div>
  );
};

六、注意事项

1. 版本兼容性

ArcGIS Maps SDK for JavaScript 5.0+ 提供 Components 支持
Experience Builder 需要 1.15+ 版本
React 19 提供了最佳的 Web Components 支持体验

2. 性能优化建议

使用 componentOnReady() 确保组件加载完成后再操作
合理使用 await viewOnReady() 避免竞态条件
注意组件销毁时清理事件监听器

3. 天地图集成

使用天地图作为底图时，可以利用第三方工具类：

javascript 复制代码

const getTianditu = await $arcgis.import("https://openlayers.vip/examples/resources/tianditu.js");
const vecLayers = getTianditu.default({ type: "vec_w" });

七、总结

ArcGIS Maps SDK for JavaScript 5.0 的组件化架构为开发者带来了更现代化、更便捷的开发体验。通过声明式的 HTML 标签，开发者可以快速构建复杂的地图应用，而无需编写大量的 JavaScript 代码。

核心优势总结：

🚀 开发效率提升：声明式 API，代码更简洁
🔮 未来可扩展：符合 Web Components 标准，顺应技术发展趋势
🌍 框架无关：可在 React、Vue、Angular 或原生 JS 中使用
📦 开箱即用：提供丰富的预构建 UI 组件

建议开发者现在开始尝试使用 Components 进行开发，以获得更好的开发体验和长期的技术支持。

下一篇 ：《ArcGIS JS 5.0 Component 地图初始化实战》 --- 包含完整的 3D 场景组件化开发示例代码及逐行解析。

参考资料：