문서 / 설정 / React / MapTiler

MapTiler 설정

Web에서 MapTiler Cloud의 스타일을 MapConductor에서 쓰는 절차입니다. 렌더러는 maplibre-gl이고, 스타일은 API 키가 붙은 MapTiler Cloud URL로 조립됩니다.

PACKAGE

react-for-maptiler

API KEY

필요

CSS

필요

REACT NATIVE

없음

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

데모 보기매장 지도 · React ↗

시작하기 전에

Node.js 18 이상

MapTiler Cloud의 계정과 API 키

STEP 01

설치한다

코어와 React 바인딩, 그리고 프로바이더의 패키지를 넣습니다. 프로바이더를 교체할 때 바뀌는 것은 3번째뿐입니다.

terminalnpm

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

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-maptiler", "@mapconductor/js-sdk-core"],
    },
    plugins: [react()],
});

STEP 03

스타일시트를 읽어 들인다

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

main.tsxTypeScript

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

STEP 04

API 키를 상태 훅에 넘긴다

키는 스타일 JSON의 URL에 포함됩니다(https://api.maptiler.com/maps/<style>/style.json?key=…).

MapTilerMap.tsxTypeScript · React

const state = useMapTilerViewState({
  apiKey: import.meta.env.VITE_MAPTILER,
  mapDesignType: MapTilerDesign.Streets,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});

주의

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

동작 확인

여기까지 보이면 완료

MapTiler의 스타일로 지도가 나오면 완료입니다.

MapTilerMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { MapTilerDesign, MapTilerMapView2D, useMapTilerViewState } from '@mapconductor/react-for-maptiler';
import '@mapconductor/react-for-maptiler/style.css';

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

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

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

지도 디자인

MapTilerDesign은 MapTiler Cloud의 참조 스타일에 대응합니다.

MapTilerDesign

Notes

Streets / StreetsDark / StreetsLight

표준의 도로 지도와 명암의 배리에이션

Basic / Bright

정보량을 줄인 스타일

Satellite

위성 화상

Outdoor / Winter / Topo

아웃도어・동계・지형

Toner / Dataviz / Backdrop

데이터를 얹는 바탕용

Ocean / Landscape / Aquarelle / OpenStreetMap

그 밖의 테마별 스타일

잘 안 될 때

지도가 새하얀 채로

apiKey가 빈 문자열이 되어 있지 않은지 확인합니다. 환경 변수를 읽지 못하는 경우가 많습니다.
MapTiler Cloud에서 키가 유효한지, 무료 구간을 넘지 않았는지 확인합니다.

지도의 위치나 컨트롤이 무너진다

style.css를 읽어 들이고 있는지 확인합니다.

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

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

MapLibre와 같은 렌더러이므로, 거동이나 제약은 MapLibre 프로바이더와 공통입니다.