카메라 제어

NaverMapViewRef를 통해 명령형으로 카메라를 제어하고 좌표를 변환하는 방법을 설명합니다.

Ref 설정

import React, { useRef } from 'react';
import { NaverMapView, type NaverMapViewRef } from '@boostbrothers/react-native-naver-map';

export default function MapScreen() {
  const mapRef = useRef<NaverMapViewRef>(null);

  return (
    <NaverMapView
      ref={mapRef}
      style={{ flex: 1 }}
      initialCamera={{
        latitude: 37.5666102,
        longitude: 126.9783881,
        zoom: 14,
      }}
    />
  );
}

카메라 이동 메서드

animateCameraTo

특정 좌표로 카메라를 이동합니다.

mapRef.current?.animateCameraTo({
  latitude: 37.5666102,
  longitude: 126.9783881,
  zoom: 14,          // 선택 (미설정 시 현재 줌 유지)
  duration: 700,     // ms (기본: 700)
  easing: 'EaseOut', // 기본: 'EaseOut'
  pivot: { x: 0.5, y: 0.5 }, // 기본: 중앙
});

animateCameraBy

현재 위치에서 화면 좌표 델타값만큼 카메라를 이동합니다.

// 화면을 오른쪽으로 100dp, 아래로 50dp 이동
mapRef.current?.animateCameraBy({
  x: 100,
  y: 50,
  duration: 500,
  easing: 'EaseOut',
});

animateRegionTo

특정 Region(영역)이 화면에 완전히 보이는 줌 레벨로 카메라를 이동합니다.

mapRef.current?.animateRegionTo({
  latitude: 37.50,
  longitude: 126.90,
  latitudeDelta: 0.1,
  longitudeDelta: 0.1,
  duration: 700,
  easing: 'EaseOut',
});

animateCameraWithTwoCoords

두 좌표가 모두 화면에 보이는 최대 줌 레벨로 카메라를 이동합니다.

mapRef.current?.animateCameraWithTwoCoords({
  coord1: { latitude: 37.50, longitude: 126.90 },
  coord2: { latitude: 37.60, longitude: 127.00 },
  duration: 700,
  easing: 'Fly',
  pivot: { x: 0.5, y: 0.5 },
});

cancelAnimation

진행 중인 카메라 애니메이션을 즉시 취소합니다.

mapRef.current?.cancelAnimation();

CameraMoveBaseParams

모든 카메라 이동 메서드가 공통으로 사용하는 파라미터입니다.

파라미터	타입	기본값	설명
`duration`	`number`	`700`	애니메이션 지속 시간 (ms)
`easing`	`CameraAnimationEasing`	`'EaseOut'`	애니메이션 이징
`pivot`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	카메라 피벗 포인트

CameraAnimationEasing

값	설명
`'EaseOut'`	부드럽게 감속 (기본, 가까운 거리에 적합)
`'EaseIn'`	부드럽게 가속 (가까운 거리에 적합)
`'Linear'`	일정한 속도
`'Fly'`	축소 후 확대 (먼 거리 이동에 적합)
`'None'`	애니메이션 없이 즉시 이동

선언형 카메라 제어 (Props)

Ref를 사용하지 않고 Props로도 카메라를 제어할 수 있습니다.

const [camera, setCamera] = useState<Camera>({
  latitude: 37.5666102,
  longitude: 126.9783881,
  zoom: 14,
  tilt: 0,
  bearing: 0,
});

<NaverMapView
  camera={camera}
  animationDuration={700}
  animationEasing="EaseOut"
  onCameraChanged={(params) => {
    // 카메라가 변경될 때마다 state 업데이트 (선택적)
  }}
/>

// 버튼 클릭으로 카메라 이동
<Button
  title="부산으로 이동"
  onPress={() => setCamera({
    latitude: 35.1795543,
    longitude: 129.0756416,
    zoom: 13,
    tilt: 0,
    bearing: 0,
  })}
/>

camera와 animationDuration을 함께 사용하면 카메라 변경 시 애니메이션이 적용됩니다. animationDuration이 0이면 애니메이션 없이 즉시 이동합니다.

좌표 변환

screenToCoordinate

화면 좌표(dp/pt)를 위경도 좌표로 변환합니다.

const handleScreenToCoord = async () => {
  const result = await mapRef.current?.screenToCoordinate({
    screenX: 200,
    screenY: 300,
  });

  if (result?.isValid) {
    console.log(`위도: ${result.latitude}, 경도: ${result.longitude}`);
  }
};

coordinateToScreen

위경도 좌표를 화면 좌표(dp/pt)로 변환합니다.

const handleCoordToScreen = async () => {
  const result = await mapRef.current?.coordinateToScreen({
    latitude: 37.5666102,
    longitude: 126.9783881,
  });

  if (result?.isValid) {
    console.log(`화면 X: ${result.screenX}, 화면 Y: ${result.screenY}`);
  }
};

isValid가 false이면 해당 좌표가 현재 화면 범위를 벗어난 것입니다. 이 경우 latitude, longitude, screenX, screenY는 모두 0을 반환합니다.

카메라 이벤트

<NaverMapView
  onCameraChanged={({ latitude, longitude, zoom, tilt, bearing, reason, region }) => {
    // 카메라가 변경될 때마다 호출
    // reason: 'Developer' | 'Gesture' | 'Control' | 'Location'
    console.log(`카메라 변경 이유: ${reason}`);
  }}
  onCameraIdle={({ latitude, longitude, zoom, tilt, bearing, region }) => {
    // 카메라 이동이 완전히 멈췄을 때 호출
    console.log(`카메라 정지: ${latitude}, ${longitude}, 줌: ${zoom}`);
  }}
/>

실전 예제: 마커 탭 시 카메라 이동

import React, { useRef } from 'react';
import { NaverMapView, NaverMapMarkerOverlay, type NaverMapViewRef } from '@boostbrothers/react-native-naver-map';

const locations = [
  { id: '1', latitude: 37.5666102, longitude: 126.9783881, name: '서울 시청' },
  { id: '2', latitude: 35.1795543, longitude: 129.0756416, name: '부산 시청' },
  { id: '3', latitude: 35.8714354, longitude: 128.6014079, name: '대구 시청' },
];

export default function CameraControlExample() {
  const mapRef = useRef<NaverMapViewRef>(null);

  const moveToLocation = (latitude: number, longitude: number) => {
    mapRef.current?.animateCameraTo({
      latitude,
      longitude,
      zoom: 15,
      duration: 1000,
      easing: 'Fly',
    });
  };

  return (
    <NaverMapView
      ref={mapRef}
      style={{ flex: 1 }}
      initialCamera={{ latitude: 36.5, longitude: 127.5, zoom: 7 }}
    >
      {locations.map((loc) => (
        <NaverMapMarkerOverlay
          key={loc.id}
          latitude={loc.latitude}
          longitude={loc.longitude}
          caption={{ text: loc.name }}
          onTap={() => moveToLocation(loc.latitude, loc.longitude)}
        />
      ))}
    </NaverMapView>
  );
}

카메라 제어

NaverMapViewRef를 통해 명령형으로 카메라를 제어하고 좌표를 변환하는 방법을 설명합니다.

Ref 설정

import React, { useRef } from 'react';
import { NaverMapView, type NaverMapViewRef } from '@boostbrothers/react-native-naver-map';

export default function MapScreen() {
  const mapRef = useRef<NaverMapViewRef>(null);

  return (
    <NaverMapView
      ref={mapRef}
      style={{ flex: 1 }}
      initialCamera={{
        latitude: 37.5666102,
        longitude: 126.9783881,
        zoom: 14,
      }}
    />
  );
}

카메라 이동 메서드

animateCameraTo

특정 좌표로 카메라를 이동합니다.

mapRef.current?.animateCameraTo({
  latitude: 37.5666102,
  longitude: 126.9783881,
  zoom: 14,          // 선택 (미설정 시 현재 줌 유지)
  duration: 700,     // ms (기본: 700)
  easing: 'EaseOut', // 기본: 'EaseOut'
  pivot: { x: 0.5, y: 0.5 }, // 기본: 중앙
});

animateCameraBy

현재 위치에서 화면 좌표 델타값만큼 카메라를 이동합니다.

// 화면을 오른쪽으로 100dp, 아래로 50dp 이동
mapRef.current?.animateCameraBy({
  x: 100,
  y: 50,
  duration: 500,
  easing: 'EaseOut',
});

animateRegionTo

특정 Region(영역)이 화면에 완전히 보이는 줌 레벨로 카메라를 이동합니다.

mapRef.current?.animateRegionTo({
  latitude: 37.50,
  longitude: 126.90,
  latitudeDelta: 0.1,
  longitudeDelta: 0.1,
  duration: 700,
  easing: 'EaseOut',
});

animateCameraWithTwoCoords

두 좌표가 모두 화면에 보이는 최대 줌 레벨로 카메라를 이동합니다.

mapRef.current?.animateCameraWithTwoCoords({
  coord1: { latitude: 37.50, longitude: 126.90 },
  coord2: { latitude: 37.60, longitude: 127.00 },
  duration: 700,
  easing: 'Fly',
  pivot: { x: 0.5, y: 0.5 },
});

cancelAnimation

진행 중인 카메라 애니메이션을 즉시 취소합니다.

mapRef.current?.cancelAnimation();

CameraMoveBaseParams

모든 카메라 이동 메서드가 공통으로 사용하는 파라미터입니다.

파라미터	타입	기본값	설명
`duration`	`number`	`700`	애니메이션 지속 시간 (ms)
`easing`	`CameraAnimationEasing`	`'EaseOut'`	애니메이션 이징
`pivot`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	카메라 피벗 포인트

CameraAnimationEasing

값	설명
`'EaseOut'`	부드럽게 감속 (기본, 가까운 거리에 적합)
`'EaseIn'`	부드럽게 가속 (가까운 거리에 적합)
`'Linear'`	일정한 속도
`'Fly'`	축소 후 확대 (먼 거리 이동에 적합)
`'None'`	애니메이션 없이 즉시 이동

선언형 카메라 제어 (Props)

Ref를 사용하지 않고 Props로도 카메라를 제어할 수 있습니다.

const [camera, setCamera] = useState<Camera>({
  latitude: 37.5666102,
  longitude: 126.9783881,
  zoom: 14,
  tilt: 0,
  bearing: 0,
});

<NaverMapView
  camera={camera}
  animationDuration={700}
  animationEasing="EaseOut"
  onCameraChanged={(params) => {
    // 카메라가 변경될 때마다 state 업데이트 (선택적)
  }}
/>

// 버튼 클릭으로 카메라 이동
<Button
  title="부산으로 이동"
  onPress={() => setCamera({
    latitude: 35.1795543,
    longitude: 129.0756416,
    zoom: 13,
    tilt: 0,
    bearing: 0,
  })}
/>

camera와 animationDuration을 함께 사용하면 카메라 변경 시 애니메이션이 적용됩니다. animationDuration이 0이면 애니메이션 없이 즉시 이동합니다.

좌표 변환

screenToCoordinate

화면 좌표(dp/pt)를 위경도 좌표로 변환합니다.

const handleScreenToCoord = async () => {
  const result = await mapRef.current?.screenToCoordinate({
    screenX: 200,
    screenY: 300,
  });

  if (result?.isValid) {
    console.log(`위도: ${result.latitude}, 경도: ${result.longitude}`);
  }
};

coordinateToScreen

위경도 좌표를 화면 좌표(dp/pt)로 변환합니다.

const handleCoordToScreen = async () => {
  const result = await mapRef.current?.coordinateToScreen({
    latitude: 37.5666102,
    longitude: 126.9783881,
  });

  if (result?.isValid) {
    console.log(`화면 X: ${result.screenX}, 화면 Y: ${result.screenY}`);
  }
};

isValid가 false이면 해당 좌표가 현재 화면 범위를 벗어난 것입니다. 이 경우 latitude, longitude, screenX, screenY는 모두 0을 반환합니다.

카메라 이벤트

<NaverMapView
  onCameraChanged={({ latitude, longitude, zoom, tilt, bearing, reason, region }) => {
    // 카메라가 변경될 때마다 호출
    // reason: 'Developer' | 'Gesture' | 'Control' | 'Location'
    console.log(`카메라 변경 이유: ${reason}`);
  }}
  onCameraIdle={({ latitude, longitude, zoom, tilt, bearing, region }) => {
    // 카메라 이동이 완전히 멈췄을 때 호출
    console.log(`카메라 정지: ${latitude}, ${longitude}, 줌: ${zoom}`);
  }}
/>

실전 예제: 마커 탭 시 카메라 이동

import React, { useRef } from 'react';
import { NaverMapView, NaverMapMarkerOverlay, type NaverMapViewRef } from '@boostbrothers/react-native-naver-map';

const locations = [
  { id: '1', latitude: 37.5666102, longitude: 126.9783881, name: '서울 시청' },
  { id: '2', latitude: 35.1795543, longitude: 129.0756416, name: '부산 시청' },
  { id: '3', latitude: 35.8714354, longitude: 128.6014079, name: '대구 시청' },
];

export default function CameraControlExample() {
  const mapRef = useRef<NaverMapViewRef>(null);

  const moveToLocation = (latitude: number, longitude: number) => {
    mapRef.current?.animateCameraTo({
      latitude,
      longitude,
      zoom: 15,
      duration: 1000,
      easing: 'Fly',
    });
  };

  return (
    <NaverMapView
      ref={mapRef}
      style={{ flex: 1 }}
      initialCamera={{ latitude: 36.5, longitude: 127.5, zoom: 7 }}
    >
      {locations.map((loc) => (
        <NaverMapMarkerOverlay
          key={loc.id}
          latitude={loc.latitude}
          longitude={loc.longitude}
          caption={{ text: loc.name }}
          onTap={() => moveToLocation(loc.latitude, loc.longitude)}
        />
      ))}
    </NaverMapView>
  );
}

카메라 제어

카메라 제어

Ref 설정

카메라 이동 메서드

animateCameraTo

animateCameraBy

animateRegionTo

animateCameraWithTwoCoords

cancelAnimation

CameraMoveBaseParams

CameraAnimationEasing

선언형 카메라 제어 (Props)

좌표 변환

screenToCoordinate

coordinateToScreen

카메라 이벤트

실전 예제: 마커 탭 시 카메라 이동

On this page

카메라 제어

카메라 제어

Ref 설정

카메라 이동 메서드

animateCameraTo

animateCameraBy

animateRegionTo

animateCameraWithTwoCoords

cancelAnimation

CameraMoveBaseParams

CameraAnimationEasing

선언형 카메라 제어 (Props)

좌표 변환

screenToCoordinate

coordinateToScreen

카메라 이벤트

실전 예제: 마커 탭 시 카메라 이동

On this page