문서 / 설정 / React / ArcGIS

ArcGIS 설정

Web에서 ArcGIS를 MapConductor에서 쓰는 절차입니다. @arcgis/core는 패키지에 동봉되고, Esri의 테마 CSS도 패키지 쪽에서 읽힙니다.

PACKAGE

react-for-arcgis

API KEY

필요

CSS

자동

REACT NATIVE

있음

같은 프로바이더, 다른 플랫폼Android iOS

데모 보기매장 지도 · React ↗

시작하기 전에

Node.js 18 이상

ArcGIS Location Platform의 API 키

STEP 01

설치한다

@arcgis/core는 패키지에 동봉되어 있습니다. Esri의 테마 CSS도 뷰 쪽에서 읽히므로, 스스로 import 할 필요는 없습니다.

terminalnpm

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

STEP 02

API 키를 상태 훅에 넘긴다

키는 뷰 component의 props가 아니라, 상태 훅에 넘깁니다. props에 두면 테스트의 로그나 스냅숏에 섞이기 때문입니다.

ArcGISMap.tsxTypeScript · React

const state = useArcGISViewState({
  apiKey: import.meta.env.VITE_ARCGIS_API_KEY,
  mapDesignType: ArcGISDesign.Streets,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});

주의

키는 빌드 시의 환경 변수(Vite라면 import.meta.env.VITE_*)에서 넘기고, 소스 관리에는 넣지 마세요. 프런트엔드로 전달되는 이상, 공개되어도 피해가 나지 않도록 리퍼러 제한이나 도메인 제한을 반드시 겁니다.

STEP 03

2D와 3D를 나눠 쓴다

ArcGISMapView는 3D의 씬 뷰, ArcGISMapView2D는 2D의 맵 뷰입니다. 둘 다 같은 상태 객체를 공유하므로, 실행 시에 전환할 수 있습니다.

동작 확인

여기까지 보이면 완료

ArcGIS의 지도가 나오면 완료입니다.

ArcGISMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { ArcGISDesign, ArcGISMapView2D, useArcGISViewState } from '@mapconductor/react-for-arcgis';

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

export function ArcGISMap() {
  const state = useArcGISViewState({
    apiKey: import.meta.env.VITE_ARCGIS_API_KEY,
    mapDesignType: ArcGISDesign.Streets,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

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

지도 디자인

ArcGISDesign은 Esri의 베이스맵에 대응합니다. 여기에 든 것은 일부입니다.

ArcGISDesign

Notes

Streets / StreetsNight / StreetsRelief

도로 지도와 그 변종

Imagery / ImageryLabels

위성 화상과 라벨 포함

Topographic / Terrain

지형도

LightGray / DarkGray

데이터를 얹는 바탕용

Navigation / NavigationNight

내비게이션용

Oceans / ChartedTerritory / Nova

그 밖의 테마별 스타일

잘 안 될 때

지도가 나오지 않는다

키가 상태 훅에 전달되고 있는지 확인합니다.
키에서 필요한 ArcGIS 서비스가 활성화되어 있는지 확인합니다.

번들이 크다

@arcgis/core는 큰 라이브러리입니다. ArcGIS를 쓰는 화면만을 동적 import로 잘라내면 초기 로드를 억제할 수 있습니다.

프로바이더를 전환하면 훅의 순서 오류가 나온다

React는 훅의 호출 순서를 바꿀 수 없습니다. 프로바이더마다 작은 컴포넌트를 만들고, 그 안에서 그 프로바이더의 훅을 호출하는 형태로 합니다. 샘플 앱의 providers/ 디렉터리가 이 구성입니다.

ArcGIS는 GIS 자산을 그대로 다룰 수 있는 것이 강점입니다. 공통 API로 부족한 부분은 MapViewHolder에서 네이티브의 뷰를 꺼내 직접 조작할 수 있습니다.