라이브러리 로고입니다.vue3-kakao-maps
npm 로고입니다.

KakaoMap

카카오 지도 컴포넌트입니다.

Name* 필수 입력값
DescriptionTypeDefaultControl
width지도의 가로 길이numberstring40rem
height지도의 세로 길이numberstring30rem
markerList지도에 표시할 marker 데이터의 리스트KakaoMapMarkerListItem[]
infoWindowList지도에 표시할 인포윈도우 데이터의 리스트KakaoMapInfoWindowListItem[]
markerCluster지도에 표시할 marker cluster의 속성 및 데이터 리스트MarkerClusterInfo
lat*지도의 위도 값number
lng*지도의 경도 값number
level지도 확대 수준. MapTypeId 의 종류에 따라 설정 범위가 다르다. SKYVIEW, HYBRID 일 경우 0 ~ 14, ROADMAP 일 경우 1 ~ 14.number3
mapTypeId지도 종류를 설정합니다. 기본값은 일반 지도(1), (베이스) 일반 지도: 1, (베이스) 스카이뷰:2, (베이스) 하이브리드(스카이뷰 + 레이블): 3, (오버레이) 레이블: 4kakao.maps.MapTypeId1
1
draggable마우스 드래그, 휠, 모바일 터치를 이용한 시점 변경(이동, 확대, 축소) 가능 여부booleantrue
scrollwheel마우스 휠, 모바일 터치를 이용한 확대 및 축소 가능 여부booleantrue
disableDoubleClick더블클릭 이벤트 및 더블클릭 확대 가능 여부, 최초 생성시에만 적용됩니다.booleanfalse
disableDoubleClickZoom더블클릭 확대 가능 여부, 최초 생성시에만 적용됩니다.booleanfalse
projectionId투영법 지정stringkakao.maps.ProjectionId.WCONG
tileAnimation지도 타일 애니메이션 설정 여부 booleantrue
keyboardShortcuts키보드의 방향키와 +,-키로 지도 이동,확대,축소 가능여부를 설정한다. speed 속성은 지도의 이동속도이며, 처음 생성시에만 적용된다.boolean{ speed: number; }true

Events

NameDescriptionReturn
onLoadKakaoMap지도가 로드되었을 때 발생하는 이벤트kakao.maps.Map
onLoadKakaoMapMarkerCluster지도의 마커 클러스터 로드되었을 때 발생하는 이벤트kakao.maps.MarkerClusterer

지도 생성하기

기본적인 지도 생성입니다.

<script setup lang="ts">
import { KakaoMap } from 'vue3-kakao-maps';
</script>

<template>
  <KakaoMap :lat="33.450701" :lng="126.570667" />
</template>

지도 이동시키기

지도를 이동시킵니다. 지도 객체의 메소드를 통해 지도를 원하는 좌표로 이동시킬 수 있습니다. 또, 지도가 표시되고 있는 영역크기를 벗어나지 않는 거리라면 애니메이션 효과처럼 지도를 부드럽게 이동시킬 수도 있습니다. 

<script setup lang="ts">
import { KakaoMap } from 'vue3-kakao-maps';
import { ref } from 'vue';

const lat = ref<number>(33.450701);
const lng = ref<number>(126.570667);
const map = ref<kakao.maps.Map>();
const latRange: [number, number] = [33.45058, 33.450701];
const lngRange: [number, number] = [126.570667, 126.574942];

const onLoadKakaoMap = (mapRef: kakao.maps.Map) => {
  map.value = mapRef;
};

const changeLatLng = () => {
  lat.value = Math.random() * (latRange[1] - latRange[0]) + latRange[0];
  lng.value = Math.random() * (lngRange[1] - lngRange[0]) + lngRange[0];
};

const setCenter = () => {
  if (map.value) {
    map.value.setCenter(new kakao.maps.LatLng(33.450701, 126.570667));
  }
};

const panTo = () => {
  if (map.value) {
    // 지도 중심을 부드럽게 이동시킵니다
    // 만약 이동할 거리가 지도 화면보다 크면 부드러운 효과 없이 이동합니다
    map.value.panTo(new kakao.maps.LatLng(33.45058, 126.574942));
  }
};
</script>

<template>
  <KakaoMap :lat="lat" :lng="lng" @onLoadKakaoMap="onLoadKakaoMap" />
  <div>
    <button @click="changeLatLng" class="demo-button">좌표값 변경으로 중심좌표 부드러운 이동</button>
    <button @click="setCenter" class="demo-button">map 객체로 중심좌표 이동</button>
    <button @click="panTo" class="demo-button">map 객체로 부드러운 이동</button>
  </div>
</template>

지도 레벨 바꾸기

거리라면 애니메이션 효과처럼 지도를 부드럽게 이동시킬 수도 있습니다.

<script setup lang="ts">
import { ref } from 'vue';
import { KakaoMap } from 'vue3-kakao-maps';

const map = ref<kakao.maps.Map>();
const message = ref<string>('');

const onLoadKakaoMap = (mapRef: kakao.maps.Map) => {
  map.value = mapRef;
  displayLevel();
};

const zoomIn = () => {
  // 현재 지도의 레벨을 얻어옵니다
  if (map.value) {
    const level = map.value.getLevel();

    // 지도를 1레벨 내립니다 (지도가 확대됩니다)
    map.value.setLevel(level - 1);
  }

  // 지도 레벨을 표시합니다
  displayLevel();
};

const zoomOut = () => {
  // 현재 지도의 레벨을 얻어옵니다
  if (map.value) {
    const level = map.value.getLevel();

    // 지도를 1레벨 올립니다 (지도가 축소됩니다)
    map.value.setLevel(level + 1);
  }

  // 지도 레벨을 표시합니다
  displayLevel();
};

const displayLevel = () => {
  message.value = `현재 지도 레벨은 ${map.value?.getLevel()} 레벨 입니다.`;
};
</script>

<template>
  <KakaoMap :lat="33.450701" :lng="126.570667" @onLoadKakaoMap="onLoadKakaoMap" />
  <div>
    <button class="demo-button" @click="zoomIn">지도레벨 - 1</button>
    <button class="demo-button" @click="zoomOut">지도레벨 + 1</button>
  </div>
  <p>{{ message }}</p>
</template>

지도 정보 얻어오기

지도 레벨, 중심좌표, 지도 타입, 지도 영역정보를 얻어와 표출합니다.
지도 타입을 보시려면 여기를 클릭하세요!

<script setup lang="ts">
import { KakaoMap } from 'vue3-kakao-maps';
import { ref } from 'vue';

const lat = ref<number>(33.450701);
const lng = ref<number>(126.570667);
const map = ref<kakao.maps.Map>();

const onLoadKakaoMap = (mapRef: kakao.maps.Map) => {
  map.value = mapRef;
  // 일반 지도와 스카이뷰로 지도 타입을 전환할 수 있는 지도타입 컨트롤을 생성합니다
  const mapTypeControl = new kakao.maps.MapTypeControl();
  // 지도 타입 컨트롤을 지도에 표시합니다
  map.value.addControl(mapTypeControl, kakao.maps.ControlPosition.TOPRIGHT);
};

const message = ref<string>('');

const getInfo = () => {
  if (map.value) {
    // 지도의 현재 중심좌표를 얻어옵니다
    const center = map.value.getCenter();

    // 지도의 현재 레벨을 얻어옵니다
    const level = map.value.getLevel();

    // 지도타입을 얻어옵니다
    const mapTypeId = map.value.getMapTypeId();

    // 지도의 현재 영역을 얻어옵니다
    const bounds = map.value.getBounds();

    // 영역의 남서쪽 좌표를 얻어옵니다
    const swLatLng = bounds.getSouthWest();

    // 영역의 북동쪽 좌표를 얻어옵니다
    const neLatLng = bounds.getNorthEast();

    // 영역정보를 문자열로 얻어옵니다. ((남,서), (북,동)) 형식입니다
    const boundsStr = bounds.toString();
    message.value = `지도 중심좌표는 위도 ${center.getLat()} <br>`;
    message.value += `경도 ${center.getLng()} 이고 <br>`;
    message.value += `지도 레벨은 ${level} 입니다 <br>`;
    message.value += `지도 타입은 ${mapTypeId} 이고 <br> `;
    message.value += `지도의 남서쪽 좌표는 ${swLatLng.getLat()}, ${swLatLng.getLng()}이고 <br>`;
    message.value += `북동쪽 좌표는 ${neLatLng.getLat()}, ${neLatLng.getLng()}입니다`;
  }
};
</script>

<template>
  <KakaoMap :lat="lat" :lng="lng" @onLoadKakaoMap="onLoadKakaoMap" />
  <button @click="getInfo" class="demo-button">정보 얻기</button>
  <div v-html="message" />
</template>

지도 이동 막기

마우스 드래그로 지도를 이동시키는 기능을 막습니다. 모바일 기기에서 터치스크롤시 지도가 이동되는 것을 막고싶거나 지도가 이동되면 안되는 경우 등 상황에 따라 지도의 이동 기능을 제어할 수 있습니다. 

<script setup lang="ts">
import { ref } from 'vue';
import { KakaoMap } from 'vue3-kakao-maps';

const map = ref<kakao.maps.Map>();

const onLoadKakaoMap = (mapRef: kakao.maps.Map) => {
  map.value = mapRef;
};

// 버튼 클릭에 따라 지도 이동 기능을 막거나 풀고 싶은 경우에는 map.value.setDraggable 함수를 사용합니다
const setDraggable = (draggable: boolean) => {
  // 마우스 드래그로 지도 이동 가능여부를 설정합니다
  map.value?.setDraggable(draggable);
};
</script>

<template>
  <KakaoMap :lat="33.450701" :lng="126.570667" @onLoadKakaoMap="onLoadKakaoMap" />
  <button class="demo-button" @click="setDraggable(false)">지도 드래그 이동 끄기</button>
  <button class="demo-button" @click="setDraggable(true)">지도 드래그 이동 켜기</button>
</template>

지도 확대 축소 막기

마우스 휠이나 멀티터치로 지도 확대, 축소 기능을 막습니다. 상황에 따라 지도 확대, 축소 기능을 제어할 수 있습니다.

<script setup lang="ts">
import { ref } from 'vue';
import { KakaoMap } from 'vue3-kakao-maps';

const map = ref<kakao.maps.Map>();

const onLoadKakaoMap = (mapRef: kakao.maps.Map) => {
  map.value = mapRef;
};

// 버튼 클릭에 따라 지도 확대, 축소 기능을 막거나 풀고 싶은 경우에는 map.value.setZoomable 함수를 사용합니다
const setZoomable = (zoomable: boolean) => {
  // 마우스 휠로 지도 확대,축소 가능여부를 설정합니다
  map.value?.setZoomable(zoomable);
};
</script>

<template>
  <KakaoMap :lat="33.450701" :lng="126.570667" @onLoadKakaoMap="onLoadKakaoMap" />
  <div>
    <button class="demo-button" @click="setZoomable(false)">지도 확대/축소 끄기</button>
    <button class="demo-button" @click="setZoomable(true)">지도 확대/축소 켜기</button>
  </div>
</template>

지도 범위 재설정하기

지도 범위를 재설정합니다. 어떤 좌표나 마커들이 지도에 모두 보여야 할 때 좌표들의 정보를 갖는 LatLngBounds를 사용하여 좌표들이 모두 보이게 지도의 중심좌표와 레벨을 재설정 할 수 있습니다. 

<script setup lang="ts">
import { ref } from 'vue';
import { KakaoMap, type KakaoMapMarkerListItem } from 'vue3-kakao-maps';

const map = ref<kakao.maps.Map>();

// 버튼을 클릭하면 아래 배열의 좌표들이 모두 보이게 지도 범위를 재설정합니다
const markerInfoList: KakaoMapMarkerListItem[] = [
  { key: 1, lat: 33.452278, lng: 126.567803 },
  { key: 2, lat: 33.452671, lng: 126.574792 },
  { key: 3, lat: 33.451744, lng: 126.572441 }
];

// 지도를 재설정할 범위정보를 가지고 있을 LatLngBounds 객체를 생성합니다
let bounds: kakao.maps.LatLngBounds;

const onLoadKakaoMap = (mapRef: kakao.maps.Map) => {
  map.value = mapRef;
  bounds = new kakao.maps.LatLngBounds();
  let marker: kakao.maps.Marker;
  let point: kakao.maps.LatLng;

  markerInfoList.forEach((markerInfo) => {
    // 배열의 좌표들이 잘 보이게 마커를 지도에 추가합니다
    point = new kakao.maps.LatLng(markerInfo.lat, markerInfo.lng);

    marker = new kakao.maps.Marker({ position: point });
    if (map.value !== undefined) {
      marker.setMap(map.value);
    }

    // LatLngBounds 객체에 좌표를 추가합니다
    bounds.extend(point);
  });
};

const setBounds = (): void => {
  // LatLngBounds 객체에 추가된 좌표들을 기준으로 지도의 범위를 재설정합니다
  // 이때 지도의 중심좌표와 레벨이 변경될 수 있습니다
  if (map.value !== undefined) {
    map.value.setBounds(bounds);
  }
};
</script>

<template>
  <KakaoMap :lat="33.450701" :lng="126.570667" @onLoadKakaoMap="onLoadKakaoMap" />
  <button class="demo-button" @click="setBounds">지도 범위 재설정 하기</button>
</template>

클릭 이벤트 등록하기

지도를 마우스로 클릭했을때 click 이벤트가 발생합니다. 이 예제에서는 지도를 클릭했을 때 지도 아래쪽에 해당 위치의 좌표를 뿌려주고 있습니다.

지도를 클릭해주세요!

<script setup lang="ts">
import { ref } from 'vue';
import { KakaoMap } from 'vue3-kakao-maps';

const map = ref<kakao.maps.Map>();
const message = ref<string>('');

const onLoadKakaoMap = (mapRef: kakao.maps.Map) => {
  map.value = mapRef;

  kakao.maps.event.addListener(map.value, 'click', function (mouseEvent: kakao.maps.event.MouseEvent) {
    // 클릭한 위도, 경도 정보를 가져옵니다
    const latlng = mouseEvent.latLng;

    message.value = `클릭한 위치의 위도는 ${latlng.getLat()} 이고, <br>`;
    message.value += `경도는 ${latlng.getLng()} 입니다`;
  });
};
</script>

<template>
  <KakaoMap :lat="33.450701" :lng="126.570667" @onLoadKakaoMap="onLoadKakaoMap" />
  <p>지도를 클릭해주세요!</p>
  <p v-html="message"></p>
</template>

여러개의 마커 제어하기

버튼을 눌러 마커를 생성하고 삭제해보세요.

<script setup lang="ts">
import { ref } from 'vue';
import { KakaoMap, type KakaoMapMarkerListItem } from 'vue3-kakao-maps';

const markerInfoList: KakaoMapMarkerListItem[] = [
  { key: 1, lat: 33.450705, lng: 126.570677 },
  { key: 2, lat: 33.450936, lng: 126.569477 },
  { key: 3, lat: 33.450879, lng: 126.56994 },
  { key: 4, lat: 33.451393, lng: 126.570738 }
];

const markerCount = ref<number>(0);
const markerList = computed(() => markerInfoList.slice(0, markerCount.value));

const onAddMarker = () => {
  if (markerCount.value < markerInfoList.length) {
    markerCount.value += 1;
  }
};

const onDeleteMarker = () => {
  if (0 < markerCount.value) {
    markerCount.value -= 1;
  }
};
</script>

<template>
  <KakaoMap :lat="33.450701" :lng="126.570667" :markerList="markerList"> </KakaoMap>
  <div>
    <button @click="onAddMarker" class="demo-button">마커 추가</button>
    <button @click="onDeleteMarker" class="demo-button">마커 삭제</button>
  </div>
</template>

다각형 그리고 이벤트 등록하기

지도 위에 다각형을 표시하고 클릭 이벤트를 등록해서 인포윈도우를 띄웁니다. 다각형의 면적을 계산할 수 있습니다. 예시 데이터와 기타 이벤트는 카카오 맵 API의 [다각형에 이벤트 등록하기]를 참고하시기 바랍니다

색칠된 영역을 클릭해보세요

<script setup lang="ts">
import { ref } from 'vue';
import { KakaoMap, KakaoMapInfoWindow } from 'vue3-kakao-maps';

// 지도에 표시할 영역 데이터 배열입니다
import area from '@/assets/data/area.json';

const map = ref<kakao.maps.Map>();
const content = ref<string>('');
const infoLat = ref<number>(37.566826);
const infoLng = ref<number>(126.9786567);
const infoVisible = ref<boolean>(false);

// 지도에 폴리곤으로 표시할 영역데이터 배열입니다
const onLoadKakaoMap = (mapRef: kakao.maps.Map) => {
  map.value = mapRef;

  displayArea(area);
};

const displayArea = (area: any): void => {
  const path = ref<kakao.maps.LatLng[]>([]);

  for (let i = 0; i < area.path.length; i++) {
    path.value.push(new kakao.maps.LatLng(area.path[i].lat, area.path[i].lng));
  }

  // 지도에 표시할 다각형을 생성합니다
  const polygon = new kakao.maps.Polygon({
    path: path.value, // 그려질 다각형의 좌표 배열입니다
    strokeWeight: 3, // 선의 두께입니다
    strokeColor: '#39DE2A', // 선의 색깔입니다
    strokeOpacity: 0.8, // 선의 불투명도 입니다 1에서 0 사이의 값이며 0에 가까울수록 투명합니다
    strokeStyle: 'longdash', // 선의 스타일입니다
    fillColor: '#A2FF99', // 채우기 색깔입니다
    fillOpacity: 0.7 // 채우기 불투명도 입니다
  });

  // 지도에 다각형을 표시합니다
  if (map.value !== undefined) {
    polygon.setMap(map.value);

    area.value = Math.floor(polygon.getArea()); // 다각형의 총면적을 계산합니다
    content.value = `${area.name}의 총 면적 : 약 ${area.value}m<sup>2</sup>`;

    // 다각형에 마우스클릭 이벤트를 등록합니다
    //'mouseover','mouseout','mousedown','click' 이벤트가 등록 가능합니다
    kakao.maps.event.addListener(polygon, 'click', function (mouseEvent: kakao.maps.event.MouseEvent) {
      infoLat.value = mouseEvent.latLng.getLat();
      infoLng.value = mouseEvent.latLng.getLng();
      infoVisible.value = true;
    });
  }
};
</script>

<template>
  <KakaoMap :lat="37.566826" :lng="126.9786567" :level="8" @onLoadKakaoMap="onLoadKakaoMap">
    <KakaoMapInfoWindow :lat="infoLat" :lng="infoLng" :visible="infoVisible" :content="content" :zIndex="5" />
  </KakaoMap>
  <p>색칠된 영역을 클릭해보세요</p>
</template>