ArcGIS Maps SDK for JavaScript 5.0 组件（Component）地图初始化示例

前言

本文是 ArcGIS Maps SDK for JavaScript 5.0 组件化开发指南的姊妹篇，重点介绍如何使用 ArcGIS JS 5.0 Components 进行地图初始化。我们将提供一个完整的 3D 场景组件化开发示例，并逐行解析核心代码。

📌 组件概念介绍请参阅：《ArcGIS Maps SDK for JavaScript 5.0 组件化开发指南》

一、完整示例代码

以下示例展示了使用 ArcGIS JS 5.0 Components 实现 3D 场景的完整代码，集成了天地图作为底图并加载倾斜摄影图层：

需要注意的是，组件式初始化场景，默认会加载 ==arcgis官方资源==，

需要手动替换为其他资源，否则不能正常初始化。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"/>
    <title>HelloWorld Component | Sample | ArcGIS Maps SDK for JavaScript</title>

    <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>

    <style>
        html,
        body {
    
            margin: 0;
            height: 100%;
        }
    </style>
</head>

<body>
<arcgis-scene id="viewDiv"
        camera-position="111.848111, 40.713906, 1990"
        camera-tilt="82.9"
        camera-heading="124.7">
    <arcgis-zoom slot="top-left"></arcgis-zoom>
    <arcgis-navigation-toggle slot="top-left"></arcgis-navigation-toggle>
    <arcgis-compass slot="top-left"></arcgis-compass>
    <arcgis-layer-list slot="top-right"></arcgis-layer-list>
</arcgis-scene>

<script type="module">
    const [IntegratedMeshLayer, Map,
        SpatialReference,
    ] = await $arcgis.import([
        "@arcgis/core/layers/IntegratedMeshLayer.js",
        "@arcgis/core/Map.js",
        "@arcgis/core/geometry/SpatialReference.js",
    ]);

    const getTianditu = await $arcgis.import("https://openlayers.vip/examples/resources/tianditu.js");

    // 初始矢量底图
    const vecLayers = getTianditu.default({
    type: "vec_w"});

    const map = new Map({
    
        basemap: {
    baseLayers: [vecLayers.base, vecLayers.anno]},
    });

    // 获取 Scene 组件并设置地图和初始相机
    const viewElement = document.querySelector("arcgis-scene");
    const view = viewElement.view;
    view.map = map;

    console.log(view);

    // 添加倾斜摄影图层
    const layer1 = new IntegratedMeshLayer({
    
        url: "https://gs3d.geosceneonline.cn/server/rest/services/Hosted/hk1/SceneServer",
        title: '香港倾斜图层'
    });

    map.add(layer1);

    // 等待视图准备就绪
    // 一定要写在 view.map = map; 之后
    await viewElement.viewOnReady();
    view.extent = layer1.fullExtent;

    // 等待图层列表组件准备就绪
    const arcgisLayerList = document.querySelector("arcgis-layer-list");
    await arcgisLayerList.componentOnReady();
    console.log("arcgis-layer-list is ready to go!");
</script>
</body>
</html>

🚀 在线体验：ArcGIS JS 5.0 Component 地图初始化示例

二、代码逐行解析

1. HTML 声明式组件

<arcgis-scene id="viewDiv"
    camera-position="111.848111, 40.713906, 1990"
    camera-tilt="82.9"
    camera-heading="124.7">

<arcgis-scene> 是 3D 场景的容器组件，通过 HTML 属性即可设置初始相机参数：

💡 提示：2D 地图使用 <arcgis-map> 组件，属性会有所不同。

2. UI 组件插槽布局

<arcgis-zoom slot="top-left"></arcgis-zoom>
<arcgis-navigation-toggle slot="top-left"></arcgis-navigation-toggle>
<arcgis-compass slot="top-left"></arcgis-compass>
<arcgis-layer-list slot="top-right"></arcgis-layer-list>

组件使用 slot 属性来指定在父容器中的位置：

3. 动态模块导入

const [IntegratedMeshLayer, Map, SpatialReference] = await $arcgis.import([
    "@arcgis/core/layers/IntegratedMeshLayer.js",
    "@arcgis/core/Map.js",
    "@arcgis/core/geometry/SpatialReference.js",
]);

使用 $arcgis.import() 可以动态导入 ArcGIS 核心模块，这是 5.0 版本的特性，支持同时导入多个模块。

4. 天地图底图配置

注意，这里的天地图资源只能在当前域名下使用！

const getTianditu = await $arcgis.import("https://openlayers.vip/examples/resources/tianditu.js");

const vecLayers = getTianditu.default({
   type: "vec_w"});

const map = new Map({
   
    basemap: {
   baseLayers: [vecLayers.base, vecLayers.anno]},
});

使用第三方工具类加载天地图作为底图，vec_w 表示矢量底图（中文标注）。

5. 获取视图并设置地图

const viewElement = document.querySelector("arcgis-scene");
const view = viewElement.view;
// 注意，一定要写在 await viewElement.viewOnReady(); 之前
view.map = map;

通过 document.querySelector() 获取组件引用，然后访问其 view 属性获取 SceneView 实例，设置地图对象。

6. 添加 3D 图层

const layer1 = new IntegratedMeshLayer({
   
    url: "https://gs3d.geosceneonline.cn/server/rest/services/Hosted/hk1/SceneServer",
    title: '香港倾斜图层'
});

map.add(layer1);

IntegratedMeshLayer 用于加载倾斜摄影测量数据（3D Tiles），这是一种高效的 3D 网格数据格式。

7. 异步等待机制

// 一定要写在 view.map = map; 之后
await viewElement.viewOnReady();
view.extent = layer1.fullExtent;

const arcgisLayerList = document.querySelector("arcgis-layer-list");
await arcgisLayerList.componentOnReady();

两个重要的异步方法：

• viewOnReady()：等待视图（地图/场景）完全加载
• componentOnReady()：等待组件内部准备就绪

三、常用组件属性一览

arcgis-scene（3D 场景）

<arcgis-scene
    id="my-scene"
    camera-position="118.805, 34.027, 1000"
    camera-tilt="45"
    camera-heading="0"
    basemap="satellite">
</arcgis-scene>

arcgis-map（2D 地图）

<arcgis-map
    id="my-map"
    center="118.805, 34.027"
    zoom="13"
    basemap="streets">
</arcgis-map>

arcgis-zoom（缩放控件）

<arcgis-zoom slot="top-left"></arcgis-zoom>

arcgis-search（搜索控件）

<arcgis-search
    slot="top-right"
    reference-id="my-map">
</arcgis-search>

arcgis-legend（图例）

<arcgis-legend
    slot="bottom-right"
    reference-id="my-map">
</arcgis-legend>

四、完整项目结构

使用 NPM 方式的项目结构通常如下：

my-arcgis-app/
├── index.html
├── package.json
└── src/
    └── main.js

package.json：

{
   
  "name": "arcgis-components-demo",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
   
    "@arcgis/map-components": "^5.0.0"
  }
}

src/main.js：

import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-scene";
import "@arcgis/map-components/components/arcgis-zoom";
import "@arcgis/map-components/components/arcgis-legend";
import "@arcgis/map-components/components/arcgis-layer-list";

const [Map] = await $arcgis.import([
    "@arcgis/core/Map.js",
]);

const map = new Map({
   
    basemap: "streets"
});

const mapElement = document.querySelector("arcgis-map");
mapElement.map = map;

五、常见问题

Q1: 组件不显示？

确保已正确引入 ArcGIS 样式文件和 SDK 脚本：

<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>

Q2: 如何获取视图对象？

const viewElement = document.querySelector("arcgis-scene");
const view = viewElement.view;

Q3: 如何等待地图加载完成？

await viewElement.viewOnReady();
// 地图已加载完成，可以安全操作

Q4: 天地图不显示？

检查网络请求是否被阻止，天地图需要有效的网络连接。如果在内网环境，可以考虑使用离线底图服务。

六、总结

本文详细介绍了 ArcGIS JS 5.0 Components 的地图初始化方法，通过声明式的 HTML 标签和简洁的 JavaScript 代码，即可快速构建 3D 地图应用。

核心要点：

• 📦 使用 <arcgis-scene> 或 <arcgis-map> 作为地图容器
• 🧭 通过 slot 属性控制 UI 组件的位置
• 📥 使用 $arcgis.import() 动态加载核心模块
• ⏳ 使用 viewOnReady() 和 componentOnReady() 处理异步加载

上一篇：《ArcGIS Maps SDK for JavaScript 5.0 组件化开发指南》 — 组件概念介绍、优势分析、Experience Builder 使用指南。

参考资料：

• ArcGIS Maps SDK for JavaScript - Map Components
• Use Map Components in Custom Widget