NaverMap

NaverMap 컴포넌트는 네이버 지도를 렌더링합니다. Container 컴포넌트 내부에서 사용해야 합니다.

사용법

import { Container as MapDiv, NaverMap } from 'react-naver-maps';

<MapDiv style={{ width: '100%', height: '400px' }}>
  <NaverMap
    defaultCenter={new navermaps.LatLng(37.3595704, 127.105399)}
    defaultZoom={15}
  />
</MapDiv>;

Controlled vs Uncontrolled

NaverMap은 center/defaultCenter, zoom/defaultZoom 등 controlled/uncontrolled 패턴을 지원합니다.

  • defaultCenter: 초기 중심 좌표 (uncontrolled)
  • center: 중심 좌표 (controlled — 외부에서 값을 관리)

Props

이름타입필수기본값설명
childrenReact.ReactNode---
centernaver.maps.Coord | naver.maps.CoordLiteral | undefined---
zoomnumber | undefined---
boundsnaver.maps.Bounds | naver.maps.BoundsLiteral | undefined---
mapTypeIdnaver.maps.MapTypeId | undefined---
sizenaver.maps.Size | naver.maps.SizeLiteral | undefined---
centerPointnaver.maps.Point | naver.maps.PointLiteral | undefined---
defaultCenternaver.maps.Coord | naver.maps.CoordLiteral | undefined---
defaultZoomnumber | undefined---
defaultBoundsnaver.maps.Bounds | naver.maps.BoundsLiteral | undefined---
defaultMapTypeIdnaver.maps.MapTypeId | undefined---
defaultSizenaver.maps.Size | naver.maps.SizeLiteral | undefined---
defaultCenterPointnaver.maps.Point | naver.maps.PointLiteral | undefined---
logoControlboolean | undefined--로고 컨트롤 표시 여부. SDK 패턴: 일방향 controlled. - `true`/미지정: 표시 (SDK 기본). - `false`: SDK가 `setRefinedOption`에서 `value || true`로 강제 변환하여 거부. 즉 false로는 끌 수 없다. 위치만 바꾸려면 `logoControlOptions`를 사용한다. dev에서 `false` 시도 시 console.warn으로 안내.
repeatXboolean | undefined--X축 타일 반복(세계 일주). SDK 패턴: static. 런타임 변경 시 tile system 재구성이 필요해 생성자에만 적용한다.
glboolean | undefined--GL 벡터맵 활성화. SDK 패턴: static. 런타임 변경 시 SDK가 `switchTo()`로 렌더 모드 전체를 교체하므로 비싸고 위험. 생성자에만 적용한다. 사용 시 GL 서브모듈을 함께 로드해야 한다.
customStyleIdstring | undefined--Style Editor에서 발행한 My Style ID. SDK 패턴: static (GL 모드 전용). 생성자에만 적용한다.
useStyleMapboolean | undefined--스타일 맵 사용 여부. SDK 패턴: static. 생성자에만 적용한다.
tileDurationnumber | undefined--타일 페이드 인 효과 지속 시간(ms). SDK 패턴: static. SDK에 `setTileDuration`/`tileDuration_changed`가 없고 타일 인스턴스 생성 시에만 읽히므로(maps.beautified.js:5568/5642/6468) 런타임 변경이 무시된다. 생성자에만 적용한다.
minZoomnumber | undefined---
maxZoomnumber | undefined---
cursorstring | undefined--커서 스타일. SDK 패턴: controlled (`setCursor`/`getCursor`). 주의: SDK가 드래그 중 손 커서("open"/"closed")로 자체 토글하고 초기화 시 `setCursor("open")`을 호출하므로(map-view.js), controlled 값과 상호 덮어쓰기될 수 있다. `draggable={false}`처럼 드래그가 없는 경우에 안정적으로 동작한다.
tiltnumber | undefined--지도 기울기(GL 모드). SDK 패턴: controlled (`setTilt`/`getTilt`, `tilt_changed`).
rotationnumber | undefined--지도 회전(GL 모드). SDK 패턴: controlled (`setRotation`/`getRotation`, `rotation_changed`).
backgroundstring | undefined---
baseTileOpacitynumber | undefined---
draggableboolean | undefined---
scrollWheelboolean | undefined---
pinchZoomboolean | undefined---
keyboardShortcutsboolean | undefined---
disableDoubleClickZoomboolean | undefined---
disableDoubleTapZoomboolean | undefined---
disableTwoFingerTapZoomboolean | undefined---
disableKineticPanboolean | undefined---
tileTransitionboolean | undefined---
logoControlOptionsnaver.maps.ControlOptions | undefined---
mapDataControlboolean | undefined---
mapDataControlOptionsnaver.maps.ControlOptions | undefined---
mapTypeControlboolean | undefined---
mapTypeControlOptionsnaver.maps.MapTypeControlOptions | undefined---
scaleControlboolean | undefined---
scaleControlOptionsnaver.maps.ControlOptions | undefined---
zoomControlboolean | undefined---
zoomControlOptionsnaver.maps.ZoomControlOptions | undefined---
mapTypesnaver.maps.MapTypeRegistry | undefined---
maxBoundsnaver.maps.Bounds | naver.maps.BoundsLiteral | undefined---
paddingnaver.maps.Margin | undefined---
resizeOriginnaver.maps.Position | undefined---
overlayZoomEffectstring | null | undefined---
tileSparenumber | undefined---
zoomOriginnaver.maps.Coord | naver.maps.CoordLiteral | undefined---
blankTileImagestring | null | undefined---
onCenterChanged((center: naver.maps.Coord) => void) | undefined---
onZoomChanged((zoom: number) => void) | undefined---
onBoundsChanged((bounds: naver.maps.Bounds) => void) | undefined---
onMapTypeIdChanged((mapTypeId: naver.maps.MapTypeId) => void) | undefined---
onSizeChanged((value: naver.maps.Size) => void) | undefined---
onCenterPointChanged((value: naver.maps.Point) => void) | undefined---
onMapTypeChanged((value: naver.maps.MapType) => void) | undefined---
onTiltChanged((value: number) => void) | undefined---
onRotationChanged((value: number) => void) | undefined---
onInit(() => void) | undefined---
onIdle(() => void) | undefined---
onPanning(() => void) | undefined---
onZooming(() => void) | undefined---
onTilesloaded(() => void) | undefined---
onResize(() => void) | undefined---
onProjectionChanged(() => void) | undefined---
onAddLayer(() => void) | undefined---
onRemoveLayer(() => void) | undefined---
onClick((e: naver.maps.PointerEvent) => void) | undefined---
onDblclick((e: naver.maps.PointerEvent) => void) | undefined---
onRightclick((e: naver.maps.PointerEvent) => void) | undefined---
onMousedown((e: naver.maps.PointerEvent) => void) | undefined---
onMouseup((e: naver.maps.PointerEvent) => void) | undefined---
onMouseover((e: naver.maps.PointerEvent) => void) | undefined---
onMouseout((e: naver.maps.PointerEvent) => void) | undefined---
onMousemove((e: naver.maps.PointerEvent) => void) | undefined---
onDragstart((e: naver.maps.PointerEvent) => void) | undefined---
onDrag((e: naver.maps.PointerEvent) => void) | undefined---
onDragend((e: naver.maps.PointerEvent) => void) | undefined---
onTouchstart((e: naver.maps.PointerEvent) => void) | undefined---
onTouchmove((e: naver.maps.PointerEvent) => void) | undefined---
onTouchend((e: naver.maps.PointerEvent) => void) | undefined---
onPinchstart((e: naver.maps.PointerEvent) => void) | undefined---
onPinch((e: naver.maps.PointerEvent) => void) | undefined---
onPinchend((e: naver.maps.PointerEvent) => void) | undefined---
onTap((e: naver.maps.PointerEvent) => void) | undefined---
onLongtap((e: naver.maps.PointerEvent) => void) | undefined---
onTwofingertap((e: naver.maps.PointerEvent) => void) | undefined---
onDoubletap((e: naver.maps.PointerEvent) => void) | undefined---
onKeydown((e: naver.maps.PointerEvent) => void) | undefined---
onKeyup((e: naver.maps.PointerEvent) => void) | undefined---