出典：ArcGIS Maps SDK for JavaScript - Get Started
ArcGIS Maps SDK for JavaScript には、コア API と、API の機能をすぐに使用できる UI 要素にカプセル化する Web コンポーネント ライブラリーのセットが含まれています。アプリケーションのニーズに応じて、4 つのコンポーネント ライブラリー（Map、Coding、Charts、Embeddable）のどれからでもコンポーネントを使用することができます。また、SDK は Esri の Calcite Design System と統合され、一貫性のある利用しやすいユーザー エクスペリエンスを提供します。Calcite は、Web コンポーネント、アイコン、配色、デザイン パターンの豊富なライブラリーを含む、完全な UI ツールキットを提供します。
JavaScript Maps SDK の使い始めは、目的や要件によって異なります。ローカル パッケージをインストールせずにバニラ JavaScript と HTML アプリを構築したい場合は、CDN を利用することができます。より構造化された、またはスケーラブルな Web アプリケーション、特にフロントエンド フレームワークやビルド ツールを使用する場合は、npm で SDK をインストールすることを検討してください。
コード例：React、Angular、Vite など、様々なサンプルについては Esri/jsapi-resources のリポジトリーを参照してください。
JavaScript Maps SDK は、ArcGIS CDN を使用して、バニラ JavaScript および HTML アプリケーションに簡単に統合できます。このアプローチでは、最適化されたクラウド キャッシングを活用することで、ローカル ビルドの必要性をなくし、SDK の最新バージョンへの更新を容易にします。
はじめに、基本的な HTML ファイルの <head> セクションに、必要なライブラリー スクリプトと CSS リンク タグを以下に示す順番ですべて含めます。
index.html
<!-- Calcite Design System のロード -->
<script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>
<!-- ArcGIS Maps SDK for JavaScript コア API のロード -->
<script src="https://js.arcgis.com/4.34/"></script>
<!-- ArcGIS Maps SDK for JavaScript のマップ コンポーネントおよびその他のコンポーネントのロード -->
<script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>
まだコンポーネントに移行しておらず、ウィジェットを使用している場合は、コンポーネントへの移行をご検討ください。ウィジェットの使用や、プログラムによる新しい MapView/SceneView の初期化には、引き続きコア API スタイルシートが必要です。
index.html
<link rel="stylesheet" href="https://js.arcgis.com/4.34/esri/themes/light/main.css" />
カスタム CSS を追加して、コンポーネントがアプリケーションで表示されるようにします。これは、CDN から ArcGIS スタイルシートとライブラリーをインポートした後、<head> セクションの最後の項目にする必要があります。
<style>
html,
body {
height: 100%;
margin: 0;
}
</style>
Calcite モードでライトまたはダークのテーマを選択してください。
2D マップ コンポーネント (または 3D シーン コンポーネント) を HTML の <body> に追加し、ArcGIS Online または ArcGIS Enterprise ポータルの WebMap を使用している場合は、オプションの item-id を割り当てます。マップまたはシーンのスロットを使用して、マップやシーン内でズームなどの他のコンポーネントを配置します。
詳細については、Programming Patterns、チュートリアル Display a web map、およびサンプル Create a 2D map を参照してください。
<!-- ベースマップ、範囲、ズームレベルをプログラムで設定する必要はありません -->
<!-- この情報はすべて WebMap から得られています -->
<arcgis-map item-id="02b37471d5d84cacbebcccd785460e94">
<arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-map>
次に、HTML の <body> の下にある <script> タグで、コア API を使用してプロパティを設定や、変更を監視、カスタム JavaScript ロジックを追加することができます。スクリプトが <script type="module"> としてマークされていることを確認してください。
コア API からのモジュールは、グローバルな $arcgis.import() メソッドで読み込むことができます。このメソッドは、モジュール パスまたはモジュール パスの配列を受け取り、要求されたモジュールを解決するプロミスを返します。モジュール識別子は、各 API リファレンス ページの上部にあります。 参考までに Graphic をご覧ください。
$arcgis.import() メソッドは、CDN 経由で使用する場合の ArcGIS Maps SDK for JavaScript 専用であり、標準の ES モジュール システムのネイティブ機能ではありません。
以下のコードは、マップのビューの準備ができるのを待ちます。ビューの準備が整えば、さらに機能を追加することができます。 index.html
<script type="module">
const Graphic = await $arcgis.import("@arcgis/core/Graphic.js");
const viewElement = document.querySelector("arcgis-map");
// ビューの準備が整うまで追加機能の実装を待つ
await viewElement.viewOnReady();
// ...
// グラフィックを作成し、それにジオメトリーとシンボルを追加する
const pointGraphic = new Graphic({
geometry: point, // ポイントのジオメトリー
symbol: markerSymbol // ポイントを描画するシンボル
})
viewElement.graphics.add(pointGraphic);
</script>
Vite のような最新のビルド ツールや、React、Angular、Vue のような JavaScript フレームワークの場合は、npm のようなパッケージ マネージャー経由で JavaScript Maps SDK をインストールすることをお勧めします。
node.js と npm の最新の長期サポート（LTS）バージョンを使用していることを確認してください。次に、好みのビルド ツールやフレームワークの推奨テンプレートを使ってプロジェクトの大枠を作成します。モジュール バンドラーとローカル Web サーバーを含むクライアント サイド ビルド ツールである Vite には、多くのテンプレート プロジェクトが用意されています。
Yarn Plug’n’Play (PnP) は現在サポートされていません。
プロジェクトでマップ コンポーネントを使用するには、@arcgis/map-components パッケージとその依存関係をインストールします。
npm の場合
npm install @arcgis/map-components
yarn の場合
yarn add @arcgis/map-components @arcgis/core @esri/calcite-components
バージョン 4.34 以降、npm を使用したコンポーネントでは CSS が自動的に読み込まれます。これにはコンポーネントと Calcite 両方のスタイルシートが含まれます。
index.css
html,
body {
height: 100%;
margin: 0;
}
まだコンポーネントに移行しておらず、ウィジェットを使用している場合は、コンポーネントへの移行をご検討ください。ウィジェットの使用や、プログラムによる新しい MapView/SceneView の初期化には、引き続きコア API スタイルシートが必要です。
index.css
@import "@arcgis/core/assets/esri/themes/light/main.css";
アプリケーションをローカル環境でホストする必要がある場合、または CSS プラグインのないビルド ツールを使用している場合は、詳細についてローカル アセット ガイド トピックを参照してください。
Vite + vanilla JavaScript スターター プロジェクトの index.html ファイルに、2D マップ コンポーネント（または 3D シーン コンポーネント）を追加し、main.js ファイルを参照してください。各コンポーネントは、<div></div> のような他の HTML 要素と同様に、HTML タグを使用してアプリケーションに追加できるカスタム要素です。
<body>
<arcgis-map item-id="02b37471d5d84cacbebcccd785460e94">
<arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-map>
<script type="module" src="./main.js"></script>
</body>
最後に、main.js JavaScript ファイルで、マップ コンポーネントなど、必要な SDK のコンポーネントを個別にインポートします。
ブラウザーの CustomElementRegistry にコンポーネントを登録します。ブラウザーが <arcgis-map></arcgis-map> のようなカスタム要素の HTML タグに出会うと、要素のインスタンスを作成し、DOM に追加してその機能を有効にします。
main.js
import "./index.css";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";
import Graphic from "@arcgis/core/Graphic.js";
const viewElement = document.querySelector("arcgis-map");
// ビューの準備が整うまで追加機能の実装を待つ
viewElement.addEventListener("arcgisViewReadyChange", () => {
// ...
// グラフィックを作成し、それにジオメトリーとシンボルを追加する
const pointGraphic = new Graphic({
geometry: point, // ポイントのジオメトリー
symbol: markerSymbol // ポイントを描画するシンボル
});
viewElement.graphics.add(pointGraphic);
});
TypeScriptは、実行時ではなく開発時にエラーを特定する静的型チェックを提供する強力な言語です。これにより生産性が向上し、トラブルシューティングの時間が短縮されます。TypeScript の定義は、SDK が npm を使ってローカルにインストールされたときに提供される。TypeScript を JavaScript にコンパイルするには、tsconfig.json ファイルを作成して TypeScript コンパイラーを設定する必要がある。プロジェクトのインストール時に tsconfig.json ファイルが自動的に作成された場合は、すべての設定を見直してください。
コア API の TypeScript デコレーターを使用する場合、例えば Accessor サブクラスを作成するときやベース レイヤーを拡張するときには、後方互換性のために useDefineForClassFields フラグを false に設定する必要があるかもしれません。このフラグの詳細については、TSConfig Referenceを参照してください。
以下に tsconfig.json の最小例になります。 tsconfig.json
{
"$schema": "https://json.schemastore.org/tsconfig.json",
// コンパイル対象の `.ts` ファイルの配列。`"src/**/*"` のようなグローブ パターンも使用できます。
"include": ["src", "*.ts"],
"compilerOptions": {
// `true`の場合、`import x from 'xyz'` のような `import` 構文の使用を許可します。
"esModuleInterop": true,
// コンパイルに含めるライブラリー型定義を指定します。
"lib": ["DOM", "DOM.Iterable", "ES2023"],
// コンパイルに使用するモジュール システム。
// ここでは、トップレベル await と動的インポートを可能にするため、ES モジュール（ESNext）を対象としています。
"module": "ES2022",
// package.json の exports 条件を尊重します。
"moduleResolution": "Bundler",
// JSON ファイルからのインポートを許可する
"resolveJsonModule": true,
// これにより、サポートされる JavaScript 機能の最小バージョンが設定されます。
"target": "ES2023",
// ライブラリーから読み込む .d.ts ファイルではなく、
// 自身が記述した .ts ファイルのみをチェックすることでパフォーマンスを向上させます。
"skipLibCheck": true,
},
}
詳しくは TypeScript の Get Started ガイドをご覧ください。
コンポーネントとコア API の両方を使用する方法を示す完全な例については、SDK の TypeScript テンプレート プロジェクトを参照してください。これは Vite + TypeScript テンプレートを出発点としており、JavaScript サンプルを反映していますが、型安全性を提供するために TypeScript(.ts) で記述されています。
React 19 プロジェクトで JSX を使用して SDK を使用することは、通常の JavaScript と HTML のプロジェクトで SDK を使用することに似ています。主な違いは、JSX の構文と React のプログラミング パターンです。React のようなフレームワークで作業する場合、コンポーネントのライフサイクルとの統合性を高めるために、一般的にはメソッドを直接呼び出すよりもイベントを使用することが推奨されます。
index.jsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";
import Graphic from "@arcgis/core/Graphic.js";
function App() {
const handleViewReady = (event) => {
const viewElement = event.target;
// ...
// グラフィックを作成し、それにジオメトリーとシンボルを追加する
const pointGraphic = new Graphic({
geometry: point, // ポイントのジオメトリー
symbol: markerSymbol // ポイントを描画するシンボル
});
viewElement.graphics.add(pointGraphic);
};
return (
<arcgis-map item-id="02b37471d5d84cacbebcccd785460e94" onarcgisViewReadyChange={handleViewReady}>
<arcgis-zoom slot="top-left" />
</arcgis-map>
);
}
const root = createRoot(document.getElementById("root"));
root.render(
<StrictMode>
<App />
</StrictMode>,
);
コンポーネントとコア API の両方を使用する方法を示す完全な例については、SDK の React テンプレート プロジェクトを参照してください。
すでに React 19 プロジェクトで TypeScript を設定しており、TSX で Web コンポーネントを使用したい場合は、メインの .tsx ファイルまたは Vite の vite-env.d.ts ファイルの先頭に1行のコードを書くだけで可能です。これにより、イベント リスナーやプロパティなどに対する型安全性が向上します。
vite.env.d.ts
/// <reference types="@arcgis/map-components/types/react" />
React 18 を使用している場合は、@arcgis/map-components-react パッケージを確認してください。
SDK の Web コンポーネントは非 Angular 要素です。 これらを Angular コンポーネント内で使用するには、Angular の CUSTOM_ELEMENTS_SCHEMA を設定する必要があります。
app.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA, OnInit } from "@angular/core";
import "@arcgis/map-components/components/arcgis-map";
@Component({
selector: "app-root",
standalone: true,
imports: [RouterOutlet],
templateUrl: "./app.html",
schemas: [CUSTOM_ELEMENTS_SCHEMA], // ここにスキーマを設定
})
export class AppComponent {
arcgisViewReadyChange(event: CustomEvent) {
// ビューの準備が整いました。以下の追加機能を追加してください。
}
}
現在 Angular では、マップ コンポーネントの CSS はバンドルされますが、本番ビルドでは自動的に読み込まれません。CSS はプロジェクトのルート スタイルシートで明示的にインポートする必要があります。src/styles.css に以下を追加してください。
sytles.css
@import "@esri/calcite-components/calcite/calcite.css";
@import "@arcgis/map-components/main.css";
@import "@arcgis/coding-components/main.css";
一部のコンポーネントはフォント ファイル（.woff2）を読み込みます。これらのアセットが Angular でサポートされるようにするには、angular.json にローダー設定を追加してください：
"loader": { ".woff2": "file" }
詳細については、Angular のファイル拡張子ローダーのカスタマイズ ガイドを参照してください。
app.html の HTML インテリセンスについては、インテリセンスのドキュメントをご覧ください。Angular のようなフレームワークで作業する場合、コンポーネントのライフサイクルとの統合性を高めるために、一般的にはメソッドを直接呼び出すよりもイベントを使用することをお勧めします。
app.html
<arcgis-map
item-id="45b77c869ba14b6dbc2de43a817304a6"
(arcgisViewReadyChange)="arcgisViewReadyChange($event)"
>
<arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-map>
SDK の Angular テンプレート プロジェクトを参照すると、両方のコンポーネントとコア API の操作方法と CSS の設定方法を示す完全なサンプルが得られます。
アプリケーションで認証に ArcGIS Identities のみを使用している場合は、このセクションをスキップできます。詳しくは、セキュリティと認証のドキュメントを参照してください。
ベースマップ、ジオコーディング、ルーティングなどの ArcGIS サービスにアクセスするには、アクセス トークンが必要です。ポータルにアクセスし、特定のニーズに合わせてカスタム権限とリファラーを持つアクセス トークンを作成します。チュートリアルやサンプルの説明で必要な場合は、アクセストークンを含めてください。グローバル API キーだけでなく、特定のクラスでより細かい API キーを使用することもできます。
詳細については、以下のリンクをご参照ください。