문서 / 설정 / React / Mapbox

Mapbox 설정

Web에서 Mapbox를 MapConductor에서 쓰는 절차입니다. 액세스 토큰이 필요한 것은 Mapbox 호스트의 스타일(mapbox://로 시작하는 것)을 쓸 때뿐입니다.

PACKAGE

react-for-mapbox

API KEY

스타일에 따라

CSS

필요

REACT NATIVE

없음

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

데모 보기매장 지도 · React ↗

시작하기 전에

Node.js 18 이상

Mapbox 호스트의 스타일을 쓰는 경우는 퍼블릭 액세스 토큰

STEP 01

설치한다

mapbox-gl은 패키지에 동봉되어 있으므로, 별도로 설치할 필요는 없습니다. React Native 판은 없습니다.

terminalnpm

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

STEP 02

스타일시트를 읽어 들인다

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

main.tsxTypeScript

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

STEP 03

액세스 토큰을 넘긴다(필요한 경우)

토큰은 상태 훅에 넘깁니다. 내부에서 mapboxgl.accessToken에 글로벌 설정됩니다. OSM 기반의 디자인만 쓴다면 생략할 수 있습니다.

HelloMap.tsxTypeScript · React

const mapState = useMapboxViewState({
  id: 'mapbox-map',
  accessToken: import.meta.env.VITE_MAPBOX_ACCESS_TOKEN,
  mapDesignType: MapboxDesign.Streets,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});

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

주의

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

동작 확인

여기까지 보이면 완료

OsmBright를 쓰면 토큰 없이도 동작을 확인할 수 있습니다.

HelloMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { MapboxDesign, MapBoxMapView2D, useMapboxViewState } from '@mapconductor/react-for-mapbox';
import '@mapconductor/react-for-mapbox/style.css';

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

export function HelloMap() {
  // No token needed for the OsmBright design
  const mapState = useMapboxViewState({
    id: 'mapbox-map',
    mapDesignType: MapboxDesign.OsmBright,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

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

상태 객체

useMapboxViewState가 받는 파라미터입니다. 뷰의 export 이름이 MapBoxMapView / MapBoxMapView2D(B가 대문자)인 점에 주의해 주세요.

signatureTypeScript

useMapboxViewState({
  id?: string;
  accessToken?: string;
  mapDesignType?: MapboxMapDesignType; // default MapboxDesign.Streets
  cameraPosition?: MapCameraPosition;  // default MapCameraPosition.Default
})

지도 디자인

MapboxDesign은 「토큰이 필요한 것」과 「필요 없는 것」의 2개 군으로 나뉩니다.

MapboxDesign

Notes

Streets / Outdoors / Light / Dark

Mapbox 호스트. 토큰이 필요

SatelliteStreets

Mapbox 호스트의 위성 화상. 토큰이 필요

OsmBright / OsmBrightEn / OsmBrightJa

MapLibre와 공통의 OSM 스타일. 토큰 불필요

MapTilerToner* / MapTilerBasic* / OpenMapTiles

마찬가지로 MapLibre 공통. 토큰 불필요

잘 안 될 때

Mapbox의 스타일만 표시되지 않는다

mapbox://로 시작하는 스타일에는 토큰이 필요합니다. accessToken을 넘기고 있는지 확인합니다.
토큰이 퍼블릭 토큰인지, 실효되지 않았는지 확인합니다.

줌 레벨이 다른 프로바이더와 어긋난다

MapConductor는 Google 기준으로 줌을 맞추고 있습니다. Mapbox는 거기에 실측의 오프셋(googleZoom ≒ mapboxZoom + 1.0)을 걸어 환산하고 있습니다.

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

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

MapLibre와 같은 구조이므로, mapDesignType의 변경은 지도의 재생성이 됩니다.