maps-suite

チュートリアル Step 0: 地図を表示する

maps-suite は、Geolonia Maps を JavaScript から命令的に操作するためのライブラリです。この Step では、Web ページに地図を1枚表示します。

ビルド環境の種類は問いません。用意がない場合は、Vite のバニラ JavaScript テンプレートを使用してください。

インストールする

maps-suite と、地図の描画エンジンである maplibre-gl をインストールします。

npm install @geolonia/maps-suite maplibre-gl

地図を表示する

はじめに、地図を描画する要素を HTML に用意します。要素自体には大きさがないため、CSS で高さを指定します。

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>suite</title>
    <style>
      #map { width: 100%; height: 100vh; }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script type="module" src="/main.js"></script>
  </body>
</html>

次に main.js で CSS を読み込み、Map のインスタンスを生成します。

import "maplibre-gl/dist/maplibre-gl.css";
import "@geolonia/maps-core/css";
import { geolonia } from "@geolonia/maps-suite";

new geolonia.maps.Map(document.getElementById("map"), {
  apiKey: "YOUR-API-KEY",
});

上のコードが、そのまま下で動作しています。

記述の要点は次の3点です。

CSS のインポート：maplibre-gl/dist/maplibre-gl.css と @geolonia/maps-core/css の2つが必要です。どちらかが欠けると、コントロールとポップアップの表示が崩れます。
new geolonia.maps.Map(要素, オプション)：第1引数は HTML 要素そのものです（"map" のような id 文字列を渡すと例外になります）。
apiKey：YOUR-API-KEY は動作確認用のデモキーであり、localhost、GitHub Pages、CodePen などの開発環境とプレビュー環境でのみ地図が描画されます（対象の一覧はデモキーで無料で試せる環境を参照してください。自分のキーの発行は Step 5 で扱います）。

動いたか確認する

npm run dev で開発サーバーを起動し、ブラウザで開くと地図が表示されます。中心を指定しない場合、maps-suite は世界全体が見える状態（緯度経度 0, 0、ズーム 0）で描画します。マウスのドラッグで移動し、ホイールで拡大縮小できれば成功です。

うまく出ないとき

真っ白で何も出ない → #map の高さが 0 になっていないか確認。<style> の指定を確認してください。
「The first argument must be an HTMLElement」という例外 → Map に id 文字列を渡しています。document.getElementById("map") で要素を取得して渡してください。
表示が崩れる（コントロールのアイコンの位置がずれるなど）→ CSS のインポート漏れ。2つとも読み込んでいるか確認。

次の Step

以上で、maps-suite による地図の表示は完了です。次の Step 1: 初期位置とズームの設定で、地図の中心座標、拡大率、傾きを指定します。