arcgis-embeddable-maps

ArcGIS 埋め込み可能マップ

コードを最小限に抑えながら、軽量で自己完結型のマップを Web ページに埋め込む場合は、このスキルを使用します。@arcgis/embeddable-components パッケージは、WebMap ビューアーと、任意で組み込み UI コントロール（凡例、ブックマーク、ベースマップギャラリー、全画面表示）をまとめた単一の Web コンポーネント arcgis-embedded-map を提供します。これは 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 のポータルアイテム ID
portalUrl	portal-url	string	"https://www.arcgis.com"	ポータル 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>

すべての UI コントロールを含めた埋め込み

<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 キーとポータル認証を確認できます。