문서 / 설정 / React / deck.gl

deck.gl 설정

Web에서 deck.gl을 MapConductor의 지도로 사용하는 절차입니다. 키가 필요 없으며, 베이스맵에는 임의의 XYZ 래스터 타일을 사용할 수 있습니다.

PACKAGE
react-for-deckgl
API KEY
불필요
CSS
불필요
3D CAMERA
기울기·회전

시작하기 전에

Node.js 18 이상
React 18 또는 19
STEP 01

설치하기

deck.gl(@deck.gl/core·layers·geo-layers 9.x)은 의존성으로 함께 설치됩니다.

terminalnpm
npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react \
            @mapconductor/react-for-deckgl
STEP 02

베이스맵 정하기

deck.gl 자체는 지도를 가지지 않으므로, 베이스맵은 XYZ 래스터 타일에서 그립니다. 제공된 디자인 외에 타일 URL 템플릿을 전달하면 자체 타일도 사용할 수 있습니다. 귀속 표기는 attributionRules에 작성합니다.

designs.tsTypeScript
import { DeckGLDesign } from '@mapconductor/react-for-deckgl';

const gsi = new DeckGLDesign({
  id: 'gsi-standard',
  tileUrl: 'https://cyberjapandata.gsi.go.jp/xyz/std/{z}/{x}/{y}.png',
  tileSize: 256,
  maxZoom: 18,
  attributionRules: [{ attribution: '国土地理院' }],
});

state.mapDesignType = gsi;
주의
OpenStreetMap의 공개 타일 서버에는 이용 정책이 있습니다. 실제 트래픽을 흘려보내는 경우 자체 타일 배포나 상용 서비스를 사용하세요.
STEP 03

필요해질 때까지 로드하지 않기

루트의 @mapconductor/react-for-deckgl을 import하면 deck.gl 본체가 로드됩니다. 상태와 디자인만 필요하다면 @mapconductor/react-for-deckgl/state에서 가져올 수 있으므로, 지도 자체는 lazy()로 나중에 로드할 수 있습니다. DeckGLView는 루트에서 DeckGLMapView를 import하고 state를 전달하기만 하는 컴포넌트입니다.

Page.tsxTypeScript · React
import { lazy, Suspense } from 'react';
import { DeckGLDesign, useDeckGLMapViewState } from '@mapconductor/react-for-deckgl/state';

const DeckGLView = lazy(() => import('./DeckGLView'));

export function Page() {
  const state = useDeckGLMapViewState({ mapDesignType: DeckGLDesign.Dark });
  return (
    <Suspense fallback={null}>
      <DeckGLView state={state} />
    </Suspense>
  );
}

동작 확인

여기까지 보이면 완료

지도와 마커가 표시되면 완료입니다.

DeckGLMap.tsxTypeScript · React
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { DeckGLDesign, DeckGLMapView, useDeckGLMapViewState } from '@mapconductor/react-for-deckgl';
import { useState } from 'react';

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

export function DeckGLMap() {
  const state = useDeckGLMapViewState({
    mapDesignType: DeckGLDesign.Standard,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

  return (
    <DeckGLMapView state={state} containerStyle={{ height: 480 }}>
      <Marker state={markerState} />
    </DeckGLMapView>
  );
}

지도 디자인

DeckGLDesign은 타일 URL 템플릿을 감싼 값입니다. 자체 타일을 사용하는 경우 같은 타입을 new 합니다.

DeckGLDesign
Notes
Standard
OpenStreetMap의 표준 타일. 최대 줌 19
Satellite
Esri World Imagery의 항공 사진
Dark
CARTO의 어두운 지도. 최대 줌 20
Light
CARTO의 밝은 지도. 최대 줌 20
None
베이스 타일 없음. 오버레이나 벡터 스타일만 그리고 싶을 때

잘 안 될 때

Longdo나 Mappls와 같은 페이지에 두면 에러가 발생함

  • deck.gl은 자신의 버전을 globalThis.deck에 등록하고, 다른 버전이 이미 있으면 예외를 던집니다. Longdo의 SDK는 deck.gl 8.x를 가져오며, Mappls도 같은 일을 합니다. 같은 페이지에 두지 말고, /state와 lazy()로 필요해질 때까지 deck.gl을 로드하지 마세요.

지도를 회전하면 지명도 회전함

  • 베이스맵은 래스터 타일이므로, 문자도 이미지의 일부입니다. 문자를 세워 두고 싶다면 벡터 스타일을 그릴 수 있는 MapLibre 등을 선택하세요.

회전만·기울기만 끌 수 없음

  • deck.gl의 dragRotate가 양쪽을 함께 처리하기 때문에, 한쪽만 끌 수는 없습니다. 그렇게 지정하면 둘 다 활성 상태로 유지되며, 한 번만 경고가 표시됩니다.

다음

마커·원·폴리라인·폴리곤·지표 이미지·래스터 레이어는 다른 프로바이더와 동일한 코드로 그릴 수 있습니다. 벡터 스타일을 겹치고 싶을 때는 벡터 타일 레이어를 DeckGLDesign.None과 조합하세요.