arcgis-core-maps

ArcGIS 核心地图

使用 ArcGIS Maps SDK for JavaScript 创建 2D 地图（MapView）或 3D 场景（SceneView）时，请使用此技能。

导入模式

直接 ESM 导入（构建工具推荐）

配合 Vite、webpack、Rollup 或其他构建工具使用：

import Map from "@arcgis/core/Map.js";
import MapView from "@arcgis/core/views/MapView.js";
import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";

• 支持摇树优化
• 标准 JavaScript 模块
• 最适合生产应用

动态导入（CDN / 无构建工具）

无法使用构建步骤时，使用 CDN 脚本标签：

const Map = await $arcgis.import("@arcgis/core/Map.js");
const MapView = await $arcgis.import("@arcgis/core/views/MapView.js");

// Multiple imports
const [FeatureLayer, Graphic] = await $arcgis.import([
  "@arcgis/core/layers/FeatureLayer.js",
  "@arcgis/core/Graphic.js",
]);

• 可与 Map Components（Web 组件）配合使用
• 无需构建步骤
• 适用于快速原型和演示
• 需要在 HTML 中添加 <script src="https://js.arcgis.com/5.0/"></script>

**注意：**此技能中的示例使用直接 ESM 导入。使用 CDN 时，将 import X from "path" 替换为 const X = await $arcgis.import("path")。

自动类型转换与显式类（TypeScript）

ArcGIS SDK 支持自动类型转换——传入普通对象而非类实例。

何时使用显式类（不进行自动类型转换）

在以下情况中使用 new SimpleRenderer()、new Point() 等：

• 需要实例方法或 instanceof 检查时
• 构建共享内部库时——构造函数 API 的破坏性变更会在编译时显现
• 希望编辑器提供清晰的属性提示时——new SimpleRenderer({ ... }) 会明确展示属性
• 逐步修改对象时——长期存在的实例使用真正的类会更清晰

import SimpleRenderer from "@arcgis/core/renderers/SimpleRenderer.js";
import SimpleMarkerSymbol from "@arcgis/core/symbols/SimpleMarkerSymbol.js";

const renderer = new SimpleRenderer({
  symbol: new SimpleMarkerSymbol({
    color: [226, 119, 40],
    size: 8,
  }),
});

何时使用自动类型转换

在以下情况中使用带有 type 属性的普通对象：

• 配置较多的代码——渲染器、符号和弹出窗口通常是数据，而非行为
• 由 UI 驱动的配置——React 状态 → 普通对象 → SDK 属性，流程更简单
• 序列化和复用很重要时——配置可存储、比较差异、测试和复用
• 创建后更新属性时——在 React useEffect 中使用 layer.renderer = { ... } 很方便

// Use 'as const' or 'satisfies' to keep discriminated unions narrow
const renderer = {
  type: "simple",
  symbol: {
    type: "simple-marker",
    color: [226, 119, 40],
    size: 8,
  },
} as const;

// Or with satisfies for better type inference
const renderer = {
  type: "simple",
  symbol: {
    type: "simple-marker",
    color: [226, 119, 40],
    size: 8,
  },
} satisfies __esri.SimpleRendererProperties;

TypeScript 最佳实践

TypeScript 真正需要关注的是保持可辨识联合类型足够精确：

// ❌ BAD - type widens to string
const symbol = { type: "simple-marker", color: "red" };

// ✅ GOOD - type stays literal
const symbol = { type: "simple-marker", color: "red" } as const;

// ✅ GOOD - explicit type annotation
const symbol: __esri.SimpleMarkerSymbolProperties = {
  type: "simple-marker",
  color: "red",
};

推荐默认做法

• 配置使用自动类型转换（渲染器、符号、弹出窗口、标注）
• 行为使用显式类（需要方法或 instanceof 时）
• 使用 as const 或 satisfies，以在自动类型转换时保持类型安全

两种方法

1. Map Components（现代方式——推荐）

使用 <arcgis-map> 和 <arcgis-scene> 的 Web 组件方法。

2. Core API

使用 Map、MapView 和 SceneView 类的传统 JavaScript 方法。

CDN 设置

Map Components 方法

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>ArcGIS Map</title>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>
    
    <script
      type="module"
      src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"
    ></script>
    
    <script src="https://js.arcgis.com/5.0/"></script>
    
    <script
      type="module"
      src="https://js.arcgis.com/5.0/map-components/"
    ></script>
  </head>
  <body>
    <arcgis-map basemap="topo-vector" center="-118.24,34.05" zoom="12">
      <arcgis-zoom slot="top-left"></arcgis-zoom>
    </arcgis-map>
  </body>
</html>

Core API 方法

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>ArcGIS Map</title>
    <style>
      html,
      body,
      #viewDiv {
        height: 100%;
        margin: 0;
      }
    </style>
    
    <link
      rel="stylesheet"
      href="https://js.arcgis.com/5.0/esri/themes/light/main.css"
    />
    <script src="https://js.arcgis.com/5.0/"></script>
  </head>
  <body>
    <div id="viewDiv"></div>
    <script type="module">
      import Map from "@arcgis/core/Map.js";
      import MapView from "@arcgis/core/views/MapView.js";

      const map = new Map({ basemap: "topo-vector" });
      const view = new MapView({
        container: "viewDiv",
        map: map,
        center: [-118.24, 34.05], // [longitude, latitude]
        zoom: 12,
      });
    </script>
  </body>
</html>

2D 地图

Map Components

<arcgis-map basemap="topo-vector" center="-118.24,34.05" zoom="12">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-compass slot="top-left"></arcgis-compass>
  <arcgis-home slot="top-left"></arcgis-home>
  <arcgis-locate slot="top-left"></arcgis-locate>
</arcgis-map>

<script type="module">
  const mapElement = document.querySelector("arcgis-map");
  await mapElement.viewOnReady(); // Wait for view to be ready
  const view = mapElement.view; // Access the MapView
  const map = mapElement.map; // Access the Map
</script>

Core API

import Map from "@arcgis/core/Map.js";
import MapView from "@arcgis/core/views/MapView.js";

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

const view = new MapView({
  container: "viewDiv",
  map: map,
  center: [-118.24, 34.05],
  zoom: 12,
  // Optional constraints
  constraints: {
    minZoom: 5,
    maxZoom: 18,
    rotationEnabled: false,
  },
});

3D 场景

Map Components

<arcgis-scene basemap="topo-3d" ground="world-elevation">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-navigation-toggle slot="top-left"></arcgis-navigation-toggle>
</arcgis-scene>

<script type="module">
  const sceneElement = document.querySelector("arcgis-scene");
  await sceneElement.viewOnReady();
  const view = sceneElement.view; // SceneView
</script>

Core API

import Map from "@arcgis/core/Map.js";
import SceneView from "@arcgis/core/views/SceneView.js";

const map = new Map({
  basemap: "topo-3d",
  ground: "world-elevation",
});

const view = new SceneView({
  container: "viewDiv",
  map: map,
  camera: {
    position: {
      longitude: -118.24,
      latitude: 34.05,
      z: 25000, // altitude in meters
    },
    heading: 0, // compass direction
    tilt: 45, // 0 = straight down, 90 = horizon
  },
});

加载 WebMap 和 WebScene

WebMap（2D）

<arcgis-map item-id="f2e9b762544945f390ca4ac3671cfa72">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-map>

// Core API
import MapView from "@arcgis/core/views/MapView.js";
import WebMap from "@arcgis/core/WebMap.js";

const webmap = new WebMap({
  portalItem: { id: "f2e9b762544945f390ca4ac3671cfa72" },
});

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

WebScene（3D）

<arcgis-scene item-id="YOUR_WEBSCENE_ID">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-scene>

// Core API
import SceneView from "@arcgis/core/views/SceneView.js";
import WebScene from "@arcgis/core/WebScene.js";

const webscene = new WebScene({
  portalItem: { id: "YOUR_WEBSCENE_ID" },
});

const view = new SceneView({
  map: webscene,
  container: "viewDiv",
});

导航组件

组件	用途
arcgis-zoom	放大/缩小按钮
arcgis-compass	方向指示器，点击可重置为朝北
arcgis-home	返回初始范围
arcgis-locate	查找用户的位置
arcgis-navigation-toggle	在平移/旋转模式之间切换（3D）
arcgis-fullscreen	切换全屏模式
arcgis-scale-bar	显示地图比例尺

插槽位置

<arcgis-map basemap="streets-vector">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-home slot="top-left"></arcgis-home>
  <arcgis-search slot="top-right"></arcgis-search>
  <arcgis-legend slot="bottom-left"></arcgis-legend>
  <arcgis-scale-bar slot="bottom-right"></arcgis-scale-bar>
</arcgis-map>

可用插槽：top-left、top-right、bottom-left、bottom-right、top-start、top-end、bottom-start、bottom-end

组件属性

<arcgis-map> / <arcgis-scene> 组件除了 basemap、center、zoom 之外，还公开了许多声明式属性。以下是一些重要属性：

属性	类型	用途
item-id	string	从 ArcGIS Online 或 Enterprise 加载 WebMap/WebScene
rotation	number	地图旋转角度
scale	number	初始比例尺（例如，50000 表示 1:50,000）
extent	Extent (autocast)	初始可见范围
viewpoint	Viewpoint (autocast)	组合中心点、比例尺和旋转角度
spatial-reference	SpatialReference	坐标系（WKID）
time-extent	TimeExtent	时间感知图层的时间过滤器
animations-disabled	boolean	禁用所有 goTo 动画
popup-disabled	boolean	禁用点击时自动弹出的弹出窗口
popup-component-enabled	boolean	使用新的 Popup 组件（测试版）代替微件
auto-destroy-disabled	boolean	卸载时保持视图存活 — 对 React 严格模式和 SPA 路由更改至关重要
attribution-mode	"dark" | "light"	署名文本主题
hide-attribution	boolean	隐藏署名（请先查看 SDK 许可条款）

部分属性只能通过 JavaScript 设置（不能作为属性使用）：

属性	类型	用途
padding	ViewPadding	当侧边面板遮挡部分地图时，偏移 UI 逻辑区域
theme	Theme	浅色 / 深色渲染主题
background	ColorBackground	非平铺区域的背景颜色
graphics	Collection	视图级图形，与任何图层无关
highlights	Collection	最多 6 组要素高亮选项
analyses	Collection	3D 分析（视线分析、可视域分析）— 仅限 SceneView
aria	ARIAProperties	无障碍标签和描述

<arcgis-map
  auto-destroy-disabled
  basemap="topo-vector"
  center="-118.24,34.05"
  zoom="12"
></arcgis-map>

// Layout: offset the UI when a 320px left sidebar covers part of the map
const mapElement = document.querySelector("arcgis-map");
await mapElement.viewOnReady();
mapElement.padding = { left: 320 };

地图属性

属性	类型	描述
basemap	string or Basemap	地图的底图层
ground	string or Ground	地表属性（高程）
layers	Collection	操作图层
tables	Collection	非空间表
allLayers	Collection (readonly)	展平后的图层集合
allTables	Collection (readonly)	展平后的表集合
editableLayers	Collection (readonly)	支持编辑的图层
focusAreas	Collection (readonly)	地图的焦点区域

地图方法

方法	返回值	用途
add(layer, index?)	void	添加图层，可指定索引
addMany(layers, index?)	void	一次调用添加多个图层
remove(layer)	Layer	移除单个图层
removeMany(layers)	Layer[]	移除多个图层
removeAll()	Layer[]	移除所有操作图层
reorder(layer, index?)	Layer	更改图层绘制顺序
findLayerById(id)	Layer	根据图层的 id 属性查找图层
findTableById(id)	Layer	根据表的 id 属性查找表
destroy()	void	释放地图及其图层、底图和地表

// Add at a specific index (below existing layers)
map.add(baseLayer, 0);

// Batch add for initial setup
map.addMany([featureLayer, graphicsLayer, imageryLayer]);

// Reorder — move a layer to index 2
map.reorder(roadsLayer, 2);

// Lookup by ID (requires `id` to be set on the layer at creation)
const roads = map.findLayerById("roads");
if (roads) roads.visible = false;

模式： 单个 Map 实例可以同时由 MapView（2D）和 SceneView（3D）共享。用户交互发生在视图上，而不是地图上，因此，同一地图上的两个视图会保持图层同步，同时分别维护各自的相机和范围状态。

视图配置

设置初始范围

// By center and zoom
const view = new MapView({
  container: "viewDiv",
  map: map,
  center: [-118.24, 34.05],
  zoom: 12,
});

// By scale
const view = new MapView({
  container: "viewDiv",
  map: map,
  center: [-118.24, 34.05],
  scale: 50000, // 1:50,000
});

// By extent
const view = new MapView({
  container: "viewDiv",
  map: map,
  extent: {
    xmin: -118.5,
    ymin: 33.8,
    xmax: -117.9,
    ymax: 34.3,
    spatialReference: { wkid: 4326 },
  },
});

程序化导航

// Go to location
await view.goTo({
  center: [-118.24, 34.05],
  zoom: 15,
});

// Animated navigation
await view.goTo(
  { center: [-118.24, 34.05], zoom: 15 },
  { duration: 2000, easing: "ease-in-out" },
);

// Go to extent
await view.goTo(layer.fullExtent);

// Go to features
await view.goTo(featureSet.features);

视图约束

// Constrain zoom levels
view.constraints = {
  minZoom: 5,
  maxZoom: 18,
};

// Constrain to area
view.constraints = {
  geometry: layer.fullExtent,
  minScale: 500000,
};

// Disable rotation
view.constraints = {
  rotationEnabled: false,
};

视图状态属性

属性	类型	描述
ready	boolean	视图是否已完全初始化
updating	boolean	是否有任何图层或视图正在更新
stationary	boolean	没有正在进行导航时为 True
interacting	boolean	用户正在交互（平移/缩放）时为 True
suspended	boolean	视图不可见时为 True
focused	boolean	视图具有键盘焦点时为 True
resolution	number	每像素对应的地图单位数

事件处理

组件事件

Map Components 会在 <arcgis-map> / <arcgis-scene> 元素本身上触发 DOM 事件，事件名前缀为 arcgisView。这些事件与视图事件相对应，但可以通过元素上的 addEventListener 处理，甚至在视图就绪之前也可以处理。

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

// Alternative to awaiting viewOnReady()
mapElement.addEventListener("arcgisViewReadyChange", () => {
  if (mapElement.ready) {
    const view = mapElement.view;
    const map = mapElement.map;
    // Safe to use view and map here
  }
});

如何选择：

• 元素上的组件事件——声明式、便于与框架配合，并且在视图就绪之前即可使用。适用于需要 DOM 风格事件监听器的 React/Vue 模式。
• 通过 view.on(...) 监听的视图事件——命令式，会返回一个用于清理的句柄，且与 Core API 代码的工作方式一致。

大多数视图事件都有对应的 arcgisView* 组件事件。完整列表请参阅 arcgis-map 组件参考。

视图事件

// View ready
view.when(() => {
  console.log("View is ready");
});

// Click event
view.on("click", (event) => {
  console.log("Clicked at:", event.mapPoint);
});

// Pointer move
view.on("pointer-move", (event) => {
  const point = view.toMap(event);
  console.log("Mouse at:", point.longitude, point.latitude);
});

// Hit test (identify features under cursor)
view.on("click", async (event) => {
  const response = await view.hitTest(event);
  if (response.results.length > 0) {
    const graphic = response.results[0].graphic;
    console.log("Clicked feature:", graphic.attributes);
  }
});

// Extent change (using reactiveUtils)
import * as reactiveUtils from "@arcgis/core/core/reactiveUtils.js";

reactiveUtils.watch(
  () => view.extent,
  (extent) => console.log("Extent changed:", extent),
);

// Stationary (after pan/zoom completes)
reactiveUtils.watch(
  () => view.stationary,
  (isStationary) => {
    if (isStationary) {
      console.log("Navigation complete");
    }
  },
);

View 事件参考

事件	描述
click	用户点击视图
double-click	用户双击视图
immediate-click	点击后立即触发（没有双击延迟）
pointer-move	鼠标／触控指针在视图上移动
pointer-down / pointer-up	指针按下／释放
pointer-enter / pointer-leave	指针进入／离开视图
key-down / key-up	视图获得焦点时触发的键盘事件
drag	用户在视图上拖动（平移）
hold	用户在视图上按住指针
mouse-wheel	鼠标滚轮滚动
resize	视图容器大小改变
focus / blur	视图获得／失去键盘焦点
layerview-create	创建图层视图
layerview-destroy	销毁图层视图

常用底图

底图 ID	描述
streets-vector	街道地图
topo-vector	地形图
satellite	卫星影像
hybrid	带标注的卫星影像
dark-gray-vector	深灰色画布
gray-vector	浅灰色画布
osm	OpenStreetMap
topo-3d	3D 地形图（SceneView）

行星可视化（火星）

火星场景

<arcgis-scene>
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-navigation-toggle slot="top-left"></arcgis-navigation-toggle>
</arcgis-scene>

<script type="module">
  import ElevationLayer from "@arcgis/core/layers/ElevationLayer.js";
  import TileLayer from "@arcgis/core/layers/TileLayer.js";

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

  // Set Mars spatial reference
  viewElement.spatialReference = { wkid: 104971 }; // Mars 2000

  // Configure camera for Mars
  viewElement.camera = {
    position: {
      x: 27.63423,
      y: -6.34466,
      z: 1281525,
      spatialReference: { wkid: 104971 },
    },
    heading: 332,
    tilt: 37,
  };

  await viewElement.viewOnReady();

  // Mars elevation
  const marsElevation = new ElevationLayer({
    url: "https://astro.arcgis.com/arcgis/rest/services/OnMars/MDEM200M/ImageServer",
  });
  viewElement.ground = { layers: [marsElevation] };

  // Mars imagery
  const marsImagery = new TileLayer({
    url: "https://astro.arcgis.com/arcgis/rest/services/OnMars/MDIM/MapServer",
    title: "Mars Imagery",
  });
  viewElement.map.add(marsImagery);
</script>

概览地图（同步视图）

带场景的概览地图

<arcgis-scene basemap="hybrid" ground="world-elevation">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  
  <arcgis-map
    basemap="topo-vector"
    id="overviewDiv"
    slot="top-right"
  ></arcgis-map>
</arcgis-scene>

<style>
  #overviewDiv {
    width: 300px;
    height: 200px;
    border: 1px solid black;
  }
</style>

<script type="module">
  import Graphic from "@arcgis/core/Graphic.js";
  import * as reactiveUtils from "@arcgis/core/core/reactiveUtils.js";

  const sceneElement = document.querySelector("arcgis-scene");
  const overviewElement = document.querySelector("arcgis-map");

  await sceneElement.viewOnReady();
  await overviewElement.viewOnReady();

  // Disable rotation on overview
  overviewElement.constraints.rotationEnabled = false;
  overviewElement.view.ui.components = [];

  // Add visible area graphic
  const visibleAreaGraphic = new Graphic({
    symbol: {
      type: "simple-fill",
      color: [0, 0, 0, 0.5],
      outline: null,
    },
  });
  overviewElement.graphics.add(visibleAreaGraphic);

  // Sync overview with main scene
  reactiveUtils.watch(
    () => sceneElement.visibleArea,
    async (visibleArea) => {
      visibleAreaGraphic.geometry = visibleArea;
      await overviewElement.goTo(visibleArea);
    },
    { initial: true },
  );
</script>

参考示例

• intro-mapview - MapView 的基本设置和配置
• intro-sceneview - 用于 3D 的 SceneView 基本设置
• webmap-basic - 从门户加载 WebMap
• watch-for-changes-reactiveutils - 使用 reactiveUtils 监视响应式属性
• overview-map - 创建概览／插图地图

相关技能

• 有关向地图添加数据图层，请参阅 arcgis-layers。
• 有关项目设置和脚手架，请参阅 arcgis-starter-app。
• 有关 reactiveUtils 和 promiseUtils 的详细信息，请参阅 arcgis-core-utilities。
• 有关命中测试、弹出窗口和用户交互，请参阅 arcgis-interaction。

常见问题

1. Core API 缺少 CSS：Core API 需要 main.css，才能正确渲染微件和弹出窗口。

   
   <script type="module">
     import MapView from "@arcgis/core/views/MapView.js";
     import Map from "@arcgis/core/Map.js";
     const view = new MapView({
       container: "viewDiv",
       map: new Map({ basemap: "topo-vector" }),
     });
   </script>
   

   
   <link
     rel="stylesheet"
     href="https://js.arcgis.com/5.0/esri/themes/light/main.css"
   />
   <script type="module">
     import MapView from "@arcgis/core/views/MapView.js";
     import Map from "@arcgis/core/Map.js";
     const view = new MapView({
       container: "viewDiv",
       map: new Map({ basemap: "topo-vector" }),
     });
   </script>
   

   影响： 地图本身可以渲染，但微件（缩放、图例、搜索）和弹出窗口没有样式或完全无法正常显示。布局会崩溃，控件也无法使用。

2. 未等待 viewOnReady()：视图准备就绪后，才能访问视图属性。

   // Anti-pattern: accessing view before it is ready
   const mapElement = document.querySelector("arcgis-map");
   const view = mapElement.view; // undefined - view is not ready yet
   view.goTo({ center: [-118, 34] }); // TypeError: Cannot read properties of undefined
   

   // Correct: wait for the view to be ready
   const mapElement = document.querySelector("arcgis-map");
   await mapElement.viewOnReady();
   const view = mapElement.view; // MapView instance, safe to use
   view.goTo({ center: [-118, 34] });
   

   影响： 组件初始化前，view 为 null 或 undefined，访问任何属性或调用任何方法都会导致运行时错误。

3. 坐标顺序：ArcGIS 使用 [longitude, latitude]，而不是 [latitude, longitude]。

   // Anti-pattern: lat/lng order (Google Maps convention)
   const view = new MapView({
     center: [34.05, -118.24], // lat first, lng second - WRONG
     zoom: 12,
   });
   

   // Correct: lng/lat order (ArcGIS convention)
   const view = new MapView({
     center: [-118.24, 34.05], // lng first, lat second
     zoom: 12,
   });
   

   影响： 地图会定位到错误位置，通常是海洋中央或另一片大陆，而且不会显示任何错误消息来提示这一问题。

4. viewDiv 缺少高度：确保容器有高度：

   html,
   body,
   #viewDiv {
     height: 100%;
     margin: 0;
   }
   

5. 脚本类型：使用 type="module" 以支持 async/await：

   <script type="module">
     // async/await works here
   </script>
   

6. 图层只能属于一个 Map：将图层添加到第二个 Map 时，会从第一个 Map 中静默移除。

   // Anti-pattern: sharing a layer between two maps expecting both to display it
   const layer = new FeatureLayer({ url: "..." });
   const map1 = new Map({ layers: [layer] });
   const map2 = new Map({ layers: [layer] }); // silently removes layer from map1
   

   // Correct: create two instances against the same data source
   const layer1 = new FeatureLayer({ url: "..." });
   const layer2 = new FeatureLayer({ url: "..." });
   const map1 = new Map({ layers: [layer1] });
   const map2 = new Map({ layers: [layer2] });
   

   影响： 图层只会显示在最近创建的地图中，不会出现错误或警告。在使用独立地图实例切换 2D 和 3D，而不是让两个视图共享同一个地图时，这种情况很常见。