ArcGIS Developers 開発リソース集 > 技術 Tips 集 > ArcGIS Maps SDK for JavaScript > 開発の手順

開発の手順

出典：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 をインストールすることを検討してください。

コードの例：ArcGIS Maps SDK for JavaScript コア API とマップコンポーネントテンプレートプロジェクトをチェックして、すぐに始めまられます。

CDN

Vite

React

Angular

Vue

CDN

JavaScript Maps SDK は、ArcGIS CDN を使用して、バニラ JavaScript および HTML アプリケーションに簡単に統合できます。このアプローチでは、最適化されたクラウドキャッシングを活用することで、ローカルビルドの必要性をなくし、SDK の最新バージョンへの更新を容易にします。

セットアップ

はじめに、基本的なHTMLファイルの <head> セクションに、必要なライブラリースクリプトと CSS リンクタグを以下に示す順番ですべて含めます。

<!-- Load Calcite Design System -->
<script
  type="module"
  src="https://js.arcgis.com/calcite-components/3.2.1/calcite.esm.js"></script>

<!-- Load the JavaScript Maps SDK core API -->
<link rel="stylesheet" href="https://js.arcgis.com/4.33/esri/themes/light/main.css" />
<script src="https://js.arcgis.com/4.33/"></script>

<!-- Load the JavaScript Maps SDK Map components or other component packages -->
<script
  type="module"
  src="https://js.arcgis.com/4.33/map-components/"></script>

CSS の設定

カスタム CSS を追加して、コンポーネントがアプリケーションで表示されるようにします。これは、CDN から ArcGIS スタイルシートとライブラリーをインポートした後、<head> セクションの最後の項目にする必要があります。

お好みの CSS スタイルシートと Calcite モードを含めることで、ライトまたはダークのテーマを選択できます。

<style>
  html,
  body {
    height: 100%;
    margin: 0;
  }
</style>

レイアウトの作成

2D マップコンポーネント (または 3D シーンコンポーネント) を HTML の <body> に追加し、ArcGIS Online または ArcGIS Enterprise ポータルの WebMap を使用している場合は、オプションの item-id を割り当てます。

詳細については、Programming Patterns、チュートリアル Display a web map、およびサンプル Create a 2D map を参照してください。

<!-- There is no need to programmatically set the basemap, extent or zoom -->
<!-- All this information comes from the WebMap -->
<arcgis-map item-id="02b37471d5d84cacbebcccd785460e94">
  <arcgis-zoom position="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 モジュールシステムのネイティブ機能ではありません。

以下のコードは、マップのビューの準備ができるのを待ちます。ビューの準備が整えば、さらに機能を追加することができます。

<script type="module">
  const Graphic = await $arcgis.import("@arcgis/core/Graphic.js");
  const viewElement = document.querySelector("arcgis-map");
  // Wait for the view to be ready before adding additional functionality
  await viewElement.viewOnReady();

  ...

  // Create a graphic and add the geometry and symbol to it
  const pointGraphic = new Graphic({
    geometry: point, // A point geometry
    symbol: markerSymbol // A symbol for drawing the point
  })
  viewElement.graphics.add(pointGraphic);
</script>

npm

Vite のような最新のビルドツールや、React、Angular、Vue のような JavaScript フレームワークの場合は、npm のようなパッケージマネージャー経由で JavaScript Maps SDK をインストールすることをお勧めします。

セットアップ

node.js と npm の最新の長期サポート（LTS）バージョンを使用していることを確認してください。次に、好みのビルドツールやフレームワークの推奨テンプレートを使ってプロジェクトの大枠を作成します。モジュールバンドラーとローカル Web サーバーを含むクライアントサイドビルドツールである Vite には、多くのテンプレートプロジェクトが用意されています。

プロジェクトでマップコンポーネントを使用するには、@arcgis/map-components パッケージとその依存関係をインストールします。

npm の場合

    npm install @arcgis/map-components

yarn の場合

    yarn add @arcgis/map-components @arcgis/core @esri/calcite-components

CSS の設定

CSS スタイルシートは、CDN または /node_modules からローカルに読み込むことができます。CDN を使用すると、ファイルがローカルにバンドルされずに実行時にロードされるため、ディスク上のビルドサイズが最小になります。

お好みの CSS スタイルシートと Calcite モードを含めることで、ライトまたはダークのテーマを選択できます。SDK はコンポーネントのスタイリングに Calcite を使用しています。また、Calciteを使って独自のカスタムUIを追加することもできる。

CDN の場合

    /* Include calcite, core API and SDK component CSS */
    @import "https://js.arcgis.com/calcite-components/3.2.1/calcite.css";
    @import "https://js.arcgis.com/4.33/@arcgis/core/assets/esri/themes/light/main.css";
    @import "https://js.arcgis.com/4.33/map-components/main.css";

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

/node_modules の場合

    /* Include calcite, core API and SDK component CSS */
    @import "@esri/calcite-components/dist/calcite/calcite.css";
    @import "@arcgis/core/assets/esri/themes/light/main.css";
    @import "@arcgis/map-components/dist/cdn/main.css";

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

import の URL パスを指定するパターンは、使用するフレームワークやモジュールバンドラーに依存します。jsapi-resources の GitHub リポジトリーには、様々なフレームワークやモジュールバンドラーの CSS 設定例があります。MDN には、@import を使用する様々なパターンに関する詳細情報も掲載されています。

レイアウトの作成

Vite + vanilla JavaScript スタータープロジェクトの index.html ファイルに、2D マップコンポーネント（または 3D シーンコンポーネント）を追加し、main.js ファイルを参照してください。各コンポーネントは、<div></div> のような他の HTML 要素と同様に、HTML タグを使用してアプリケーションに追加できるカスタム要素です。

<body>
  <arcgis-map item-id="02b37471d5d84cacbebcccd785460e94">
    <arcgis-zoom position="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 に追加してその機能を有効にします。

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");
// Wait for the view to be ready before adding additional functionality
viewElement.addEventListener("arcgisViewReadyChange", () => {
  ...

  // Create a graphic and add the geometry and symbol to it
  const pointGraphic = new Graphic({
    geometry: point, // A point geometry
    symbol: markerSymbol // A symbol for drawing the point
  });
  viewElement.graphics.add(pointGraphic);
});

TypeScript

TypeScriptは、実行時ではなく開発時にエラーを特定する静的型チェックを提供する強力な言語です。これにより生産性が向上し、トラブルシューティングの時間が短縮されます。TypeScript の定義は、SDK が npm を使ってローカルにインストールされたときに提供される。TypeScript を JavaScript にコンパイルするには、tsconfig.json ファイルを作成して TypeScript コンパイラーを設定する必要がある。プロジェクトのインストール時に tsconfig.json ファイルが自動的に作成された場合は、すべての設定を見直してください。

コア API の TypeScript デコレーターを使用する場合、例えば Accessor サブクラスを作成するときやベースレイヤーを拡張するときには、後方互換性のために useDefineForClassFields フラグを false に設定する必要があるかもしれません。このフラグの詳細については、TSConfig Referenceを参照してください。

以下に tsconfig.json の最小例になります。

{
  "$schema": "https://json.schemastore.org/tsconfig.json",
  // Array of `.ts` files to compile. You can also use glob patterns such as `"src/**/*"`.
  "include": ["src", "*.ts"],
  "compilerOptions": {
    // When `true`, this allows use of `import` syntax such as `import x from 'xyz'`.
    "esModuleInterop": true,
    // Specify library type definitions to be included in the compilation.
    "lib": ["DOM", "DOM.Iterable", "ES2023"],
    // The module system to use for compilation.
    // Here, ES modules are targeted (ESNext) to enable top-level await and dynamic imports.
    "module": "ES2022",
    // Respects package.json's "exports" conditions.
    "moduleResolution": "Bundler",
    // Allow importing from JSON files
    "resolveJsonModule": true,
    // This sets the output at the minimum version of JavaScript features that will be supported.
    "target": "ES2023",
    // Improves performance by checking only the .ts files you write
    // rather than the .d.ts files from the libraries you are using.
    "skipLibCheck": true,
  },
}

詳しくは TypeScript の Get Started ガイドをご覧ください。

React

React 19 プロジェクトで JSX を使用して SDK を使用することは、通常の JavaScript と HTML のプロジェクトで SDK を使用することに似ています。主な違いは、JSX の構文と React のプログラミングパターンです。React のようなフレームワークで作業する場合、コンポーネントのライフサイクルとの統合性を高めるために、一般的にはメソッドを直接呼び出すよりもイベントを使用することが推奨されます。

index.jsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";

import "@arcgis/map-components/dist/components/arcgis-map";
import "./index.css";

const root = createRoot(document.getElementById("root"));
root.render(
  <StrictMode>
    <arcgis-map
      itemId="45b77c869ba14b6dbc2de43a817304a6"
      // All events for the SDK's components in React will start with `onarcgis`
      onarcgisViewReadyChange={(event) => {
        // The view is ready, add additional functionality below
      }}>
    ></arcgis-map>
  </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 パッケージを確認してください。

Angular

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.component.html",
  styleUrl: "./app.component.css",
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Set the schema here
})
export class AppComponent {
  arcgisViewReadyChange(event: CustomEvent) {
    // The view is ready, add additional functionality below
  }
}

app.html の HTML インテリセンスについては、インテリセンスのドキュメントをご覧ください。Angular のようなフレームワークで作業する場合、コンポーネントのライフサイクルとの統合性を高めるために、一般的にはメソッドを直接呼び出すよりもイベントを使用することをお勧めします。

app.html

<arcgis-map
  item-id="45b77c869ba14b6dbc2de43a817304a6"
  (arcgisViewReadyChange)="arcgisViewReadyChange($event)"
>
  <arcgis-zoom position="top-left"></arcgis-zoom>
</arcgis-map>

SDK の Angular テンプレートプロジェクトを参照すると、両方のコンポーネントとコア API の操作方法と CSS の設定方法を示す完全なサンプルが得られます。

アクセストークン

ヒント：アプリケーションで認証に ArcGIS Identities のみを使用している場合は、このセクションをスキップできます。詳しくは、セキュリティと認証のドキュメントを参照してください。

ベースマップ、ジオコーディング、ルーティングなどの ArcGIS サービスにアクセスするには、アクセストークンが必要です。ポータルにアクセスし、特定のニーズに合わせてカスタム権限とリファラーを持つアクセストークンを作成します。チュートリアルやサンプルの説明で必要な場合は、アクセストークンを含めてください。グローバル API キーだけでなく、特定のクラスでより細かい API キーを使用することもできます。

追加情報

詳細については、以下のリンクをご参照ください。

開発の手順

CDN

セットアップ

CSS の設定

レイアウトの作成

npm

セットアップ

CSS の設定

レイアウトの作成

コンポーネントのインポート

TypeScript

React

Angular

アクセス トークン

追加情報

アクセストークン