arcgis-embeddable-maps

ArcGIS 嵌入式地图

使用此技能可通过少量代码，将轻量、自包含的地图嵌入网页。@arcgis/embeddable-components 包提供了 arcgis-embedded-map Web 组件——单个元素即可封装 WebMap 查看器，以及可选的内置 UI 控件（图例、书签、底图库、全屏）。这是 5.0 中新增的组件包，在 4.x 中没有对应组件。

何时使用 arcgis-embedded-map，何时使用 arcgis-map： 在博客、仪表板和报告等场景中，如果只需简单的只读地图嵌入，不需要自定义微件、编辑功能或以编程方式控制地图，请使用 arcgis-embedded-map。对于功能完整的应用程序，请使用 arcgis-map（参见 arcgis-core-maps）。

导入方式

CDN（无需构建工具）

<script src="https://js.arcgis.com/5.0/"></script>

<script
  type="module"
  src="https://js.arcgis.com/5.0/embeddable-components/"
></script>

直接导入 ESM（构建工具）

import "@arcgis/embeddable-components/components/arcgis-embedded-map";

arcgis-embedded-map 组件

属性

属性	属性名	类型	默认值	说明
itemId	item-id	string	-	必需。 WebMap 的 Portal 项目 ID
portalUrl	portal-url	string	"https://www.arcgis.com"	Portal URL（ArcGIS Online 或 Enterprise）
apiKey	api-key	string	-	用于访问资源的 API 密钥
center	center	number[] | Point	-	视图中心 [longitude, latitude]
zoom	zoom	number	-	缩放级别
scale	scale	string	-	中心处的地图比例尺
extent	-	Extent	-	可见地图范围（通过 JS 设置）
webMap	-	WebMap	-	WebMap 实例（通过 JS 设置，可替代 itemId）
theme	theme	string	"light"	组件主题："light" 或 "dark"

UI 控件属性

属性	属性名	类型	默认值	说明
headingEnabled	heading-enabled	boolean	false	显示 WebMap 标题
legendEnabled	legend-enabled	boolean	false	显示图例面板
bookmarksEnabled	bookmarks-enabled	boolean	false	显示书签面板
basemapGalleryEnabled	basemap-gallery-enabled	boolean	false	显示底图库面板
informationEnabled	information-enabled	boolean	false	显示信息面板
shareEnabled	share-enabled	boolean	false	显示在 Map Viewer 中打开的按钮
fullscreenDisabled	fullscreen-disabled	boolean	false	禁用全屏按钮
scrollEnabled	scroll-enabled	boolean	true	启用鼠标滚轮缩放
timeZoneLabelEnabled	time-zone-label-enabled	boolean	false	显示时区标签

方法

方法	返回值	说明
componentOnReady()	Promise<void>	组件完全加载后解析

基本用法

最简嵌入

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  style="width: 800px; height: 600px;"
>
</arcgis-embedded-map>

嵌入并显示所有界面控件

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  heading-enabled
  legend-enabled
  bookmarks-enabled
  basemap-gallery-enabled
  information-enabled
  share-enabled
  style="width: 100%; height: 500px;"
>
</arcgis-embedded-map>

深色主题

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  theme="dark"
  legend-enabled
  style="width: 800px; height: 600px;"
>
</arcgis-embedded-map>

自定义中心点和缩放级别

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  center="-118.24,34.05"
  zoom="12"
  style="width: 800px; height: 600px;"
>
</arcgis-embedded-map>

禁用滚动缩放（适用于内嵌内容）

<arcgis-embedded-map
  item-id="f2e9b762544945f390ca4ac3671cfa72"
  scroll-enabled="false"
  style="width: 100%; height: 400px;"
>
</arcgis-embedded-map>

使用 API 密钥

<arcgis-embedded-map
  item-id="YOUR_ITEM_ID"
  api-key="YOUR_API_KEY"
  portal-url="https://www.arcgis.com"
  legend-enabled
  style="width: 800px; height: 600px;"
>
</arcgis-embedded-map>

企业门户

<arcgis-embedded-map
  item-id="YOUR_ENTERPRISE_ITEM_ID"
  portal-url="https://your-enterprise.com/portal"
  heading-enabled
  legend-enabled
  style="width: 800px; height: 600px;"
>
</arcgis-embedded-map>

CDN 完整示例

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Embedded Map</title>
    <script src="https://js.arcgis.com/5.0/"></script>
    <script
      type="module"
      src="https://js.arcgis.com/5.0/embeddable-components/"
    ></script>
    <style>
      body {
        font-family: sans-serif;
        max-width: 900px;
        margin: 0 auto;
        padding: 20px;
      }
      arcgis-embedded-map {
        width: 100%;
        height: 500px;
        display: block;
        margin: 20px 0;
      }
    </style>
  </head>
  <body>
    <h1>City Demographics</h1>
    <p>Explore population data across the region.</p>
    <arcgis-embedded-map
      item-id="f2e9b762544945f390ca4ac3671cfa72"
      heading-enabled
      legend-enabled
      bookmarks-enabled
      theme="light"
    >
    </arcgis-embedded-map>
    <p>Data source: US Census Bureau</p>
  </body>
</html>

以编程方式配置

通过 JavaScript 设置范围

const embeddedMap = document.querySelector("arcgis-embedded-map");
await embeddedMap.componentOnReady();

embeddedMap.extent = {
  xmin: -118.5,
  ymin: 33.8,
  xmax: -117.9,
  ymax: 34.3,
  spatialReference: { wkid: 4326 },
};

使用 WebMap 实例

const WebMap = await $arcgis.import("@arcgis/core/WebMap.js");

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

const embeddedMap = document.querySelector("arcgis-embedded-map");
embeddedMap.webMap = webMap;

使用 CSS 变量设置主题

该组件支持 Calcite Design System CSS 变量：

arcgis-embedded-map {
  --calcite-color-brand: #007ac2;
  --calcite-color-foreground-1: #ffffff;
  --calcite-color-text-1: #151515;
  --calcite-color-border-1: #cacaca;
}

常见问题

1. 缺少 item-id：该组件需要 WebMap 门户项目 ID。

   
   <arcgis-embedded-map style="width: 800px; height: 600px;">
   </arcgis-embedded-map>
   

   
   <arcgis-embedded-map
     item-id="f2e9b762544945f390ca4ac3671cfa72"
     style="width: 800px; height: 600px;"
   >
   </arcgis-embedded-map>
   

   影响： 组件会渲染出一个没有地图的空容器。

2. 缺少 embeddable-components 脚本：必须单独加载该软件包。

   
   <script src="https://js.arcgis.com/5.0/"></script>
   <arcgis-embedded-map item-id="abc123"></arcgis-embedded-map>
   

   
   <script src="https://js.arcgis.com/5.0/"></script>
   <script
     type="module"
     src="https://js.arcgis.com/5.0/embeddable-components/"
   ></script>
   <arcgis-embedded-map item-id="abc123"></arcgis-embedded-map>
   

   影响： 该元素无法识别，渲染结果为空。

3. 未明确指定尺寸：嵌入式地图需要宽度和高度才能正常显示。

   
   <arcgis-embedded-map item-id="abc123"></arcgis-embedded-map>
   

   
   <arcgis-embedded-map
     item-id="abc123"
     style="width: 100%; height: 500px; display: block;"
   >
   </arcgis-embedded-map>
   

   影响： 地图会以零高度渲染，在页面上不可见。

4. 将 arcgis-embedded-map 用于交互式应用：该组件专为简单嵌入而设计，不支持自定义小组件、编辑、图层操作或以编程方式控制视图。完整应用请使用 @arcgis/map-components 中的 arcgis-map。

   影响： 尝试添加小组件或编辑要素时会悄无声息地失败。

5. 长页面中的滚动缩放：嵌入式地图与可滚动内容内嵌时，滚动缩放可能会困住用户。禁用此功能可改善用户体验。

   <arcgis-embedded-map
     item-id="abc123"
     scroll-enabled="false"
     style="width: 100%; height: 400px;"
   >
   </arcgis-embedded-map>
   

   影响： 用户想滚动页面时，却会被困在地图缩放操作中。

参考示例

• 搜索展示轻量级 WebMap 嵌入的地图示例。

相关技能

• 查看 arcgis-core-maps，了解如何使用 arcgis-map 和 arcgis-scene 构建功能完整的地图应用。
• 查看 arcgis-starter-app，了解项目脚手架和 CDN 设置。
• 查看 arcgis-authentication，了解 API 密钥和门户身份验证。