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

Class: naver.maps.Map

naver.maps. Map

Map 클래스는 애플리케이션에서 지도 인스턴스를 정의합니다. 이 객체를 생성함으로써 개발자는 지정한 DOM 요소에 지도를 삽입할 수 있습니다.

new naver.maps.Map(mapDiv, mapOptions)

Parameters
Name Type Description
mapDiv string | HTMLElement

지도를 삽입할 HTML 요소 또는 HTML 요소의 id

mapOptions naver.maps.MapOptions

지도의 옵션 객체

Properties
Name Type Description
controls naver.maps.KVOArray

사전에 정의된 지도 내의 위치별로 지도 컨트롤의 인스턴스를 포함하는 객체입니다.

사용자 정의 컨트롤을 이 속성 내 특정 위치에 추가함으로써 사용자 정의 컨트롤을 지도에 추가할 수 있습니다.

data naver.maps.Data

데이터 레이어를 정의하는 Data 객체입니다.

layers LayerRegistry

지도 레이어의 컬렉션을 포함하는 객체입니다.

mapTypes naver.maps.MapTypeRegistry

지도 유형의 컬렉션을 포함하는 객체입니다.

mapSystemProjection naver.maps.MapSystemProjection

프로젝션 객체입니다.

지도 좌표와 세계 좌표, 화면 픽셀 좌표 간 좌표를 변환할 수 있는 메서드를 제공합니다.

Tutorials

Extends

Methods

addPane(name, elementOrZIndex)

사용자 정의 창(pane)을 추가합니다.

Parameters
Name Type Description
name string

창의 이름

elementOrZIndex HTMLElement | number

창 HTML 요소 또는 zIndex값

autoResize()

지도 화면의 크기를 자동으로 재설정합니다.
단, 지도 DOM 요소의 CSS 크기에 따라 지도 크기가 자동으로 조정될 때만 동작합니다.

Fires

destroy()

모든 이벤트 및 DOM 요소를 포함한 지도를 안전하게 제거합니다.

fitBounds(bounds, FitBoundsOptions)

지정한 좌표 경계를 포함하는 위치로 지도를 이동합니다.

지도 좌표의 배열을 지정하면 좌표 경계를 판단하여 지도를 이동합니다.

Parameters
Name Type Argument Description
bounds Bounds | BoundsLiteral | ArrayOfCoords | ArrayOfCoordsLiteral

좌표 경계 또는 좌표의 배열

FitBoundsOptions FitBoundsOptions <optional>

좌표 경계를 확장하기 위한 Margin 값.

{ top: 10, right: 10, bottom: 10, left: 10, maxZoom: 10 } 형태로 좌표 경계를 확장하기 위한 픽셀 단위의 여백값입니다.
left 값이 10이면 왼쪽 여백이 5px 증가합니다. (센터 좌표가 왼쪽으로 5px 이동)

Fires

getBounds()

지도 화면의 좌표 경계를 반환합니다.

Returns
Type Description
Bounds

현재 지도의 좌표 경계

getCenter()

지도의 중심 좌표를 반환합니다.

Returns
Type Description
Coord

지도의 중심 좌표

getCenterPoint()

지도의 중심 좌표를 세계 좌표로 변환한 결과를 반환합니다.

Returns
Type Description
Coord

지도의 중심 세계 좌표

getElement()

지도의 HTML 요소를 반환합니다.

Returns
Type Description
HTMLElement

현재 지도의 HTML 요소

getMapTypeId()

현재 지도 유형의 id를 반환합니다.

Returns
Type Description
string

지도 유형의 id

getMaxZoom()

지도의 최대 줌 레벨을 반환합니다.

Returns
Type Description
number

지도의 최대 줌 레벨

getMinZoom()

지도의 최소 줌 레벨을 반환합니다.

Returns
Type Description
number

지도의 최소 줌 레벨

getOptions(key)

지도의 모든 옵션 또는 특정 옵션의 값을 반환합니다.

Parameters
Name Type Argument Description
key string <optional>

가져올 옵션의 이름

Returns
Type Description
any

모든 옵션 또는 특정 key에 해당되는 옵션의 값

getPanes()

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

Returns
Type Description
MapPanes

창 요소의 집합 객체

getPrimitiveProjection()

지도 유형의 투영(projection)을 반환합니다.

Returns
Type Description
naver.maps.Projection

지도 유형의 원본 투영 객체

getProjection()

지도의 투영을 반환합니다.

Returns
Type Description
naver.maps.MapSystemProjection

지도 투영 객체

getSize()

지도 화면의 크기를 반환합니다.

Returns
Type Description
naver.maps.Size

지도의 크기

getZoom()

지도의 줌 레벨을 반환합니다.

Returns
Type Description
number

지도의 줌 레벨

morph(coord, zoom, transitionOptions)

지정한 좌표와 줌 레벨을 사용하는 새로운 위치로 지도를 이동합니다. 이때, 이동 거리가 가깝다면 부드럽게 이동합니다.

Parameters
Name Type Argument Description
coord Coord | CoordLiteral

이동할 중심 좌표

zoom number <optional>

이동할 줌 레벨

transitionOptions TransitionOptions <optional>

이동 효과에 사용할 옵션

Fires

panBy(offset)

지정한 픽셀 좌표만큼 지도를 이동합니다.

Parameters
Name Type Description
offset naver.maps.Point | PointLiteral

이동할 픽셀 좌표

Fires

panTo(coord, transitionOptions)

지정한 좌표를 중심점으로 지도를 이동합니다. 이때, 이동 거리가 가깝다면 부드럽게 이동합니다.

Parameters
Name Type Description
coord Coord | CoordLiteral

중심 좌표

transitionOptions TransitionOptions

이동 효과에 사용할 옵션

Fires

panToBounds(bounds, transitionOptions, margin)

지정한 좌표 경계를 포함하는 위치로 지도를 부드럽게 이동합니다.

Parameters
Name Type Argument Description
bounds Bounds | BoundsLiteral

좌표 경계

transitionOptions TransitionOptions

이동 효과에 사용할 옵션

margin margin <optional>

좌표 경계를 확장하기 위한 값.

{ top: 10, right: 10, bottom: 10, left: 10 } 형태로 좌표 경계를 확장하기 위한 픽셀 단위의 여백값입니다.

Fires

refresh(noEffect)

지도를 새로 고칩니다.

Parameters
Name Type Argument Default Description
noEffect boolean <optional>
false

지도를 새로 고칠 때 페이드 인(fade in) 효과 적용 여부

Fires

removePane(name)

지정한 창을 지도에서 제거합니다.

Parameters
Name Type Description
name string

창의 이름

setCenter(center)

지정한 좌표로 지도의 중심점을 설정합니다.

Parameters
Name Type Description
center Coord | CoordLiteral

지도의 중심 좌표

Fires

setCenterPoint(point)

지정한 세계 좌표로 지도의 중심점을 설정합니다.

Parameters
Name Type Description
point naver.maps.Point | PointLiteral

지도의 중심 세계 좌표

Fires

setMapTypeId(mapTypeId)

지도 유형을 지정한 id로 설정합니다.

Parameters
Name Type Description
mapTypeId string

지도 유형의 id

Fires

setOptions(newOptionsOrKey, value)

지도의 옵션을 변경하거나 새로 설정합니다.

Parameters
Name Type Argument Description
newOptionsOrKey object | string

지도의 옵션 객체 또는 특정 옵션의 이름

value any <optional>

옵션의 값

setSize(size)

지도 화면의 크기를 픽셀 단위로 설정합니다.

Parameters
Name Type Description
size naver.maps.Size | SizeLiteral

픽셀 단위의 지도 크기

Fires

setZoom(zoom, effect)

지도의 줌 레벨을 설정합니다.

Parameters
Name Type Argument Default Description
zoom number

지도의 줌 레벨

effect boolean <optional>
false

줌 레벨 변경 시 효과 적용 여부

Fires

updateBy(coord, zoom)

지정한 좌표와 줌 레벨을 사용하는 새로운 위치로 지도를 즉시 이동합니다.

Parameters
Name Type Description
coord Coord | CoordLiteral

중심 좌표

zoom number

줌 레벨

Fires

zoomBy(deltaZoom, zoomOrigin, effect)

지도의 줌 레벨을 상대 값으로 설정합니다.
zoomOrigin을 설정하면 줌 레벨 변경 시 해당 지도 좌표의 위치가 고정됩니다.

Parameters
Name Type Argument Default Description
deltaZoom number

지도의 상대 줌 레벨

zoomOrigin Coord | CoordLiteral <optional>
center

줌 변경 시 고정할 지도 좌표입니다.

effect boolean <optional>
false

줌 레벨 변경 시 효과 적용 여부

Fires

Type Definitions


MapOptions

MapOptions 객체는 지도를 정의하는 옵션을 나타냅니다.

Type:
Properties
Name Type Default Description
background string

지도 요소의 배경으로 사용할 이미지 URL 또는 CSS 색상값입니다.

baseTileOpacity number

지도 기본 타일의 불투명도를 설정합니다. 값의 범위는 0~1이며, 기본값은 1입니다.

bounds Bounds | BoundsLiteral null

지도의 초기 좌표 경계입니다. 이 값을 설정하면 지도 옵션 중 centerzoom 옵션을 무시하고, 지정한 좌표 경계에 맞게 지도를 생성합니다.

center Coord | CoordLiteral 서울시청

지도의 초기 중심 좌표입니다. 기본값은 서울 시청 좌표(37.5666103, 126.9783882)입니다.

disableDoubleClickZoom boolean false

사용자가 지도 위에서 마우스 버튼을 더블 클릭해 지도를 확대하는 기능의 사용 여부입니다.

disableDoubleTapZoom boolean false

사용자가 지도 위에서 한 손가락으로 더블 탭해 지도를 확대하는 기능의 사용 여부입니다.

disableKineticPan boolean true

사용자가 지도를 드래그했을 때 관성 효과(사용자가 동작을 끝낸 후에도 계속되는 지도의 움직임)의 사용 여부입니다.

disableTwoFingerTapZoom boolean false

사용자가 지도 위에서 두 손가락으로 두 번 탭해 지도를 축소하는 기능의 사용 여부입니다.

draggable boolean true

마우스 또는 손가락을 이용한 지도 이동(패닝) 허용 여부입니다.

keyboardShortcuts boolean true

키보드 방향 키를 이용한 지도 이동(패닝) 허용 여부입니다.

logoControl boolean true

NAVER 로고 컨트롤의 표시 여부입니다. (항상 노출로 변경)

logoControlOptions LogoControlOptions

NAVER 로고 컨트롤의 옵션입니다.

mapDataControl boolean true

지도 데이터 저작권 컨트롤의 표시 여부입니다.

mapDataControlOptions MapDataControlOptions

지도 데이터 저작권 컨트롤의 옵션입니다.

mapTypeControl boolean false

지도 유형 컨트롤의 표시 여부입니다.

mapTypeControlOptions MapTypeControlOptions

지도 유형 컨트롤의 옵션입니다.

mapTypeId string NORMAL

지도의 초기 지도 유형 id입니다.

mapTypes naver.maps.MapTypeRegistry

지도 유형의 컬렉션을 포함하는 객체입니다. 이 값을 설정하지 않으면 사전에 정의된 NAVER 지도의 기본 지도 유형으로 설정합니다.

maxBounds Bounds | BoundsLiteral null

지도에서 보이는 최대 좌표 경계입니다. 지도의 중심 좌표는 지정한 최대 좌표 경계 내에서만 설정할 수 있습니다.

maxZoom number

지도의 최대 줌 레벨입니다. 이 값을 설정하지 않으면 지정된 초기 지도 유형의 최고 줌 레벨로 설정합니다.

minZoom number

지도의 최소 줌 레벨입니다. 이 값을 설정하지 않으면 지정된 초기 지도 유형의 최저 줌 레벨로 설정합니다.

padding padding

지도 뷰포트의 안쪽 여백(패딩)입니다. 단위는 화면 픽셀이며, 기본값은 {top: 0, right: 0, bottom: 0, left: 0}입니다.

pinchZoom boolean true

핀치 제스처를 이용한 지도 확대/축소 허용 여부입니다.

resizeOrigin naver.maps.Position CENTER

지도 크기 조정 시 고정할 원점입니다.

scaleControl boolean true

지도 축척 컨트롤의 표시 여부입니다.

scaleControlOptions ScaleControlOptions

지도 축척 컨트롤의 옵션입니다.

scrollWheel boolean true

마우스 스크롤 휠을 이용한 지도 확대/축소 허용 여부입니다.

size naver.maps.Size | SizeLiteral

지도의 초기 크기입니다. 이 값을 설정하지 않으면, 지도 DOM 요소의 CSS 크기에 따라 지도 크기가 자동으로 조정됩니다.

overlayZoomEffect null | string null

도형, 마커 등 오버레이의 줌 효과 적용 대상입니다. 적용할 대상의 창(pane) 이름을 문자열로 지정합니다. 이 값이 all이면 모든 오버레이에 줌 효과가 적용됩니다. 오버레이의 개수가 많을 때는 성능에 영향을 줄 수 있으므로 주의해 사용해야 합니다.

tileSpare number 0

지도의 크기보다 보다 여유있게 로딩할 타일의 개수를 지정합니다.

tileTransition boolean true

지도 타일을 전환할 때 페이드 인 효과(타일이 서서히 나타나는 것)의 사용 여부입니다.

tileDuration number

지도 타일을 전환할 때 페이드 인 효과(타일이 서서히 나타나는 것)의 지속 시간 입니다. (밀리초), 기본값은 300~600ms입니다.

zoom number 11

지도의 초기 줌 레벨입니다.

zoomControl boolean false

줌 컨트롤의 표시 여부입니다.

zoomControlOptions ZoomControlOptions

줌 컨트롤의 옵션입니다.

zoomOrigin Coord | CoordLiteral null

줌 효과 시 고정하여 적용할 기준 좌표입니다. 해당 좌표가 현재 지도 화면 밖에 위치해 있으면 기본 기준 좌표를 적용합니다.

blankTileImage null | string null

빈 타일 이미지 URL을 설정할 수 있는 옵션입니다. 기본값은 투명 gif 입니다.


MapPanes

MapPanes 객체는 오버레이를 지도 위에 렌더링할 수 있는 DOM 요소를 포함하며, 지도에 있는 여러 레이어의 스택(stack) 순서를 나타냅니다.

Type:
Properties
Name Type Description
overlayLayer HTMLElement

이 창은 폴리라인, 폴리곤 등의 오버레이 요소를 포함합니다. 이 창은 DOM 이벤트를 받지 않습니다.

overlayImage HTMLElement

이 창은 마커의 요소를 포함합니다.

floatPane HTMLElement

이 창은 모든 오버레이보다 위에 위치하는 정보 창(Info Window) 요소를 포함합니다.

Events

addLayer

지도 레이어가 추가되면 이벤트가 발생합니다.

Parameters
Name Type Description
layer naver.maps.Layer

추가된 레이어

bounds_changed

지도 좌표 경계가 변경되면 이벤트가 발생합니다.

Parameters
Name Type Description
bounds Bounds

변경된 좌표 경계

center_changed

지도 중심 좌표가 변경되면 이벤트가 발생합니다.

Parameters
Name Type Description
center Coord

변경된 중심 좌표

centerPoint_changed

지도 중심 세계 좌표가 변경되면 이벤트가 발생합니다.

Parameters
Name Type Description
centerPoint naver.maps.Point

변경된 중심 세계 좌표

click

사용자가 지도에서 마우스 왼쪽 버튼을 클릭하면 이벤트가 발생합니다. 단, 오버레이를 클릭했을 때는 이벤트가 발생하지 않습니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

dblclick

사용자가 지도에서 마우스 왼쪽 버튼을 더블 클릭하면 이벤트가 발생합니다. 단, 오버레이를 클릭했을 때는 이벤트가 발생하지 않습니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

doubletap

사용자가 지도에서 두 번 연속으로 탭하면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

drag

사용자가 지도를 끌어다 놓으면(드래그) 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

dragend

사용자가 지도에서 드래그를 종료하면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

dragstart

사용자가 지도에서 드래그를 시작하면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

idle

지도의 움직임이 종료되면(유휴 상태) 이벤트가 발생합니다.

init

지도가 초기화되면 이벤트가 발생합니다.

keydown

지도 위에서 키보드의 키를 누르고 있으면 이벤트가 발생합니다.

Parameters
Name Type Description
keyboardEvent KeyboardEvent

키보드 이벤트 객체

keyup

지도 위에서 키보드의 키를 눌렀다 떼면 이벤트가 발생합니다.

Parameters
Name Type Description
keyboardEvent KeyboardEvent

키보드 이벤트 객체

longtap

사용자가 한 손가락으로 지도를 누르고 1초 이상 지난 후 떼면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

mapType_changed

지도 유형이 변경되면 이벤트가 발생합니다.

Parameters
Name Type Description
mapType MapType

변경된 지도 유형 객체

mapTypeId_changed

지도 유형 id가 변경되면 이벤트가 발생합니다.

Parameters
Name Type Description
mapTypeId naver.maps.MapTypeId | string

변경된 지도 유형의 id

mousedown

사용자가 지도에서 마우스 버튼을 누르면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

mousemove

지도에서 사용자의 마우스 포인터를 움직이면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

mouseout

사용자의 마우스 포인터가 지도 경계를 벗어나면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

mouseover

사용자의 마우스 포인터가 지도 경계에 들어오면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

mouseup

사용자가 지도에서 마우스 버튼을 놓으면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

panning

panTo, morph 메서드 등으로 지도 패닝을 시작하면 이벤트가 발생합니다.

pinch

사용자가 두 손가락으로 지도를 누르고 두 손가락을 모으거나 펼치면(핀치 제스처) 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

pinchend

사용자가 지도에서 핀치 제스처를 종료하면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

pinchstart

사용자가 지도에서 핀치 제스처를 시작하면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

projection_changed

지도 투영이 변경되면 이벤트가 발생합니다.

Parameters
Name Type Description
projection naver.maps.Projection

지도 유형의 원본 투영 객체

removeLayer

지도 레이어가 제거되면 이벤트가 발생합니다.

Parameters
Name Type Description
layername string

제거된 레이어 이름

resize

지도의 크기가 재설정되면 이벤트가 발생합니다.

rightclick

사용자가 지도에서 마우스 오른쪽 버튼을 클릭하면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

size_changed

지도 크기가 변경되면 이벤트가 발생합니다.

Parameters
Name Type Description
size naver.maps.Size

지도의 크기

tap

사용자가 한 손가락으로 지도를 누르고, 즉시 한 손가락을 뗄 때 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

tilesloaded

지도의 모든 타일이 로드되면 이벤트가 발생합니다.

touchend

사용자의 손가락이 지도에서 떨어지면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

touchmove

사용자의 손가락이 지도에서 움직이면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

touchstart

사용자의 손가락이 지도에 닿으면 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

twofingertap

사용자가 두 손가락으로 지도를 누렀다가 즉시 떼면(탭) 이벤트가 발생합니다.

Parameters
Name Type Description
pointerEvent PointerEvent

포인터 이벤트 객체

zoom_changed

지도 줌 레벨이 변경되면 이벤트가 발생합니다.

Parameters
Name Type Description
zoom number

변경된 줌 레벨

zoomend

지도 줌 레벨이 종료되면 이벤트가 발생합니다.

zoomstart

지도 줌 효과가 시작되면 이벤트가 발생합니다.