문서 / 설정 / React / Azure Maps

Azure Maps 설정

Web에서 Azure Maps를 MapConductor에서 쓰는 절차입니다. Azure의 서브스크립션 키로 인증합니다.

PACKAGE

react-for-azuremaps

API KEY

서브스크립션 키

CSS

필요

REACT NATIVE

없음

데모 보기매장 지도 · React ↗

시작하기 전에

Node.js 18 이상

Azure Maps의 계정과 서브스크립션 키

STEP 01

설치한다

azure-maps-control은 패키지에 동봉되어 있습니다.

terminalnpm

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

STEP 02

스타일시트를 읽어 들인다

앱의 엔트리 포인트에서 한 번만 읽어 들입니다. 잊으면 지도의 위치나 컨트롤의 겉모습이 무너집니다.

main.tsxTypeScript

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

STEP 03

서브스크립션 키를 넘긴다

키는 상태 훅의 subscriptionKey에 넘깁니다. 비어 있는 채로는 지도가 초기화되지 않습니다.

AzureMap.tsxTypeScript · React

const state = useAzureMapsViewState({
  subscriptionKey: import.meta.env.VITE_AZURE_MAPS_SUBSCRIPTION_KEY ?? '',
  mapDesignType: AzureMapsDesign.Road,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});

주의

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

동작 확인

여기까지 보이면 완료

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

AzureMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { AzureMapsDesign, AzureMapsMapView, useAzureMapsViewState } from '@mapconductor/react-for-azuremaps';
import '@mapconductor/react-for-azuremaps/style.css';

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

export function AzureMap() {
  const state = useAzureMapsViewState({
    subscriptionKey: import.meta.env.VITE_AZURE_MAPS_SUBSCRIPTION_KEY ?? '',
    mapDesignType: AzureMapsDesign.Road,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

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

지도 디자인

AzureMapsDesign은 Azure Maps의 스타일에 대응합니다.

AzureMapsDesign

Notes

Road / RoadShadedRelief

표준의 도로 지도와 음영 기복 포함

Satellite / SatelliteRoadLabels

위성 화상과 라벨 포함

GrayscaleLight / GrayscaleDark

데이터를 얹는 바탕용

Night

야간 스타일

HighContrastLight / HighContrastDark

고대비

Blank / BlankAccessible

베이스맵 없음

잘 안 될 때

지도가 나오지 않는다

subscriptionKey가 빈 문자열이 되어 있지 않은지 확인합니다.
Azure 포털에서 키가 유효한지 확인합니다.

개발 시에만 지도가 이중으로 초기화된다

React StrictMode는 effect를 2번 실행합니다. 각 프로바이더는 이것을 감지해 한쪽을 파기하도록 되어 있으므로, StrictMode를 뺄 필요는 없습니다.

서브스크립션 키는 브라우저로 전달됩니다. 본번에서는 이용 범위를 제한하거나, Azure의 인증 방식을 검토해 주세요.