移行のヒント

出典：ArcGIS Maps SDK for JavaScript - Tips for migrating

移行のヒント

バージョン 4.30 で ArcGIS Maps SDK for JavaScript に Web コンポーネントが追加されました。これらのコンポーネントはカスタム HTML 要素として構築されているため、最新のブラウザーで標準的に使用でき、特定のフレームワークに依存しません。SDK では、コンポーネントによって API の定型コードの大部分をカプセル化することで、一般的なコーディングパターンを簡素化します。

アプリケーションは、Map コンポーネントや Scene コンポーネントといったコンポーネント（カスタム HTML 要素）を使って宣言的に定義できるようになりました。これにより、ビューやコンテナーの設定、モジュールのインポート作業が軽減されます。

<head>
  <!-- ArcGIS Maps SDK for JavaScript のマップ コンポーネントおよびその他のコンポーネントのロード -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>
</head>
<body>
  <arcgis-map basemap="topo-vector" zoom="4" center="15, 65"></arcgis-map>
</body>

Getting started

Web コンポーネントが初めての方、またはこのトピックのブラッシュアップが必要な方には、役立つさまざまなリソースがあります。

すぐにコーディングを始めたい場合は、コンポーネントのチュートリアルや GitHub 上のコードサンプルを参照してください。
属性やプロパティの扱い方、変更の監視などに関する詳細ついては、プログラミングパターンのガイドトピックをお読みください。
プロパティ、メソッド、イベントを確認するには、リファレンスページをご覧ください。
JavaScript Maps SDK コンポーネントでアプリを構築するブログ (Build GIS Web Apps with the JavaScript Maps SDK components) をご覧ください。
MDN ウェブコンポーネントリソースページをご覧ください。

基本的な実装

ArcGIS Maps SDK for JavaScript を使ってアプリケーションを実装する際、コンポーネントを使用すると反復的な定型コードを減らすことができます。たとえば、コア API の Map クラスと MapView クラスを使ってシンプルな地図を作成する従来のパターンは次のとおりです。

const [Map, MapView] = await $arcgis.import([
  "@arcgis/core/Map.js",
  "@arcgis/core/views/MapView.js",
]);
const map = new Map({
  basemap: "streets-vector",
});

const view = new MapView({
  container: "viewDiv",
  map: map,
  zoom: 14,
  center: [8.5, 47.37],
});

以下は、Map コンポーネントを使用して HTML で記述した同等のコードです。これにより、一般的なユースケースにおいて、ビューを手動で作成したり、コンテナー要素を管理したり、コアのビューモジュールをインポートしたりする必要がなくなります。このスニペットでは、コンポーネントに対して直接属性を設定する方法を示しています。

<arcgis-map zoom="14" center="8.5,47.37" basemap="streets-vector"></arcgis-map>

コンポーネントへの移行により、ビューや UI の作成、配置方法は変わりますが、コアとなる ArcGIS Maps SDK for JavaScript が置き換えられるわけではありません。マップ、レイヤー、レンダラーそしてほとんどのビューロジックは従来と同じ方法で動作します。

slots（スロット）を使用した UI 要素の宣言的な配置

コンポーネントベースのパターンでは view.ui.add がスロットに置き換えられ、コンポーネントやカスタム HTML などの UI 要素をマークアップ内で宣言的に配置し、DOM の一部として管理できるようになります。レイアウトやスタイリングは標準的な HTML と CSS の挙動に従うため、SDK 固有の構造やインポートを必要とせず、より柔軟なデザインを実現できます。

<arcgis-map zoom="14" center="8.5,47.37" basemap="streets-vector">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-basemap-toggle slot="bottom-right" next-basemap="topo"></arcgis-basemap-toggle>
  <div id="my-custom-ui-content" slot="bottom-right"></div>
</arcgis-map>

このアプローチにより、UI の配置をマークアップと密接に保ち、命令的な UI コードで一般的に発生するビューのライフサイクルに関するタイミングの問題を回避できます。

コア API を引き続き使用するケース

コンポーネントはアプリケーションのセットアップや UI の構築を簡素化しますが、ArcGIS Maps SDK for JavaScript のコア API の代替となるものではありません。カスタムレイヤーのロジック、レンダラー、クエリー、複雑なビュー操作などの高度なワークフローでは、コンポーネントと並行してコアモジュールを引き続き利用できます。

カスタム機能の実装

Map コンポーネントがロードされた後に実行される機能を実装するには、HTML 要素をクエリで取得し、その要素のオブジェクトを使用してイベントリスナーを設定したり、プロパティを取得または設定したり、コンポーネントに直接メソッドを実装したりします。

以下のスニペットでは、いくつかのプロパティを設定し、ビューの準備が整うのを待ってからマップの itemId をコンソールに出力しています。このシンプルな例では、モジュールのインポートは不要です。

index.html

<arcgis-map></arcgis-map>
<script type="module" src="/main.js"></script>

main.js

// HTML 要素を取得
const viewElement = document.querySelector("arcgis-map");

// マップのプロパティを設定
viewElement.zoom = 14;
viewElement.center = [8.5, 47.37];
viewElement.basemap = "streets-vector";

// ビューの準備完了まで待機
await viewElement.viewOnReady();

// マップのアイテム ID をログ出力
console.log(viewElement.itemId)

コンポーネントは、プロパティを通じてプログラム的に構成することも、カスタム要素内で属性を使って直接設定することも可能です。プロパティの更新、イベントの監視が可能で、viewOnReady() のようなライフサイクルメソッドが公開されているため、アプリケーションのロジックフローを制御できます。

コンポーネントによってアプリケーションのセットアップは簡素化されますが、ほとんどのプロジェクトでは、上記のようにカスタム動作をサポートするためのコア API を引き続き使用できます。必要に応じてビューを構成したり、追加機能を統合したりするために、$arcgis.import() を使ってモジュールを動的にインポートすることが可能です。

必要に応じて、アプリケーションは CDN とバニラの HTML / JavaScript を使って構築することも、npm を使って JavaScript のバンドラーやフレームワークでローカルに構築することも可能です。

詳細は開発の手順をご覧ください。

移行計画：ウィジェットからコンポーネントへ