v0.1에서 마이그레이션

0.2는 React 19 전용으로 재작성되었습니다.

React 19 필수

peerDependencies가 react@^19.0.0으로 변경되었습니다.

인증 키

NCP 콘솔에서 발급받은 키를 ncpKeyId로 전달합니다. 기존 ncpClientId도 동작하지만, ncpKeyId가 현재 NCP 표준입니다.

<NavermapsProvider ncpKeyId="YOUR_NCP_KEY_ID">
  <Container style={{ width: '100%', height: '400px' }}>
    <NaverMap
      defaultCenter={{ lat: 37.5666, lng: 126.9784 }}
      defaultZoom={16}
    />
  </Container>
</NavermapsProvider>

이벤트 핸들링

<Listener> 컴포넌트가 제거되었습니다. on* props를 사용합니다.

// Before (v0.1)
<Marker position={position}>
  <Listener type="click" listener={handleClick} />
  <Listener type="rightclick" listener={handleRightClick} />
</Marker>

// After (v0.2)
<Marker position={position} onClick={handleClick} onRightclick={handleRightClick} />

on* props에 없는 이벤트(KVO changed, idle 등)는 useListener() 훅을 사용합니다.

function IdleTracker() {
  const map = useMap();

  useListener(map, 'idle', () => {
    console.log('지도 이동 완료');
  });

  return null;
}

커스텀 오버레이

<Overlay element={...}> + <Listener> 조합이 제거되었습니다. useOverlay() + useListener() 훅으로 대체됩니다.

// Before (v0.1)
function MyCustomMarkers() {
  const navermaps = useNavermaps();

  const [marker1] = useState(
    () =>
      new navermaps.Marker({
        position: { lat: 37.5666, lng: 126.9784 },
      }),
  );

  const marker2Ref = useRef(null);
  if (!marker2Ref.current) {
    marker2Ref.current = new navermaps.Marker({
      position: { lat: 37.5657, lng: 126.9755 },
    });
  }
  const marker2 = marker2Ref.current;

  useListener(marker1, 'click', () => alert('서울시청'));

  return (
    <>
      <Overlay element={marker1} />
      <Overlay element={marker2}>
        <Listener type="click" listener={() => alert('덕수궁')} />
      </Overlay>
    </>
  );
}

// After (v0.2)
function MyCustomMarkers() {
  const navermaps = useNavermaps();
  const map = useMap();

  const marker1 = useOverlay(
    () =>
      new navermaps.Marker({
        map,
        position: { lat: 37.5666, lng: 126.9784 },
      }),
  );

  const marker2 = useOverlay(
    () =>
      new navermaps.Marker({
        map,
        position: { lat: 37.5657, lng: 126.9755 },
      }),
  );

  useListener(marker1, 'click', () => alert('서울시청'));
  useListener(marker2, 'click', () => alert('덕수궁'));

  return null;
}

네이버맵 공식 CustomOverlay 패턴(OverlayView 상속)도 동일하게 useOverlay로 연결할 수 있습니다. 자세한 내용은 useOverlay API Reference를 참고하세요.

제거된 API