NaverMapMarkerOverlay

지도 위의 특정 좌표에 마커(핀)를 표시합니다. 아이콘 이미지, 캡션, 서브캡션을 지원하며, 커스텀 React 뷰를 마커 아이콘으로 사용할 수도 있습니다.

임포트

import { NaverMapMarkerOverlay } from '@boostbrothers/react-native-naver-map';

기본 사용법

<NaverMapView style={{ flex: 1 }} initialCamera={{ latitude: 37.5666102, longitude: 126.9783881, zoom: 14 }}>
  <NaverMapMarkerOverlay
    latitude={37.5666102}
    longitude={126.9783881}
    image={{ symbol: 'green' }}
    caption={{ text: '서울 시청' }}
    onTap={() => console.log('마커 탭')}
  />
</NaverMapView>

Props

위치 (필수)

Prop	타입	설명
`latitude`	`number`	위도 (필수)
`longitude`	`number`	경도 (필수)

기본 오버레이 Props (BaseOverlayProps)

Prop	타입	기본값	설명
`zIndex`	`number`	`0`	보조 Z 인덱스 (같은 globalZIndex 내 우선순위)
`globalZIndex`	`number`	`200000`	전역 Z 인덱스
`isHidden`	`boolean`	-	숨김 여부
`minZoom`	`number`	`0`	표시 최소 줌 레벨
`maxZoom`	`number`	`21`	표시 최대 줌 레벨
`isMinZoomInclusive`	`boolean`	-	최소 줌 레벨 포함 여부
`isMaxZoomInclusive`	`boolean`	-	최대 줌 레벨 포함 여부
`onTap`	`() => void`	-	마커 탭 이벤트

아이콘

Prop	타입	기본값	설명
`image`	`MapImageProp`	`{ symbol: 'green' }`	마커 아이콘 이미지
`width`	`number`	이미지 크기	마커 너비
`height`	`number`	이미지 크기	마커 높이
`anchor`	`Point`	`{ x: 0.5, y: 1 }`	앵커 포인트 (0~1, 왼쪽위가 0,0)
`angle`	`number`	`0`	아이콘 회전 각도 (시계 방향)
`alpha`	`number`	`1`	불투명도 (0~1)
`tintColor`	`ColorValue`	-	아이콘에 덧입힐 색상

width와 height prop을 항상 명시하는 것을 권장합니다. 특히 require()로 로컬 이미지를 사용할 때 debug/release 빌드 간 크기 차이가 발생할 수 있습니다.

동작

Prop	타입	기본값	설명
`isFlatEnabled`	`boolean`	`false`	아이콘을 지도에 눕힘 (지도 회전/기울임 따라감)
`isIconPerspectiveEnabled`	`boolean`	`false`	아이콘 원근 효과
`isHideCollidedSymbols`	`boolean`	`false`	겹치는 지도 심벌 숨김
`isHideCollidedMarkers`	`boolean`	`false`	겹치는 다른 마커 숨김
`isHideCollidedCaptions`	`boolean`	`false`	겹치는 마커의 캡션만 숨김
`isForceShowIcon`	`boolean`	`false`	다른 마커와 겹쳐도 아이콘 무조건 표시

캡션 (CaptionType)

caption={{
  text: '마커 텍스트',
  align: 'Bottom',     // 기본값
  textSize: 12,        // 기본값
  color: 'black',      // 기본값
  haloColor: 'transparent', // 기본값
  offset: 0,
  requestedWidth: 0,
  minZoom: 0,
  maxZoom: 21,
}}

속성	타입	기본값	설명
`text`	`string`	-	캡션 텍스트 (빈 문자열이면 미표시)
`align`	`Align`	`'Bottom'`	캡션 정렬 방향
`textSize`	`number`	`12`	텍스트 크기
`color`	`ColorValue`	`'black'`	텍스트 색상
`haloColor`	`ColorValue`	`'transparent'`	텍스트 외곽선 색상
`offset`	`number`	-	아이콘과 캡션 간 거리
`requestedWidth`	`number`	`0`	캡션 최대 너비 (0 = 제한 없음)
`minZoom`	`number`	`0`	캡션 표시 최소 줌 레벨
`maxZoom`	`number`	`21`	캡션 표시 최대 줌 레벨

서브캡션 (SubCaptionType)

subCaption={{
  text: '서브 텍스트',
  textSize: 10,
  color: 'black',
  haloColor: 'transparent',
  requestedWidth: 0,
  minZoom: 0,
  maxZoom: 21,
}}

속성	타입	기본값	설명
`text`	`string`	-	서브캡션 텍스트
`textSize`	`number`	`10`	텍스트 크기
`color`	`ColorValue`	`'black'`	텍스트 색상
`haloColor`	`ColorValue`	`'transparent'`	외곽선 색상
`requestedWidth`	`number`	`0`	최대 너비
`minZoom`	`number`	`0`	최소 줌 레벨
`maxZoom`	`number`	`21`	최대 줌 레벨

이미지 타입 (MapImageProp)

마커 이미지는 5가지 방식으로 지정할 수 있습니다.

1. 네이버 기본 심벌

image={{ symbol: 'green' }}

2. 로컬 리소스 (require)

image={require('./assets/marker.png')}

3. 네이티브 에셋

// iOS: main bundle의 image asset 이름
// Android: resources의 drawable 이름
image={{ assetName: 'my_marker_icon' }}

4. 네트워크 이미지

image={{ httpUri: 'https://example.com/marker.png' }}

5. 커스텀 React 뷰 (children)

<NaverMapMarkerOverlay
  latitude={37.5666102}
  longitude={126.9783881}
  width={80}
  height={40}
>
  <View
    key="marker-view"
    collapsable={false}
    style={{ width: 80, height: 40, backgroundColor: 'blue', borderRadius: 8 }}
  >
    <Text style={{ color: 'white', textAlign: 'center' }}>커스텀</Text>
  </View>
</NaverMapMarkerOverlay>

커스텀 React 뷰는 성능 비용이 높습니다. 대량의 마커에는 이미지 방식을 권장합니다. iOS New Architecture에서는 자식 뷰에 collapsable={false} 설정이 필요합니다. 마커 내용이 변경되면 최상위 자식의 key를 업데이트해야 합니다.

사용 예제

다양한 마커 스타일

<NaverMapView style={{ flex: 1 }} initialCamera={{ latitude: 37.5, longitude: 126.9, zoom: 12 }}>
  {/* 네이버 기본 심벌 */}
  <NaverMapMarkerOverlay
    latitude={37.5}
    longitude={126.9}
    image={{ symbol: 'red' }}
    caption={{ text: '빨간 마커', color: 'red' }}
  />

  {/* 로컬 이미지 */}
  <NaverMapMarkerOverlay
    latitude={37.51}
    longitude={126.91}
    image={require('./assets/custom-marker.png')}
    width={32}
    height={32}
    anchor={{ x: 0.5, y: 1 }}
  />

  {/* 네트워크 이미지 */}
  <NaverMapMarkerOverlay
    latitude={37.52}
    longitude={126.92}
    image={{ httpUri: 'https://example.com/pin.png' }}
    width={40}
    height={40}
    caption={{ text: '네트워크 이미지', align: 'Bottom' }}
    subCaption={{ text: '서브 텍스트' }}
  />

  {/* 회전 마커 */}
  <NaverMapMarkerOverlay
    latitude={37.53}
    longitude={126.93}
    image={{ symbol: 'blue' }}
    angle={45}
    caption={{ text: '45도 회전' }}
  />
</NaverMapView>

NaverMapMarkerOverlay

지도 위의 특정 좌표에 마커(핀)를 표시합니다. 아이콘 이미지, 캡션, 서브캡션을 지원하며, 커스텀 React 뷰를 마커 아이콘으로 사용할 수도 있습니다.

임포트

import { NaverMapMarkerOverlay } from '@boostbrothers/react-native-naver-map';

기본 사용법

<NaverMapView style={{ flex: 1 }} initialCamera={{ latitude: 37.5666102, longitude: 126.9783881, zoom: 14 }}>
  <NaverMapMarkerOverlay
    latitude={37.5666102}
    longitude={126.9783881}
    image={{ symbol: 'green' }}
    caption={{ text: '서울 시청' }}
    onTap={() => console.log('마커 탭')}
  />
</NaverMapView>

Props

위치 (필수)

Prop	타입	설명
`latitude`	`number`	위도 (필수)
`longitude`	`number`	경도 (필수)

기본 오버레이 Props (BaseOverlayProps)

Prop	타입	기본값	설명
`zIndex`	`number`	`0`	보조 Z 인덱스 (같은 globalZIndex 내 우선순위)
`globalZIndex`	`number`	`200000`	전역 Z 인덱스
`isHidden`	`boolean`	-	숨김 여부
`minZoom`	`number`	`0`	표시 최소 줌 레벨
`maxZoom`	`number`	`21`	표시 최대 줌 레벨
`isMinZoomInclusive`	`boolean`	-	최소 줌 레벨 포함 여부
`isMaxZoomInclusive`	`boolean`	-	최대 줌 레벨 포함 여부
`onTap`	`() => void`	-	마커 탭 이벤트

아이콘

Prop	타입	기본값	설명
`image`	`MapImageProp`	`{ symbol: 'green' }`	마커 아이콘 이미지
`width`	`number`	이미지 크기	마커 너비
`height`	`number`	이미지 크기	마커 높이
`anchor`	`Point`	`{ x: 0.5, y: 1 }`	앵커 포인트 (0~1, 왼쪽위가 0,0)
`angle`	`number`	`0`	아이콘 회전 각도 (시계 방향)
`alpha`	`number`	`1`	불투명도 (0~1)
`tintColor`	`ColorValue`	-	아이콘에 덧입힐 색상

width와 height prop을 항상 명시하는 것을 권장합니다. 특히 require()로 로컬 이미지를 사용할 때 debug/release 빌드 간 크기 차이가 발생할 수 있습니다.

동작

Prop	타입	기본값	설명
`isFlatEnabled`	`boolean`	`false`	아이콘을 지도에 눕힘 (지도 회전/기울임 따라감)
`isIconPerspectiveEnabled`	`boolean`	`false`	아이콘 원근 효과
`isHideCollidedSymbols`	`boolean`	`false`	겹치는 지도 심벌 숨김
`isHideCollidedMarkers`	`boolean`	`false`	겹치는 다른 마커 숨김
`isHideCollidedCaptions`	`boolean`	`false`	겹치는 마커의 캡션만 숨김
`isForceShowIcon`	`boolean`	`false`	다른 마커와 겹쳐도 아이콘 무조건 표시

캡션 (CaptionType)

caption={{
  text: '마커 텍스트',
  align: 'Bottom',     // 기본값
  textSize: 12,        // 기본값
  color: 'black',      // 기본값
  haloColor: 'transparent', // 기본값
  offset: 0,
  requestedWidth: 0,
  minZoom: 0,
  maxZoom: 21,
}}

속성	타입	기본값	설명
`text`	`string`	-	캡션 텍스트 (빈 문자열이면 미표시)
`align`	`Align`	`'Bottom'`	캡션 정렬 방향
`textSize`	`number`	`12`	텍스트 크기
`color`	`ColorValue`	`'black'`	텍스트 색상
`haloColor`	`ColorValue`	`'transparent'`	텍스트 외곽선 색상
`offset`	`number`	-	아이콘과 캡션 간 거리
`requestedWidth`	`number`	`0`	캡션 최대 너비 (0 = 제한 없음)
`minZoom`	`number`	`0`	캡션 표시 최소 줌 레벨
`maxZoom`	`number`	`21`	캡션 표시 최대 줌 레벨

서브캡션 (SubCaptionType)

subCaption={{
  text: '서브 텍스트',
  textSize: 10,
  color: 'black',
  haloColor: 'transparent',
  requestedWidth: 0,
  minZoom: 0,
  maxZoom: 21,
}}

속성	타입	기본값	설명
`text`	`string`	-	서브캡션 텍스트
`textSize`	`number`	`10`	텍스트 크기
`color`	`ColorValue`	`'black'`	텍스트 색상
`haloColor`	`ColorValue`	`'transparent'`	외곽선 색상
`requestedWidth`	`number`	`0`	최대 너비
`minZoom`	`number`	`0`	최소 줌 레벨
`maxZoom`	`number`	`21`	최대 줌 레벨

이미지 타입 (MapImageProp)

마커 이미지는 5가지 방식으로 지정할 수 있습니다.

1. 네이버 기본 심벌

image={{ symbol: 'green' }}

2. 로컬 리소스 (require)

image={require('./assets/marker.png')}

3. 네이티브 에셋

// iOS: main bundle의 image asset 이름
// Android: resources의 drawable 이름
image={{ assetName: 'my_marker_icon' }}

4. 네트워크 이미지

image={{ httpUri: 'https://example.com/marker.png' }}

5. 커스텀 React 뷰 (children)

<NaverMapMarkerOverlay
  latitude={37.5666102}
  longitude={126.9783881}
  width={80}
  height={40}
>
  <View
    key="marker-view"
    collapsable={false}
    style={{ width: 80, height: 40, backgroundColor: 'blue', borderRadius: 8 }}
  >
    <Text style={{ color: 'white', textAlign: 'center' }}>커스텀</Text>
  </View>
</NaverMapMarkerOverlay>

사용 예제

다양한 마커 스타일

<NaverMapView style={{ flex: 1 }} initialCamera={{ latitude: 37.5, longitude: 126.9, zoom: 12 }}>
  {/* 네이버 기본 심벌 */}
  <NaverMapMarkerOverlay
    latitude={37.5}
    longitude={126.9}
    image={{ symbol: 'red' }}
    caption={{ text: '빨간 마커', color: 'red' }}
  />

  {/* 로컬 이미지 */}
  <NaverMapMarkerOverlay
    latitude={37.51}
    longitude={126.91}
    image={require('./assets/custom-marker.png')}
    width={32}
    height={32}
    anchor={{ x: 0.5, y: 1 }}
  />

  {/* 네트워크 이미지 */}
  <NaverMapMarkerOverlay
    latitude={37.52}
    longitude={126.92}
    image={{ httpUri: 'https://example.com/pin.png' }}
    width={40}
    height={40}
    caption={{ text: '네트워크 이미지', align: 'Bottom' }}
    subCaption={{ text: '서브 텍스트' }}
  />

  {/* 회전 마커 */}
  <NaverMapMarkerOverlay
    latitude={37.53}
    longitude={126.93}
    image={{ symbol: 'blue' }}
    angle={45}
    caption={{ text: '45도 회전' }}
  />
</NaverMapView>

NaverMapMarkerOverlay

NaverMapMarkerOverlay

임포트

기본 사용법

Props

위치 (필수)

기본 오버레이 Props (BaseOverlayProps)

아이콘

동작

캡션 (CaptionType)

서브캡션 (SubCaptionType)

이미지 타입 (MapImageProp)

1. 네이버 기본 심벌

2. 로컬 리소스 (require)

3. 네이티브 에셋

4. 네트워크 이미지

5. 커스텀 React 뷰 (children)

사용 예제

다양한 마커 스타일

목차

NaverMapMarkerOverlay

NaverMapMarkerOverlay

임포트

기본 사용법

Props

위치 (필수)

기본 오버레이 Props (BaseOverlayProps)

아이콘

동작

캡션 (CaptionType)

서브캡션 (SubCaptionType)

이미지 타입 (MapImageProp)

1. 네이버 기본 심벌

2. 로컬 리소스 (require)

3. 네이티브 에셋

4. 네트워크 이미지

5. 커스텀 React 뷰 (children)

사용 예제

다양한 마커 스타일

목차