logo
Tutorials Examples naver map js api v3 네이버 지도 API Marker

Class: naver.maps.Marker

naver.maps. Marker

Marker 클래스는 지도 위에 올리는 마커를 정의합니다.

new naver.maps.Marker(options)

Parameters
Name Type Description
options MarkerOptions

마커 옵션. 이때 position 속성은 반드시 설정해야 합니다.

Tutorials

Extends

Methods

<abstract> draw()

지도에 오버레이를 그릴 때 호출됩니다. 지도의 창(pane) 위에 원하는 오버레이를 그리고, 배치하는 기능을 구현합니다.

Inherited From
Overrides

getAnimation()

마커의 애니메이션을 반환합니다.

Returns
Type Description
naver.maps.Animation

Animation 객체

getClickable()

마커의 클릭 허용 여부를 반환합니다.

Returns
Type Description
boolean

마커 클릭 허용 여부

getContainerTopLeft()

현재 지도 컨테이너 요소의 left, top 픽셀값을 반환합니다.

Inherited From
Returns
Type
naver.maps.Point

getCursor()

마우스 오버 시 반영되는 마우스 포인터 모양을 반환합니다.

Returns
Type Description
string

마우스 포인터 모양

getDraggable()

마커의 드래그 허용 여부를 반환합니다.

Returns
Type Description
boolean

마커 드래그 허용 여부

getDrawingRect()

마커가 그려지는 영역의 경계 좌표를 반환합니다. 기준 좌표는 세계 좌표를 화면 픽셀로 변환한 픽셀 좌표입니다. 좌표 체계에 대한 자세한 설명은 지도 투영의 좌표 체계를 참고합니다.

Returns
Type Description
Bounds

경계 좌표

getIcon()

마커의 모양을 표현하는 아이콘 객체를 반환합니다.

Returns
Type Description
ImageIcon | SymbolIcon | HtmlIcon

아이콘 객체

getMap()

현재 오버레이가 추가된 Map 객체를 반환합니다.

Inherited From
Returns
Type Description
naver.maps.Map | null

Map 객체

getOptions(key)

마커 옵션을 반환합니다.

Parameters
Name Type Argument Description
key string <optional>

반환받을 옵션 이름

Returns
Type Description
MarkerOptions

마커 옵션

getPanes()

오버레이 요소를 추가할 수 있는 지도의 창(pane) 요소 집합 객체를 반환합니다.

Inherited From
Returns
Type Description
MapPanes

MapPanes 객체

getPosition()

마커의 위치를 반환합니다.

Returns
Type Description
Coord

마커 위치

getProjection()

지도 좌표, 화면 좌표 간에 변환할 수 있는 MapSystemProjection 객체를 반환합니다. 반환된 객체를 이용해 지도 위의 원하는 위치에 오버레이를 배치할 수 있습니다.

Inherited From
Returns
Type Description
naver.maps.MapSystemProjection

MapSystemProjection 객체

getShape()

마커의 이벤트 영역 셰이프를 반환합니다.

Returns
Type Description
MarkerShape

마커 셰이프 객체

getTitle()

마커의 타이틀을 반환합니다. 타이틀은 마커에 마우스 포인터를 올리면 나타나는 툴팁의 문자열입니다.

Returns
Type Description
string

마커 타이틀

getVisible()

마커의 노출 허용 여부를 반환합니다.

Returns
Type Description
boolean

마커 노출 허용 여부

getZIndex()

마커의 쌓임 순서를 반환합니다.

Returns
Type Description
number

마커의 쌓임 순서

<abstract> onAdd()

지도에 오버레이를 추가할 때 호출됩니다. 오버레이 요소를 Map 객체의 창(pane) 요소에 추가하는 기능을 구현합니다. MapPanes 중 적합한 창 요소에 오버레이 요소를 추가합니다.

Inherited From
Overrides

<abstract> onRemove()

지도에서 오버레이를 제거할 때 호출됩니다. 오버레이 요소를 Map 객체의 창(pane) 요소에서 제거하는 기능을 구현합니다.

Inherited From
Overrides

setAnimation(animation)

마커의 애니메이션을 설정합니다. 동작하고 있는 애니메이션이 있다면 중지하고, 설정한 애니메이션을 바로 시작합니다.
제공하는 애니메이션은 DROP, BOUNCE입니다.

Parameters
Name Type Description
animation naver.maps.Animation

마커의 애니메이션. 이 값이 null이면 애니메이션을 중지합니다.

setClickable(clickable)

마커의 클릭 허용 여부를 설정합니다.

Parameters
Name Type Description
clickable boolean

클릭 허용 여부. 이 값이 true이면 마커는 마우스, 터치 이벤트를 받을 수 있고, 마우스 오버 시 cursor 속성에 따라 포인터 모양을 반영합니다.
false일 경우 이벤트를 받지 않으며 마우스 오버 시에도 포인터 모양이 변하지 않습니다.

Fires
  • clickable_changed

setCursor(cursor)

마우스 오버 시 포인터의 모양을 설정하는 CSS cursor값을 설정합니다.

Parameters
Name Type Description
cursor string

마우스 포인터 모양

Fires
  • cursor_changed

setDraggable(draggable)

마커의 드래그 허용 여부를 설정합니다.

Parameters
Name Type Description
draggable boolean

마커의 드래그 허용 여부

Fires
  • draggable_changed

setIcon(icon)

마커의 모양을 설정합니다. 단, ImageIcon 객체는 마커 생성과 동시에 호출하면 MarkerOptions 객체의 icon 옵션이 적용됩니다.

Parameters
Name Type Description
icon string | ImageIcon | SymbolIcon | HtmlIcon

아이콘 객체

Fires
  • icon_changed

setMap(map)

오버레이를 지도에 추가합니다. 인수로 null을 전달하면 오버레이를 지도에서 제거합니다.

Parameters
Name Type Description
map naver.maps.Map | null

오버레이를 추가할 Map 객체

Inherited From

setOptions(options)

마커 옵션을 설정합니다. 설정한 옵션만 반영됩니다.

Parameters
Name Type Description
options MarkerOptions

마커 옵션

Fires
  • clickable_changed
  • cursor_changed
  • draggable_changed
  • icon_changed
  • position_changed
  • shape_changed
  • title_changed
  • visible_changed
  • zIndex_changed

setPosition(position)

마커의 위치를 설정합니다.

Parameters
Name Type Description
position Coord | CoordLiteral

마커 위치

Fires
  • position_changed

setShape(shape)

마커의 이벤트 영역을 설정합니다.

Parameters
Name Type Description
shape MarkerShape

마커 셰이프 객체

Fires
  • shape_changed

setTitle(title)

마커의 타이틀을 설정합니다. 타이틀은 마커에 마우스 포인터를 올리면 나타나는 툴팁의 문자열입니다.

Parameters
Name Type Description
title string

마커 타이틀

Fires
  • title_changed

setVisible(visible)

마커의 노출 허용 여부를 설정합니다.

Parameters
Name Type Description
visible boolean

마커 노출 허용 여부

Fires
  • visible_changed

setZIndex(zIndex)

마커의 쌓임 순서를 설정합니다.

Parameters
Name Type Description
zIndex number

마커의 쌓임 순서

Fires
  • zIndex_changed

Type Definitions


HtmlIcon

HtmlIcon 객체는 HTML 마커에서 사용하는 아이콘을 정의합니다. HTML 마커는 HTML 문자열 또는 HTML 요소를 사용하는 마커입니다.

Type:
Properties
Name Type Argument Description
content string | HTMLElement

마커의 아이콘으로 사용할 HTML 마크업 또는 HTML 요소입니다. 이 속성은 반드시 설정해야 합니다.

size naver.maps.Size | SizeLiteral <optional>

화면에 나타나는 마커의 크기입니다.

anchor naver.maps.Point | PointLiteral | naver.maps.Position <optional>

지도 위에 놓이는 마커의 위치와 일치시킬 아이콘의 기준 위치입니다. 기본값은 (0, 0)으로, 마커 기준 왼쪽 위 모서리가 마커의 위치입니다. Position 사용 시 Size값은 필수입니다.


ImageIcon

ImageIcon 객체는 이미지 마커에서 사용하는 아이콘을 정의합니다.

Type:
Properties
Name Type Argument Default Description
url string

마커의 아이콘으로 사용할 이미지의 URL입니다.

size naver.maps.Size | SizeLiteral <optional>

화면에 나타나는 마커의 크기입니다. 이 속성을 설정하지 않으면 이미지의 크기로 설정합니다.

scaledSize naver.maps.Size | SizeLiteral <optional>

아이콘 이미지의 크기입니다. 이 속성을 설정하지 않으면 이미지의 크기로 설정합니다. 이 속성을 이용하면 레티나 디스플레이에 대응할 수 있습니다.

예를 들어, window.deviceRatio2인 디바이스이고 이미지 크기가 200 x 100인 경우, 이 속성을 100 x 50으로 설정하면 실제 이미지 크기보다 2배 줄여서 보여줌으로써 레티나 디스플레이에 대응할 수 있습니다.

origin naver.maps.Point | PointLiteral <optional>
(x: 0, y: 0)

스프라이트 이미지의 아이콘을 사용할 때 이미지의 원점입니다. 즉, 이 원점 위치로부터 size 속성의 값만큼 화면에 노출됩니다.

anchor naver.maps.Point | PointLiteral | naver.maps.Position <optional>

지도 위에 놓이는 마커의 위치와 일치시킬 아이콘의 기준 위치입니다. 이 속성을 설정하지 않으면 아이콘의 아래쪽 가운데로 설정합니다. Position 사용 시 Size값은 필수입니다.


MarkerOptions

MarkerOptions 객체는 Marker를 정의하는 옵션을 나타냅니다.

Type:
Properties
Name Type Argument Default Description
animation naver.maps.Animation <optional>

마커가 지도에 추가될 때 시작할 애니메이션입니다.

map naver.maps.Map

마커를 표시할 Map 객체입니다.

position Coord | CoordLiteral

마커의 위치를 나타내는 지도 좌표입니다.

icon string | ImageIcon | SymbolIcon | HtmlIcon <optional>

마커의 모양입니다. 이 속성을 설정하지 않으면 기본 아이콘으로 설정합니다. 문자열로 입력할 때는 마커의 아이콘으로 사용할 이미지의 URL을 입력합니다.

shape MarkerShape <optional>

마커의 인터랙션 영역입니다.

title string <optional>
null

마커에 마우스 오버 시 나타나는 툴팁 문자열입니다. 이 속성을 설정하지 않거나 빈 문자열로 설정하면 툴팁을 노출하지 않습니다.

cursor string <optional>
pointer

마커에 마우스 오버 시 나타나는 포인터 모양입니다.

clickable boolean <optional>
true

마커의 클릭 허용 여부입니다. 이 값이 false이면 마커는 사용자 인터랙션을 받지 않습니다. 또한 cursor 속성값도 반영되지 않습니다.

draggable boolean <optional>
false

마커의 드래그 허용 여부입니다. 이 속성은 clickable 속성보다 우선합니다. 즉, clickable 속성이 false라도 이 값이 true이면 클릭 등의 사용자 인터랙션을 받습니다.

visible boolean <optional>
true

마커의 노출 허용 여부입니다.

zIndex number <optional>

마커의 쌓임 순서입니다.


MarkerShape

MarkerShape 객체는 마커의 인터랙션 영역을 정의합니다.

일반적으로 이미지 또는 심벌 아이콘을 사용했을 때 클릭할 수 있는 영역은 다음 그림과 같이 사각형의 아이콘 크기로 설정됩니다. 그러나 이 객체를 이용하면 마커 모양대로 클릭할 수 있는 영역을 설정할 수 있습니다.
marker-shape

Type:
Properties
Name Type Description
coords array

인터랙션 영역을 정의하는 도형의 좌표입니다.

type string

인터랙션 영역을 정의하는 도형의 유형입니다.


SymbolIcon

SymbolIcon 객체는 심벌 마커에서 사용하는 아이콘을 정의합니다. 마커의 위치 (x: 0, y: 0)를 기준으로 폴리곤 좌표를 설정해 원하는 모양의 아이콘을 생성할 수 있습니다.

Type:
Properties
Name Type Argument Default Description
path naver.maps.SymbolPath | Array.<naver.maps.Point> | Array.<PointLiteral>

마커 아이콘으로 사용할 벡터 폴리곤 좌표입니다. naver.maps.SymbolPath에서 미리 정의된 path를 사용할 수 있습니다.

style naver.maps.SymbolStyle <optional>

도형 아이콘의 스타일입니다. path 속성을 naver.maps.SymbolPath로 사용하는 경우 생략할 수 있습니다.

radius number <optional>
10

원 아이콘을 그리는 경우 원의 반지름을 정의합니다.

fillColor string <optional>

폴리곤 배경색입니다. CSS 색상 표현법으로 설정합니다.

fillOpacity number <optional>
1

폴리곤 배경색의 불투명도입니다. 값의 범위는 0~1입니다.

strokeColor string <optional>

폴리곤 선의 색상입니다. CSS 색상 표현법으로 설정합니다.

strokeStyle string <optional>
solid

폴리곤 선의 스타일입니다.

  • solid
  • shortdash
  • shortdot
  • shortdashdot
  • shortdashdotdot
  • dot
  • dash
  • longdash
  • dashdot
  • longdashdot
  • longdashdotdot
strokeWeight number <optional>
1

폴리곤 선의 두께입니다.

strokeOpacity number <optional>
1

폴리곤 선의 불투명도입니다. 값의 범위는 0~1입니다.

anchor naver.maps.Point | PointLiteral | naver.maps.Position <optional>
naver.maps.Position.BOTTOM_CENTER

지도 위에 놓이는 마커의 위치와 일치시킬 아이콘의 기준 위치입니다. Position 사용 시 Size값은 필수입니다.

Events

icon_loaded

이미지 아이콘 로드가 완료되면 이벤트가 발생합니다.

Parameters
Name Type Description
marker naver.maps.Marker

로드된 아이콘의 마커