API Reference.ja

API リファレンス（日本語）

MaplatCore が公開する MaplatApp API の概念と利用パターン。本ページは リリース非依存 の解説（ADR-0012）を扱います。最新の完全な API シグネチャ一覧はリポジトリ内 docs/api/ を 参照してください。

目次

• MaplatApp ライフサイクル
• Option のカテゴリ
• 利用パターン
• API シグネチャ参照
• 関連項目

---

MaplatApp ライフサイクル

MaplatApp は MaplatCore をアプリへ組込むためのメインクラスです。 ライフサイクルは3フェーズ:

1. 初期化 — MaplatApp.createObject(option) は地図データ読込・変換準備が 完了したときに解決する Promise を返します。インスタンス生成の推奨方法です。
2. 実行中 — インスタンスはインタラクティブです。ユーザーは地図切替・ レイヤー切替・POI 表示等を行えます。
3. 破棄 — イベントリスナ・DOM 要素・タイルキャッシュを解放します。

なぜ Promise なのか? MaplatCore は地図定義 JSON の読込・TIN 変換の 計算（または事前計算済みデータの読込）・OpenLayers 地図の初期化を 完了してから準備完了となります。Promise はこれらすべてが完了した後に 解決します。

ライフサイクルフェーズと uiHooks は Maplat ビューアリポジトリ内 docs/ui-core-lifecycle.md に記載されています（ライフサイクルは @maplat/ui と共通です）。

Option のカテゴリ

createObject へ渡す option オブジェクトは複数カテゴリのプロパティを持ちます:

カテゴリ	主なキー	用途
地図識別	startFrom	初期地図 ID
DOM ターゲット	div	ターゲット div ID（デフォルト 'map_div'）
外部トークン	mapboxToken	Mapbox タイルサービスのアクセストークン
ベクタータイルエンジン	maplibregl, mapboxgl	ベクタータイル描画用の注入グローバル

option オブジェクトはランタイム挙動を制御します。地図・アプリデータ （どの地図・POI・スタイルを使用するか）は option ではなくアプリ JSON ファイルで定義します。データ形式の詳細は Concepts を 参照してください。

利用パターン

パターン1: CDN 最小利用

バンドラーを使わずに素早く組込む場合、CDN から OpenLayers と MaplatCore を 読み込みます。MaplatCore の前に OpenLayers を読み込む必要があります。

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10/ol.css">
<script src="https://cdn.jsdelivr.net/npm/ol@10/dist/ol.js"></script>

<script src="https://cdn.jsdelivr.net/npm/@maplat/core@0.13.2/dist/maplat_core.umd.js"></script>

<div id="map_div"></div>
<script>
  MaplatApp.createObject({ startFrom: 'gsi' }).then(function (app) {
    console.log('Maplat initialized');
  });
</script>

パターン2: npm ESM import

モダンなバンドラーベースのプロジェクトでは、ES モジュールとして MaplatApp を import します。

import { MaplatApp } from '@maplat/core';
import 'ol/ol.css';

MaplatApp.createObject({ startFrom: 'gsi' }).then((app) => {
  // Application initialized
});

peer dependency として ol（OpenLayers）v9 または v10 を別途インストール する必要があります。

パターン3: フレームワーク統合

MaplatCore をフレームワーク（React, Vue 等）へ統合する場合、コンポーネントの mount/unmount フックでライフサイクルを管理します:

// 疑似コード
onMount: MaplatApp.createObject(option).then(app => { this.app = app; })
onUnmount: this.app.destroy(); // 現行 API に従い解放

同一 DOM 要素に複数の MaplatApp インスタンスを作成しないでください。 新しいインスタンスを作る前に古いインスタンスを解放してください。

API シグネチャ参照

完全な API シグネチャ一覧（地図状態・座標系・マーカー・ライン/ベクター・ POI レイヤー・GPS・イベントのインスタンスメソッド）はリポジトリ内 docs/api/ に保持します。本 Wiki ページでは シグネチャを意図的に重複保持せず、正本からの乖離を防ぎます。

参照:

• docs/api/ — API シグネチャ正本
• README §API リファレンス — 概要と導線

---

英語版はこちら / Read this page in English

関連項目

• Home
• Concepts.ja — データ形式と座標変換の理論
• Tutorials.ja — 利用手順
• README — インストールとクイックスタート