문서 / 설정 / 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에 지정해 주세요.

동작 확인

여기까지 보이면 완료

도쿄를 중심으로 지도가 나오고, 마커가 하나 서면 완료입니다.

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이며, 상태 객체에는 포함되지 않습니다.