syncfusion-javascript-maps

TypeScript と JavaScript での Syncfusion Maps の実装

Syncfusion EJ2 Maps コンポーネントは、オンラインタイルプロバイダー、GeoJSON シェイプレイヤー、マーカー、バブル、カスタムポリゴン、ナビゲーションライン、ラベル、凡例、注釈、ツールチップ、選択、ズーム、パン、印刷、エクスポートを通じて、地理情報を可視化します。

このスキルでは、フレームワークに依存しない次の実装を扱います。

• npm とモジュールインポートを使用する TypeScript アプリケーション。
• バージョン指定された EJ2 グローバルバンドルを使用する JavaScript アプリケーション。
• OpenStreetMap と認証が必要なマッププロバイダー。
• GeoJSON の地理的シェイプ。
• 座標ベースのマーカー。
• 地域に関連付けられたバブル。
• カスタムポリゴンオーバーレイ。
• シェイプとバブルの色分け。
• ナビゲーションライン。
• 凡例、注釈、ツールチップ。
• 選択とハイライト表示。
• 組み込みの永続化とアプリケーション独自の永続化。
• 印刷と画像エクスポート。
• アクセシビリティ、検証、パフォーマンス、クリーンアップ。

プラットフォームのサポート

TypeScript

アプリケーションで次を使用する場合は、TypeScript を使用します。

• @syncfusion/ej2-maps npm パッケージ。
• TypeScript コンパイル。
• Webpack、Vite、またはその他のモジュールバンドラー。
• 明示的な機能モジュールの注入。
• 型付けされたデータモデルと設定モデル。
• コンパイル時の検証と IDE の IntelliSense。

パッケージをインストールします。

npm install @syncfusion/ej2-maps

基本的なインポート：

import {
    Maps
} from '@syncfusion/ej2-maps';

Maps を構築する前に、機能モジュールをインポートして注入する必要があります。

import {
    Maps,
    Marker,
    Zoom
} from '@syncfusion/ej2-maps';

Maps.Inject(
    Zoom,
    Marker
);

JavaScript

アプリケーションで次を使用する場合は、グローバル JavaScript を使用します。

• バージョン指定された EJ2 CDN バンドル。
• ローカルでホストされた EJ2 グローバルバンドル。
• 従来の HTML ファイルと JavaScript ファイル。
• グローバルな ej.maps.Maps コンストラクター。
• TypeScript コンパイルを行わない環境。

グローバルコンストラクター：

ej.maps.Maps

バージョン指定された EJ2 グローバルバンドル全体を使用します。

<script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script>

完全なバンドルと、個別の ej2-base、ej2-data、ej2-svg-base、ej2-maps の各スクリプトを併用しないでください。

完全なバンドルを使用するグローバル JavaScript では、明示的な Maps.Inject(...) の呼び出しは不要です。

JavaScript の互換性

グローバル JavaScript の例では、実用的な範囲で ES5 互換の構文を使用します。

var declarations
Traditional functions
No TypeScript annotations
No ECMAScript module imports
Global ej namespace

ただし、ブラウザーのサポートは、インストールした EJ2 リリースの対応ブラウザーマトリックスに適合させる必要があります。

レガシーブラウザーが無制限にサポートされると約束しないでください。

このスキルを使用する場面

次のタスクが必要な場合は、このスキルを使用してください。

• オンラインマッププロバイダーを表示する。
• GeoJSON から国、州、またはカスタム地域を表示する。
• 座標ベースの位置を表示する。
• バブルで地域ごとの規模を可視化する。
• データに基づいてシェイプまたはバブルの色を設定する。
• 座標で定義したカスタムポリゴン領域を描画する。
• ナビゲーションラインで位置を結ぶ。
• 地理的シェイプにデータラベルを追加する。
• 凡例とツールチップを表示する。
• マップに対して位置を調整した注釈コンテンツを追加する。
• シェイプ、マーカー、またはバブルを選択またはハイライト表示する。
• ズームとパンに対応する。
• サポートされているマップの状態を永続化する。
• 検証済みのアプリケーション設定を保存する。
• レンダリングされたマップを印刷する。
• マップを PNG、JPEG、または SVG としてエクスポートする。
• レスポンシブレイアウトに対応する。
• 大規模な地理データセットを最適化する。
• セットアップ、ネットワーク、データバインディング、または描画に関する障害を診断する。

可視化の選択ガイド

マーカーを使用する

緯度と経度で直接定義された位置には、マーカーを使用します。

例：

• オフィス。
• 店舗。
• 空港。
• 倉庫。
• インシデント地点。
• ルートの経由地点。

バブルを使用する

GeoJSON のシェイプに関連付けられた数値には、バブルを使用します。

例：

• 国別の人口。
• 州別の収益。
• テリトリー別の売上。
• 地域別のエンゲージメント。

バブルは、座標マーカーの直接的な代替ではありません。

GeoJSON シェイプを使用する

次の用途には shapeData を使用します。

• 国。
• 州。
• 県。
• 地区。
• 行政区域の境界。
• カスタムの地理的フィーチャーコレクション。

カスタムポリゴンを使用する

座標点に基づくアプリケーション定義の領域には、polygonSettings.polygons を使用します。

例：

• 配送区域。
• 制限区域。
• カバー範囲。
• サービス提供区域。

ナビゲーションラインを使用する

ナビゲーションラインを使用して、次の項目を表示します。

• ルート。
• 経路。
• 接続。
• 飛行経路。
• 地理的な依存関係。

機能モジュールのリファレンス

Zooming and panning -> Zoom
Markers             -> Marker
Bubbles             -> Bubble
Navigation lines    -> NavigationLine
Tooltips            -> MapsTooltip
Legends             -> Legend
Annotations         -> Annotations
Selection           -> Selection
Data labels         -> DataLabel
Custom polygons     -> Polygon
Printing            -> Print
Image export        -> ImageExport
PDF export          -> PdfExport

例で使用するモジュールのみをインポートして、インジェクションします。

例：

import {
    Maps,
    MapsTooltip,
    Marker,
    Zoom
} from '@syncfusion/ej2-maps';

Maps.Inject(
    Zoom,
    Marker,
    MapsTooltip
);

インポートとインジェクションの内容を一致させます。

誤り：

import {
    Maps
} from '@syncfusion/ej2-maps';

Maps.Inject(
    Marker
);

正しい例：

import {
    Maps,
    Marker
} from '@syncfusion/ej2-maps';

Maps.Inject(
    Marker
);

実装ルール

DOM への明示的なアタッチを使用する

推奨する TypeScript：

const map: Maps =
    new Maps({
        layers
    });

map.appendTo(
    '#maps-container'
);

推奨する JavaScript：

var map =
    new ej.maps.Maps({
        layers: layers
    });

map.appendTo(
    '#maps-container'
);

ホスト要素を確認する

const host:
    HTMLElement | null =
        document.getElementById(
            'maps-container'
        );

if (!host) {
    throw new Error(
        'The Maps host element "#maps-container" was not found.'
    );
}

測定可能な寸法を指定する

Maps に明確な高さを設定します。

#maps-container {
    width: 100%;
    min-height: 600px;
}

width:
    '100%',

height:
    '600px'

次の設定に依存することは避けてください。

height:
    '100%'

ただし、関連するすべての祖先要素に、計算済みの明確な高さがある場合を除きます。

centerPosition を使用する

誤り：

center: {
    latitude: 37.7749,
    longitude: -122.4194
}

正しい例：

centerPosition: {
    latitude: 37.7749,
    longitude: -122.4194
}

機能の設定を正しいレベルに保つ

Shape data             -> Layer shapeData
Shape binding data     -> Layer dataSource
Shape tooltip          -> Layer tooltipSettings
Shape selection        -> Layer selectionSettings
Markers                -> Layer markerSettings array
Marker tooltip          -> Marker entry tooltipSettings
Marker selection        -> Marker entry selectionSettings
Bubbles                -> Layer bubbleSettings array
Bubble tooltip          -> Bubble entry tooltipSettings
Bubble selection        -> Bubble entry selectionSettings
Navigation lines       -> Layer navigationLineSettings array
Custom polygons        -> Layer polygonSettings
Shape labels           -> Layer dataLabelSettings

ドキュメントとナビゲーションガイド

はじめにとセットアップ

次を参照してください。

references/getting-started.md

このリファレンスでは、次の内容を説明しています。

• パッケージのインストール。
• TypeScript のインポート。
• モジュールのインジェクション。
• JavaScript CDN のセットアップ。
• OpenStreetMap の初期化。
• ホストの寸法。
• 世界地図データの取得。
• Maps の初回実装。

データとレイヤー

次を参照してください。

references/data-and-layers.md

このリファレンスでは、次の内容を説明しています。

• オンラインタイルレイヤー。
• GeoJSON シェイプレイヤー。
• メインレイヤー。
• サブレイヤー。
• baseLayerIndex。
• シェイプデータのバインド。
• マーカーとバブルのデータ配置。
• レイヤーの表示／非表示。
• 安全な実行時更新。

マーカーとナビゲーション

次を参照してください。

references/markers-and-navigation.md

このリファレンスでは、次の内容を説明しています。

• 座標ベースのマーカー。
• マーカーの外観。
• マーカーテンプレート。
• マーカー画像。
• マーカーツールチップ。
• マーカーの選択。
• マーカーイベント。
• マーカーのクラスタリング。
• ナビゲーションライン。
• マーカーとルートの動的な更新。

視覚化機能

次を参照してください。

references/visualization-features.md

このリファレンスでは、次の内容を説明しています。

• 地域に関連付けられたバブル。
• GeoJSON シェイプの描画。
• カスタムポリゴンオーバーレイ。
• シェイプの色マッピング。
• バブルの色マッピング。
• シェイプデータラベル。
• 地域の複合的な視覚化。

凡例と注釈

次を参照してください。

references/legends-and-annotations.md

このリファレンスでは、次の内容を説明しています。

• デフォルトの凡例とインタラクティブな凡例。
• ドッキングされた凡例とフローティング凡例。
• レイヤー、マーカー、バブルの凡例。
• 凡例の切り替え動作。
• マップに対する注釈の配置。
• シェイプ、マーカー、バブルのツールチップ。

マッププロバイダーと選択

次を参照してください。

references/map-providers-and-selection.md

このリファレンスでは、次の内容を説明しています。

• OpenStreetMap。
• Bing Maps。
• カスタムタイルプロバイダー。
• プロバイダーの認証。
• プロバイダーのセキュリティと帰属表示。
• シェイプの選択。
• マーカーの選択。
• バブルの選択。
• 単一選択と複数選択。
• 検証済みのインタラクションイベント。

カスタマイズと永続化

次を参照してください。

references/customization-and-persistence.md

このリファレンスでは、次の内容を説明しています。

• 組み込みテーマ。
• 公開されている外観モデル。
• アプリケーションが管理するラッパー CSS。
• レスポンシブレイアウト。
• 組み込みの永続化機能。
• 検証済みのブラウザーストレージ設定。
• 印刷。
• PNG、JPEG、SVG へのエクスポート。
• クリーンアップ。

トラブルシューティング

次を参照してください。

references/troubleshooting.md

このリファレンスでは、次の内容を説明しています。

• インストールの失敗。
• バンドルの読み込み失敗。
• モジュールのインジェクション漏れ。
• ホストと寸法の問題。
• タイルプロバイダーの問題。
• GeoJSON の読み込み失敗。
• マーカーとバブルの問題。
• データバインドの問題。
• 色マッピングの失敗。
• ツールチップと選択の問題。
• パフォーマンスとメモリの問題。
• TypeScript と JavaScript の診断。

TypeScript クイックスタート

この例では、マーカー、マーカーツールチップ、ズーム、パンを使って OpenStreetMap を表示します。

index.html

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">

    <meta
        name="viewport"
        content="width=device-width, initial-scale=1.0"
    >

    <title>Syncfusion Maps</title>

    ./styles.css
</head>

<body>
    <main class="page-container">
        <section
            class="maps-card"
            aria-labelledby="maps-heading"
            aria-describedby="maps-description"
        >
            <h1 id="maps-heading">
                Office Location
            </h1>

            <p id="maps-description">
                An interactive OpenStreetMap view showing the
                San Francisco office location.
            </p>

            <div id="maps-container"></div>

            <p class="map-attribution">
                Map data © OpenStreetMap contributors
            </p>

            <p
                id="maps-status"
                aria-live="polite"
            >
                Loading the map.
            </p>
        </section>
    </main>

    <script scr="app.ts"></script>
</body>
</html>

styles.css

html,
body {
    margin: 0;
    min-height: 100%;
}

body {
    color: #111827;
    background: #f1f5f9;
    font-family:
        "Segoe UI",
        Arial,
        sans-serif;
}

.page-container {
    width: 100%;
    min-height: 100vh;
    padding: 24px;
    box-sizing: border-box;
}

.maps-card {
    width: 100%;
    max-width: 1200px;
    margin: 0 auto;
    padding: 16px;
    box-sizing: border-box;
    background: #ffffff;
    border: 1px solid #cbd5e1;
    border-radius: 8px;
}

.maps-card h1 {
    margin: 0 0 8px;
    font-size: 24px;
}

.maps-card > p {
    color: #475569;
    line-height: 1.5;
}

#maps-container {
    width: 100%;
    min-height: 600px;
}

.map-attribution {
    margin: 8px 0 0;
    font-size: 12px;
}

@media (max-width: 768px) {
    .page-container {
        padding: 12px;
    }

    .maps-card {
        padding: 12px;
    }

    #maps-container {
        min-height: 500px;
    }
}

app.ts

import {
    Maps,
    MapsTooltip,
    Marker,
    Zoom
} from '@syncfusion/ej2-maps';

Maps.Inject(
    Zoom,
    Marker,
    MapsTooltip
);

interface LocationData {
    id: string;
    name: string;
    latitude: number;
    longitude: number;
}

const locationData:
    LocationData[] = [
        {
            id:
                'san-francisco-office',
            name:
                'San Francisco Office',
            latitude:
                37.7749,
            longitude:
                -122.4194
        }
    ];

const validateLocations = (
    locations:
        LocationData[]
): void => {
    const ids:
        Set<string> =
            new Set<string>();

    locations.forEach(
        (
            location:
                LocationData
        ): void => {
            if (
                !location.id.trim()
            ) {
                throw new Error(
                    'Every marker requires a nonempty ID.'
                );
            }

            if (
                ids.has(
                    location.id
                )
            ) {
                throw new Error(
                    'Duplicate marker ID: ' +
                    location.id
                );
            }

            if (
                !location.name.trim()
            ) {
                throw new Error(
                    'Every marker requires a name.'
                );
            }

            if (
                !Number.isFinite(
                    location.latitude
                ) ||
                location.latitude < -90 ||
                location.latitude > 90
            ) {
                throw new Error(
                    'Invalid marker latitude.'
                );
            }

            if (
                !Number.isFinite(
                    location.longitude
                ) ||
                location.longitude < -180 ||
                location.longitude > 180
            ) {
                throw new Error(
                    'Invalid marker longitude.'
                );
            }

            ids.add(
                location.id
            );
        }
    );
};

validateLocations(
    locationData
);

const host:
    HTMLElement | null =
        document.getElementById(
            'maps-container'
        );

const statusElement:
    HTMLElement | null =
        document.getElementById(
            'maps-status'
        );

if (!host) {
    throw new Error(
        'The Maps host element "#maps-container" was not found.'
    );
}

const map: Maps =
    new Maps({
        width: '100%',
        height: '600px',

        centerPosition: {
            latitude: 37.7749,
            longitude: -122.4194
        },

        zoomSettings: {
            enable: true,
            enablePanning: true,
            mouseWheelZoom: true,
            pinchZooming: true,
            minZoom: 1,
            maxZoom: 13,
            zoomFactor: 5,

            toolbarSettings: {
                buttonSettings: {
                    toolbarItems: [
                        'Zoom',
                        'ZoomIn',
                        'ZoomOut',
                        'Pan',
                        'Reset'
                    ]
                }
            }
        },

        layers: [
            {
                urlTemplate:
                    'https://tile.openstreetmap.org/level/tileX/tileY.png',

                markerSettings: [
                    {
                        visible: true,
                        dataSource:
                            locationData,
                        latitudeValuePath:
                            'latitude',
                        longitudeValuePath:
                            'longitude',
                        width: 24,
                        height: 24,
                        shape: 'Circle',
                        fill: '#dc2626',

                        border: {
                            color: '#ffffff',
                            width: 2
                        },

                        tooltipSettings: {
                            visible: true,
                            valuePath:
                                'name'
                        }
                    }
                ]
            }
        ],

        loaded: (): void => {
            if (
                statusElement
            ) {
                statusElement.textContent =
                    'The map loaded successfully.';
            }
        }
    });

map.appendTo(
    host
);

JavaScript クイックスタート

この例では、単独で動作する 1 つの HTML ファイルで同等の動作を実現します。

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">

    <meta
        name="viewport"
        content="width=device-width, initial-scale=1.0"
    >

    <title>Syncfusion Maps</title>


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

        body {
            color: #111827;
            background: #f1f5f9;
            font-family:
                "Segoe UI",
                Arial,
                sans-serif;
        }

        .page-container {
            width: 100%;
            min-height: 100vh;
            padding: 24px;
            box-sizing: border-box;
        }

        .maps-card {
            width: 100%;
            max-width: 1200px;
            margin: 0 auto;
            padding: 16px;
            box-sizing: border-box;
            background: #ffffff;
            border: 1px solid #cbd5e1;
            border-radius: 8px;
        }

        #maps-container {
            width: 100%;
            min-height: 600px;
        }

        .map-attribution {
            color: #475569;
            font-size: 12px;
        }

        @media (max-width: 768px) {
            .page-container {
                padding: 12px;
            }

            #maps-container {
                min-height: 500px;
            }
        }
    </style>
    <script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script>
</head>

<body>
    <main class="page-container">
        <section
            class="maps-card"
            aria-labelledby="maps-heading"
            aria-describedby="maps-description"
        >
            <h1 id="maps-heading">
                Office Location
            </h1>

            <p id="maps-description">
                An interactive OpenStreetMap view showing the
                San Francisco office location.
            </p>

            <div id="maps-container"></div>

            <p class="map-attribution">
                Map data © OpenStreetMap contributors
            </p>

            <p
                id="maps-status"
                aria-live="polite"
            >
                Loading the map.
            </p>
        </section>
    </main>

    <script>
        var locationData = [
            {
                id:
                    'san-francisco-office',
                name:
                    'San Francisco Office',
                latitude:
                    37.7749,
                longitude:
                    -122.4194
            }
        ];

        function validateLocations(
            locations
        ) {
            var ids =
                new Set();

            locations.forEach(
                function (location) {
                    if (
                        typeof location.id !==
                            'string' ||
                        location.id
                            .trim()
                            .length === 0
                    ) {
                        throw new Error(
                            'Every marker requires a nonempty ID.'
                        );
                    }

                    if (
                        ids.has(
                            location.id
                        )
                    ) {
                        throw new Error(
                            'Duplicate marker ID: ' +
                            location.id
                        );
                    }

                    if (
                        !Number.isFinite(
                            location.latitude
                        ) ||
                        location.latitude < -90 ||
                        location.latitude > 90
                    ) {
                        throw new Error(
                            'Invalid marker latitude.'
                        );
                    }

                    if (
                        !Number.isFinite(
                            location.longitude
                        ) ||
                        location.longitude < -180 ||
                        location.longitude > 180
                    ) {
                        throw new Error(
                            'Invalid marker longitude.'
                        );
                    }

                    ids.add(
                        location.id
                    );
                }
            );
        }

        validateLocations(
            locationData
        );

        var host =
            document.getElementById(
                'maps-container'
            );

        var statusElement =
            document.getElementById(
                'maps-status'
            );

        if (!host) {
            throw new Error(
                'The Maps host element "#maps-container" was not found.'
            );
        }

        if (
            typeof window.ej ===
                'undefined' ||
            !window.ej.maps
        ) {
            throw new Error(
                'The EJ2 Maps global bundle was not loaded.'
            );
        }

        var map =
            new ej.maps.Maps({
                width: '100%',
                height: '600px',

                centerPosition: {
                    latitude: 37.7749,
                    longitude: -122.4194
                },

                zoomSettings: {
                    enable: true,
                    enablePanning: true,
                    mouseWheelZoom: true,
                    pinchZooming: true,
                    minZoom: 1,
                    maxZoom: 13,
                    zoomFactor: 5,

                    toolbarSettings: {
                        buttonSettings: {
                            toolbarItems: [
                                'Zoom',
                                'ZoomIn',
                                'ZoomOut',
                                'Pan',
                                'Reset'
                            ]
                        }
                    }
                },

                layers: [
                    {
                        urlTemplate:
                            'https://tile.openstreetmap.org/level/tileX/tileY.png',

                        markerSettings: [
                            {
                                visible: true,
                                dataSource:
                                    locationData,
                                latitudeValuePath:
                                    'latitude',
                                longitudeValuePath:
                                    'longitude',
                                width: 24,
                                height: 24,
                                shape: 'Circle',
                                fill: '#dc2626',

                                border: {
                                    color:
                                        '#ffffff',
                                    width: 2
                                },

                                tooltipSettings: {
                                    visible: true,
                                    valuePath:
                                        'name'
                                }
                            }
                        ]
                    }
                ],

                loaded:
                    function () {
                        statusElement.textContent =
                            'The map loaded successfully.';
                    }
            });

        map.appendTo(
            host
        );
    </script>
</body>
</html>

GeoJSON 世界地図のセットアップ

OpenStreetMap では世界地図ファイルは不要です。

GeoJSON シェイプ、色マッピング、シェイプラベル、バブルの例では、完全な shapeData が必要です。

世界地図の GeoJSON ファイルをダウンロードします。

mkdir -p src/data
curl -L "https://datahub.io/core/geo-countries/_r/-/data/countries.geojson" -o "src/data/world-map.geojson"

手動でダウンロードする場合：

https://datahub.io/core/geo-countries/_r/-/data/countries.geojson

検証します。

import {
    readFile
} from 'node:fs/promises';

const content =
    await readFile(
        'src/data/world-map.geojson',
        'utf8'
    );

const worldMap =
    JSON.parse(
        content
    );

if (
    worldMap.type !==
    'FeatureCollection'
) {
    throw new Error(
        'The world-map file must be a GeoJSON FeatureCollection.'
    );
}

if (
    !Array.isArray(
        worldMap.features
    ) ||
    worldMap.features.length === 0
) {
    throw new Error(
        'The world-map file does not contain features.'
    );
}

TypeScript で JSON をインポートするには、次の設定を有効にします。

{
  "compilerOptions": {
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

次に、インポートします。

import worldMap
    from './data/world-map.json';

よくあるパターン

地域データの可視化

完全なデータバインディングを備えた GeoJSON レイヤーを使用します。

layers: [
    {
        shapeData:
            worldMap,

        dataSource:
            regionData,

        shapePropertyPath:
            'name',

        shapeDataPath:
            'country',

        shapeSettings: {
            fill: '#e2e8f0',
            colorValuePath:
                'value',

            colorMapping: [
                {
                    from: 0,
                    to: 39,
                    color: '#dbeafe',
                    label: 'Low'
                },
                {
                    from: 40,
                    to: 69,
                    color: '#60a5fa',
                    label: 'Moderate'
                },
                {
                    from: 70,
                    to: 100,
                    color: '#1d4ed8',
                    label: 'High'
                }
            ]
        }
    }
]

単数形を使用します。

colorMapping

次のようにはしないでください。

colorMappings

マルチレイヤーマップ

検証済みのメインレイヤーと SubLayer オーバーレイを使用します。

layers: [
    {
        shapeData:
            worldMap
    },
    {
        type: 'SubLayer',
        shapeData:
            overlayGeoJson,

        shapeSettings: {
            fill:
                'rgb(37 99 235 / 30%)'
        }
    }
]

マーカーとバブルの設定を分けるためだけに、空のレイヤーを作成しないでください。

インタラクティブな操作性

次を使用します。

Zoom        -> Zooming and panning
MapsTooltip -> Tooltips
Selection   -> Visual selection

クリックイベントと視覚的な選択状態は分けてください。

情報が重要な場合は、外部に永続表示される詳細情報を使用します。ホバーツールチップだけに頼らないでください。

ナビゲーションとルートの可視化

navigationLineSettings: [
    {
        latitude: [
            37.7749,
            34.0522
        ],

        longitude: [
            -122.4194,
            -118.2437
        ],

        color: '#2563eb',
        width: 3,
        opacity: 0.8,
        dashArray: '8 4'
    }
]

次の項目を検証します。

• 座標ペアが 2 つ以上あること。
• 緯度配列と経度配列の長さが一致していること。
• 座標値が有限であること。
• 緯度が -90 から 90 の範囲内であること。
• 経度が -180 から 180 の範囲内であること。
• 線の幅が正の値であること。
• 不透明度が 0 から 1 の範囲内であること。

距離と所要時間はアプリケーション側で管理する値です。ナビゲーションラインは、ルートの距離、移動時間、道路案内を自動的に計算しません。

主な機能の概要

マーカー

緯度と経度に基づく地理的な地点に使用します。

バブル

GeoJSON の図形に関連付けた大きさの可視化に使用します。

GeoJSON 図形

shapeData で指定する地理的な境界に使用します。

カスタムポリゴン

polygonSettings.polygons で指定する座標ベースのオーバーレイに使用します。

カラーマッピング

範囲、等値、または不透明度に基づく図形やバブルの色付けに使用します。

レイヤー

メインレイヤーと検証済みの SubLayer オーバーレイを使用します。

ナビゲーションライン

地点を結ぶ座標パスに使用します。

凡例

レイヤー、バブル、またはマーカーの色や記号の説明に使用します。

注釈

x と y で位置を指定する、マップに対する HTML オーバーレイに使用します。

注釈では緯度と経度を使用しません。地理的な地点にはマーカーを使用してください。

ツールチップ

図形、マーカー、またはバブルに関連する補足情報に使用します。

永続化

組み込みコンポーネントの永続化がアプリケーションの要件を満たす場合は、enablePersistence を使用します。

カスタム設定、スキーマのバージョン管理、有効期限、レイヤーの表示状態、またはユーザーごとの設定には、検証済みのアプリケーション管理ストレージを使用します。

印刷とエクスポート

次を使用します。

Print       -> Print module and allowPrint
ImageExport -> ImageExport module and allowImageExport
PdfExport   -> PdfExport module and allowPdfExport

実行時の検証チェックリスト

✅ @syncfusion/ej2-maps is installed.
✅ Maps is imported.
✅ Every enabled TypeScript feature has its module imported.
✅ Every imported runtime module is injected before construction.
✅ Unused optional modules are not injected.
✅ Global JavaScript does not call Maps.Inject.
✅ The complete EJ2 bundle loads before application code.
✅ Combined and individual bundles are not mixed.
✅ Every CDN script URL ends in .min.js.
✅ The Maps host exists.
✅ The appendTo target matches the host ID.
✅ The host has measurable width and height.
✅ Maps width and height use valid CSS-size strings.
✅ centerPosition is used instead of center.
✅ Zoom is injected when zooming or panning is enabled.
✅ Tile URLs are plain strings.
✅ OpenStreetMap URLs contain level, tileX, and tileY.
✅ OpenStreetMap attribution is visible.
✅ Provider terms and network requirements are reviewed.
✅ Maps provider credentials are protected as far as the provider permits.
✅ The layer contains urlTemplate or shapeData.
✅ GeoJSON is a nonempty FeatureCollection.
✅ shapePropertyPath matches a GeoJSON feature property.
✅ shapeDataPath matches application data.
✅ markerSettings is an array.
✅ Every active marker entry uses visible: true.
✅ Marker coordinate paths match marker data.
✅ Marker IDs are nonempty and unique when required.
✅ Marker latitudes are finite and between -90 and 90.
✅ Marker longitudes are finite and between -180 and 180.
✅ bubbleSettings is an array.
✅ Every active bubble entry uses visible: true.
✅ Bubble data is associated with GeoJSON shapes.
✅ Bubble valuePath matches finite numeric values.
✅ colorMapping uses the singular property name.
✅ Color ranges are finite and nonoverlapping.
✅ Navigation-line coordinate arrays have matching lengths.
✅ Annotations use x and y rather than latitude and longitude.
✅ Layer indexes are validated before runtime updates.
✅ Storage preferences are validated before use.
✅ Print and export flags match injected modules.
✅ Runtime updates are batched.
✅ refresh is called once after complete updates.
✅ Important information is not communicated only by color, size, or hover.
✅ Application-owned listeners and timers are cleaned up.
✅ Pending requests are cancelled where appropriate.
✅ map.destroy() is called when a dynamic host is removed.
✅ No encoded HTML replaces executable markup.
✅ No rich-text anchors or editor-generated classes remain.

アクセシビリティに関するガイダンス

• 意味のある見出しを用意します。
• 簡潔なマップの説明を用意します。
• 意味のあるマーカー名と地域名を付けます。
• マーカーの色だけに頼らないでください。
• バブルの大きさだけに頼らないでください。
• マッピングされた図形の色だけに頼らないでください。
• 説明的な凡例ラベルを用意します。
• 選択内容の詳細を常に表示します。
• フォーカスを視認できる状態に保ちます。
• 印刷、エクスポート、リセットなどのアプリケーション操作には、ネイティブのボタンを使用します。
• 意思決定に重要な可視化データには、意味的に適切なテーブルを用意します。
• マーカーのタップ領域をタッチデバイスで使いやすい大きさにします。
• ツールチップの内容を、不可欠な情報の唯一の情報源にしないでください。
• ライブリージョンによる通知が過剰にならないようにします。
• 必要なプロバイダーの帰属表示を含めます。
• キーボード、タッチ操作、スクリーンリーダー、ブラウザーのズーム、リフローの動作をテストします。
• アプリケーション全体がアクセシビリティ規格に自動的に準拠すると主張しないでください。

パフォーマンスとクリーンアップ

• 解析済みの GeoJSON を再利用します。
• 変更されていない図形を繰り返し取得しないでください。
• 地理的な精度を検証したうえでのみ、ジオメトリを簡略化します。
• 描画前にマーカー、バブル、図形、ルートのデータを検証します。
• マーカーとツールチップのテンプレートはシンプルに保ちます。
• プロファイリングを行ったうえでのみ、クラスタリングを使用します。
• 実行時の変更をまとめて適用します。
• refresh() は 1 回だけ呼び出します。
• 負荷の高い描画イベントのログ出力は避けます。
• クリーンアップせずに、同じホストで Maps を再作成しないでください。
• アプリケーションが所有するイベントリスナーを削除します。
• 保留中のタイマーをクリアします。
• 適切な場合は、保留中のリクエストをキャンセルします。
• 動的ビューが削除されるときに Maps を破棄します。

map.destroy();

間違いやすい点と今後の参考情報

誤った Center プロパティ

誤り：

center: {
    latitude: 37.7749,
    longitude: -122.4194
}

正しい例：

centerPosition: {
    latitude: 37.7749,
    longitude: -122.4194
}

Zoom のインジェクション不足

誤り：

import {
    Maps
} from '@syncfusion/ej2-maps';

const map: Maps =
    new Maps({
        zoomSettings: {
            enable: true
        }
    });

正しい例：

import {
    Maps,
    Zoom
} from '@syncfusion/ej2-maps';

Maps.Inject(
    Zoom
);

Marker Settings をオブジェクトとして指定

誤り：

markerSettings: {
    dataSource:
        locationData
}

正しい例：

markerSettings: [
    {
        visible: true,
        dataSource:
            locationData
    }
]

オブジェクトとしての Bubble 設定

誤り：

bubbleSettings: {
    dataSource:
        bubbleData
}

正しい例：

bubbleSettings: [
    {
        visible: true,
        dataSource:
            bubbleData
    }
]

未対応機能の表示

誤り：

markerSettings: [
    {
        dataSource:
            locationData
    }
]

正しい例：

markerSettings: [
    {
        visible: true,
        dataSource:
            locationData
    }
]

リッチテキストタイルの URL

誤り：

urlTemplate:
    'https://tile.openstreetmap.org/......</a>'

正しい例：

urlTemplate:
    'https://tile.openstreetmap.org/level/tileX/tileY.png'

不要な OSM タイプ

避けてください：

type:
    'OSM'

次を使用してください：

urlTemplate:
    'https://tile.openstreetmap.org/level/tileX/tileY.png'

座標ベースの Bubble に関する誤った想定

誤り：

Bubbles can always be positioned like markers by supplying
latitude and longitude on a basic tile layer.

正しい例：

Use markers for direct coordinates.
Use bubbles for values associated with GeoJSON shapes.

色のマッピングプロパティの誤り

誤り：

colorMappings: []

正しい例：

colorMapping: []

図形プロパティのパスの誤り

誤り：

shapePropertyPath:
    'properties.name'

正しい例：

shapePropertyPath:
    'name'

地理座標を使用した注釈

誤り：

annotations: [
    {
        latitude:
            37.7749,
        longitude:
            -122.4194
    }
]

地理座標にはマーカーを使用してください。

注釈には x と y を使用してください：

annotations: [
    {
        content:
            '#annotation-template',
        x:
            '5%',
        y:
            '10%'
    }
]

Maps ルートにあるナビゲーションライン

誤り：

map.navigationLineSettings =
    routes;

正しい例：

map.layers[0]
    .navigationLineSettings =
        routes;

未定義の地理データ

避けてください：

shapeData:
    worldMap

ただし、worldMap がインポート、定義されているか、正常に取得されている場合を除きます。

未検証のイベント名

次のイベントが存在すると決めつけないでください：

zoomEnd
panEnd
mouseMove
layerRender

インストール済みパッケージに照らして、イベントとイベントタイプを検証してください。

不正な CDN マークアップ

誤り：

https://cdn.syncfusion.com/...
    https://cdn.syncfusion.com/...
</a>

正しい例：

<script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script>

結合バンドルと個別バンドルの混在

誤り：

<script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script>
<script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-base/dist/global/ej2-base.min.js"></script>
<script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-maps/dist/global/ej2-maps.min.js"></script>

正しい例：

<script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script>

実行可能な HTML のエンコード

誤り：

<div id="maps-container"></div>

正しい例：

<div id="maps-container"></div>

クリーンアップの欠落

動的ビューが削除されたとき：

button.removeEventListener(
    'click',
    handleClick
);

controller.abort();

map.destroy();

エディターが生成したマークアップ

実行可能な HTML、TypeScript、JavaScript、CSS、インポート、コマンド、テンプレート、URL から、次の項目を削除してください：

<a>
<strong data-lexical-text="true">
<br>
data-lexical-text
Editor-generated class names
Encoded executable tags