Skip to content

Tutorials.ja

Jump to bottom
Kohei Otsuka edited this page Aug 10, 2026 · 5 revisions

Tutorials（日本語）

2 つの手順ガイドです。MaplatEditor で作ったアプリを公開する道と、 自分のページに Maplat ビューアを組み込む道を扱います。

注記: 最新のクイックスタート（インストールコマンド・CDN の URL・バージョン番号）は README を参照してください。このページはリリースに依存しない チュートリアルの内容を扱います。

目次

どちらの道を選ぶか

やりたいこと 道
MaplatEditor で作ったアプリを、そのまま公開したい 道 A — 実際に使うならこちら
すでにあるページやサイトの中に Maplat の地図を置きたい 道 B

この 2 つは代替案ではなく、段階です。 ビューアはアプリ定義・地図設定・タイル・サムネイルを ページの隣に置かれたファイルから読み込みますが、それらを作るのは MaplatEditor です。 ∴ 道 B にも道 A の成果物が要ります。道 B が目的の場合でも、まず道 A を読んでください。

道 A — MaplatEditor で作ったアプリを公開する

A1. アプリを書き出す

MaplatEditor で地図・POI ソース・アプリを作り、書き出し機能を使います。 成果物はアプリ ID の名前を持つ ZIP 1 本です。

そこまでの手順 — 地図の作成・タイル化・GCP の設定・POI・アプリ設定・書き出し — は MaplatEditor Wiki の Tutorials が扱います。このページは ZIP を手に入れた後から始まります。

A2. パッケージの中身

解凍すると、そのまま配れる静的サイトが出てきます:

{appID}/
├ index.html          入口のページ。ビューアを読み込んで起動する
├ favicon.ico
├ service-worker.js   キャッシュを有効にした場合のみ
├ apps/               アプリ定義
├ maps/               地図・ベースマップの設定
├ tiles/              地図タイル
├ tmbs/               地図選択 UI 用サムネイル
├ merc/               メルカトルタイルセット（使う場合）
├ pois/               POI ソース（GeoJSON）
├ imgs/               POI アイコン
├ img/                スプラッシュ画像
├ pwa/                マニフェストとアイコン（PWA 有効時）
└ assets/             ビューア本体・OpenLayers・UI の言語リソース

この構成から 2 つのことが導かれます。

  • パッケージは自己完結しています。 ビューアも OpenLayers も UI の翻訳もすべて assets/ の 中にあり、実行時に CDN へ依存しません。唯一の例外は MapLibre GL JS / Mapbox GL JS で、 これらは CDN から、かつ当該種別のソースをアプリが実際に含む場合にだけ読み込まれます。
  • 中身を手で書き換えることは想定していません。 データを変えるときは MaplatEditor 側で変えて 書き出し直します。例外は A4 で述べる 2 つの切り替えだけです。

A3. Web サーバに置く

解凍したフォルダごとアップロードし、index.html を開きます。

ビューアはアプリ定義と地図設定を HTTP 経由で取得するため、 ローカルフォルダ（file://）からは動きません。 必ず Web サーバに置いてください。 静的ホスティングであれば何でも構いません。

サブディレクトリでも動きます。ビューアが使うパスはすべてページからの相対なので、 https://example.com/maps/morioka/ でもサイトのルートと同じように動作します。

A4. 書き出し直さずに挙動を変える

書き出された index.html は、ビューアを起動する前に任意のクエリパラメータを オプションへ流し込みます。∴ URL だけで挙動を変えられます:

クエリ 効果
?lang=en UI を英語で動かす（通常はブラウザ設定から自動判定）
?overlay=true 古地図を現代地図の上にオーバーレイ表示する
?appid=hoge 書き出されたアプリ定義ではなく apps/hoge.json を読み込む。apps/ の下に定義を複数置いた場合にだけ意味がある

true と false は真偽値になり、それ以外は文字列のまま渡されます。 受け付けるキーの決まった一覧はありません —— オプションのどのプロパティでも同じように働きます。 どんなプロパティがあるかは API-Reference § MaplatAppOption のカテゴリ を参照してください。

これは書き出されたページの性質であって、ライブラリの機能ではありません。 @maplat/ui は URL のクエリを自分で読むことがありません。自分でページを作る場合（道 B）は、同じ数行を 自分で書いたときにだけこの挙動が手に入ります。

既定値として焼き込みたい場合は、index.html の末尾近くにあるオプションを書き換えます:

var option = {
  "appid": "myApp",
  "lang": "en",
  "overlay": true
};

A5. 共有できる URL

アプリ設定で 状態URL を有効にすると、ビューアは現在の地図・位置・ズーム・回転を URL の #! 以降に保ち続けます。アドレスバーが常に「いま見えているもの」へのリンクになります:

https://example.com/myApp/#!s:morioka/b:gsi/x:141.149989/y:39.699952/z:17

この URL はブックマークでき、共有でき、後から開き直せます。同じ設定で シェア機能 を有効にすると、 このリンクを利用者へ直接渡す共有 UI が加わります。

個々のキーは内部的な符号化であり、リリースごとに増えることがあります。 ∴ 手で組み立てるのではなく、不透明な文字列として扱ってください。

道 B — 自分のページにビューアを組み込む

B1. OpenLayers と Maplat UI を CDN から読み込む

ビルド工程を持たない自前のページでは、先に OpenLayers を、その後に Maplat UI を 読み込みます。Maplat UI はグローバルの ol が存在することを前提とします。

<!-- OpenLayers の CSS と JS（必須。かつ先に読むこと） -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10/ol.min.css">
<script src="https://cdn.jsdelivr.net/npm/ol@10/dist/ol.min.js"></script>

<!-- <version> は README のリリースブロックに載っている版へ置き換えてください。 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@maplat/ui@<version>/dist/maplat_ui.css">
<!-- <version> は README のリリースブロックに載っている版へ置き換えてください。 -->
<script src="https://cdn.jsdelivr.net/npm/@maplat/ui@<version>/dist/maplat_ui.umd.js"></script>

<div id="map_div" style="width: 100%; height: 100vh;"></div>

<script>
  MaplatUi.createObject({ appid: "myApp" }).then(function (app) {
    console.log("Maplat initialized", app);
  });
</script>

createObject は Promise を返し、地図データの読み込みと座標変換の準備が終わった時点で解決します。

B2. ビューアが探すデータファイル

上のコードだけでは地図は出ません。appid は「ページからの相対で apps/myApp.json を取得せよ」 という指示であり、その定義がさらに別のファイルを、やはりページからの相対で指します:

your-page/
├ index.html      上のコードを書いた自前のページ
├ apps/           apps/<appid>.json — アプリ定義
├ maps/           maps/<mapID>.json — 地図・ベースマップごとに 1 つ
├ tiles/          tiles/<mapID>/{z}/{x}/{y}.<ext>
├ tmbs/           地図選択 UI 用サムネイル
└ pois/           アプリ定義から参照される POI ソース

これらのフォルダは、道 A で書き出したパッケージから持ってきます。 同じファイルを同じ配置で 置くだけです。道 A の index.html と assets/ にあたる部分を、自前のページと CDN のタグで 置き換えている、という関係になります。

これらは HTTP 経由で取得されるため、自前のページにも道 A と同じ制約が掛かります。 file:// からは動きません。 制作中はローカルの開発用サーバを使ってください。

各ファイルの中身については Concepts § アプリケーションデータ形式 と Concepts § 現行版の POI を参照してください。 現行版で動くアプリ定義の実例がリポジトリ内の public/apps/sample.json にあります。

B3. バンドラで使う

バンドラを使うプロジェクトでは、パッケージを導入して ES モジュールとして import します。 OpenLayers は peer dependency なので別途導入します。

pnpm add @maplat/ui ol
import { MaplatUi } from '@maplat/ui';
import '@maplat/ui/dist/maplat_ui.css';

MaplatUi.createObject({ appid: 'myApp' }).then(app => {
  // アプリケーションの初期化完了
});

B2 のデータファイルはこの場合も必要です。 ビルド後のページから辿れる場所（多くのバンドラでは public / static ディレクトリ）へ置いてください。

B4. オプションとシグネチャ

このページはオプションのプロパティ一覧やメソッドのシグネチャを意図的に載せていません。 正しく保つ場所を 1 か所に閉じるためです。

  • API-Reference — ライフサイクル・オプションのカテゴリ・ フレームワーク組み込みのパターン
  • docs/api/ — シグネチャの正本
  • MaplatCore Wiki の Tutorials — UI の下の層（@maplat/core）。イベント処理・実行時の POI レイヤ操作・線とベクタ

よくあるつまずき

  • ファイルシステムから開くと何も表示されない。 ビューアは JSON を fetch しますが、 ブラウザは file:// でこれを拒否します。HTTP で配信してください。
  • Invalid Maplat option key: … Use "…" instead. 旧リリース向けに書かれたアプリ定義は app_name や home_position のような snake_case を使っていました。現行版はこれらを変換せず 拒否します。現行の camelCase への対応表は Concepts § アプリケーションデータ形式 にあります。
  • ベースマップが黙って消える。 Mapbox / MapLibre のベースマップは GL ライブラリを必要とし、 それは CDN から読み込まれます。CDN に到達できない場合、そのソースだけが警告つきで落ち、 残りのアプリは動き続けます。

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

関連ページ

  • Home
  • Concepts — データ形式と座標変換の理論
  • API-Reference — API の概念と利用パターン
  • Gallery — 公開されている Maplat アプリ（実際に開いて試せます）
  • README — 最新のクイックスタート

Maplat

Language / 言語

Pages / ページ

English

日本語

External / 外部

Clone this wiki locally