ドキュメント / セットアップ / React / MapLibre

MapLibre セットアップ

Web で MapLibre を MapConductor から使う手順です。キーが不要で、いちばん短く始められます。maplibre-gl はパッケージに同梱されています。

PACKAGE

react-for-maplibre

API KEY

不要

CSS

必要

REACT NATIVE

あり

ほかのプラットフォームAndroid iOS

デモを見る店舗マップ · React ↗

前提

Node.js 18 以上

React 18 または 19

STEP 01

インストールする

maplibre-gl はパッケージに同梱されているので、別途インストールする必要はありません。

terminalnpm

npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react \
            @mapconductor/react-for-maplibre

STEP 02

Vite の事前バンドルから外す

Vite を使う場合は optimizeDeps.exclude にプロバイダを追加します。maplibre-gl v6 はワーカーを URL で読み込むため、事前バンドルされると .vite/deps 配下にワーカーのファイルが出力されず、読み込みに失敗します。

vite.config.tsTypeScript · Vite

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
    optimizeDeps: {
        exclude: ["@mapconductor/react-for-maplibre", "@mapconductor/js-sdk-core"],
    },
    plugins: [react()],
});

STEP 03

スタイルシートを読み込む

アプリのエントリーポイントで一度だけ読み込みます。忘れると地図の位置やコントロールの見た目が崩れます。

main.tsxTypeScript

import '@mapconductor/react-for-maplibre/style.css';

STEP 04

スタイルを決める

MapLibre にキーはありませんが、タイルの出どころは自分で決める必要があります。既定の DemoTiles は動作確認用です。

注意

OsmBright 系・MapTiler 系・OpenMapTiles のスタイルは日本向けの公開デモタイルホスト（tile.openstreetmap.jp）から配信されています。開発中は便利ですが、本番トラフィックとライセンス遵守のためには自前のスタイル JSON を mapDesignType に指定してください。

動作確認

ここまで動けば完了

東京を中心に地図が出て、マーカーが 1 つ立てば完了です。

HelloMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { MapLibreDesign, MapLibreMapView2D, useMapLibreViewState } from '@mapconductor/react-for-maplibre';
import '@mapconductor/react-for-maplibre/style.css';

const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });

export function HelloMap() {
  const mapState = useMapLibreViewState({
    id: 'maplibre-map',
    mapDesignType: MapLibreDesign.DemoTiles,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

  return (
    <MapLibreMapView2D state={mapState} style={{ height: 480 }}>
      <Marker state={markerState} />
    </MapLibreMapView2D>
  );
}

状態オブジェクト

useMapLibreViewState が受け取るパラメータです。MapLibreMapView は 3D、MapLibreMapView2D は 2D で、どちらも同じ状態を共有します。

signatureTypeScript

useMapLibreViewState({
  id?: string;
  mapDesignType?: MapLibreMapDesignType; // default MapLibreDesign.OsmBright
  cameraPosition?: MapCameraPosition;    // default MapCameraPosition.Default
})

// View props, on top of the shared MapViewBaseProps
{
  maxZoom?: number;
  minZoom?: number;
  projection?: 'mercator' | 'globe';   // a component prop, not part of state
  containerStyle?: React.CSSProperties;
  markerTilingOptions?: MarkerTilingOptions;
  onError?: (error: Error) => void;
}

地図デザイン

MapLibreDesign はスタイル JSON の URL を包んだ定数です。

MapLibreDesign

Notes

DemoTiles

demotiles.maplibre.org。設定ゼロで動く

OsmBright / OsmBrightEn / OsmBrightJa

OSM Bright。ラベルの言語違い

MapTilerTonerEn / MapTilerTonerJa

高コントラストの Toner スタイル

MapTilerBasicEn / MapTilerBasicJa

情報量を落とした Basic スタイル

OpenMapTiles

汎用の OpenMapTiles スタイル

うまくいかないとき

スタイルを変えると一瞬地図が消える

mapDesignType の変更は setStyle ではなく地図の作り直しになります。スタイルの切り替えは安くありません。頻繁に切り替える UI は避けてください。

地図の位置やコントロールが崩れる

style.css を読み込んでいるか確認します。

開発時だけ地図が二重に初期化される

React StrictMode は effect を 2 回実行します。各プロバイダはこれを検知して片方を破棄するようになっているので、StrictMode を外す必要はありません。

次に

projection="globe" を渡すと地球儀表示になります。これはビューの props で、状態オブジェクトには含まれません。