JavaScript에서 마우스 위치 추적

브라우저의 mousemove 이벤트에 콜백을 등록하면 포인터의 움직임을 추적할 수 있습니다. 콜백은 MouseEvent를 받으므로, 포인터 상태를 별도로 저장하는 대신 해당 이벤트에서 좌표 속성을 읽습니다. 포인터가 창 위에서 움직일 때마다 이벤트가 발생하므로 핸들러는 매번 최신 위치를 확인할 수 있습니다.

mousemove 이벤트로 마우스 움직임 감지하기

이벤트 리스너에는 이벤트 유형과 콜백이 필요합니다. 아래 브라우저 예제에서는 window.addEventListener가 handleMouseMove를 mousemove 이벤트에 등록하고, 콜백은 pageX, pageY, clientX, clientY를 읽습니다. 속성 이름은 대소문자를 구분합니다. mousemove 이벤트는 포인터가 움직일 때 발생하며, 페이지가 로드되거나 포인터가 가만히 있다는 이유만으로 발생하지는 않습니다.

간단히 실행할 수 있는 예제는 콜백에서 이벤트 값을 어떻게 형식화하는지 보여 줍니다. 일반 객체는 속성 이름을 설명하기 위한 샘플 입력입니다. 상호작용하는 페이지에서는 실제 브라우저 MouseEvent를 사용하세요.

다음 예제를 실행하세요:

이 섹션의 코드와 표시되는 레이블 또는 출력은 영어로 유지됩니다.

function handleMouseMove(event) {
  console.log(
    `page: (${event.pageX}, ${event.pageY}); client: (${event.clientX}, ${event.clientY})`
  );
}

handleMouseMove({ pageX: 120, pageY: 240, clientX: 120, clientY: 240 });

브라우저에서 상호작용하려면 자체적으로 완결된 다음 페이지를 사용하세요. 콘텐츠 높이가 충분해 문서를 스크롤할 수 있고, 핸들러는 페이지 위에서 포인터가 움직일 때마다 두 좌표 쌍을 모두 로그에 기록합니다.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Mouse coordinates</title>
  <style>
    body { min-height: 1600px; font: 16px sans-serif; }
    main { padding: 2rem; }
  </style>
</head>
<body>
  <main>
    <h1>Move the pointer, then scroll</h1>
    <p>Open the browser developer console to compare the coordinate pairs.</p>
  </main>
  <script>
    window.addEventListener('mousemove', (event) => {
      console.log(
        `page: (${event.pageX}, ${event.pageY}); client: (${event.clientX}, ${event.clientY})`
      );
    });
  </script>
</body>
</html>

페이지 좌표와 뷰포트 좌표 중 선택하기

pageX와 pageY는 문서의 왼쪽 위를 기준으로 포인터 위치를 측정합니다. 문서의 스크롤 오프셋이 포함되므로 독자가 스크롤해도 위치를 콘텐츠에 연결해 두려는 경우에 유용합니다. 예를 들어 긴 문서에서 특정 지점의 위치를 기록할 때 페이지 좌표를 사용하세요.

clientX와 clientY는 현재 보이는 뷰포트의 왼쪽 위를 기준으로 측정합니다. 스크롤해도 기준점은 바뀌지 않습니다. 사용자 지정 커서 표시나 뷰포트 오버레이처럼 현재 브라우저 화면 안에서 무언가의 위치를 지정하거나 비교할 때 이 값을 사용하세요.

두 좌표 쌍은 서로 다른 좌표 공간을 나타내므로 계산할 때는 한 쌍을 일관되게 사용하세요. 페이지 좌표와 뷰포트 좌표를 섞으면 결과가 스크롤 오프셋만큼 어긋날 수 있습니다. 요소가 포인터를 따라 움직이게 하려면 추가 마우스 이벤트와 요소 위치 지정 로직도 필요합니다. 좌표를 읽는 것만으로 요소가 움직이지는 않습니다.

스크롤하며 pageX와 clientX 비교하기

스크롤하기 전에는 문서의 기준점과 뷰포트의 기준점이 일치합니다. 따라서 가로 값인 pageX와 clientX가 같고, pageY와 clientY도 같습니다. 포인터를 움직인 다음 콘솔에서 두 좌표 쌍을 확인하세요. 첫 번째 제공 화면은 스크롤하기 전 콘솔 화면입니다.

아래로 스크롤한 뒤에도 가로 값은 대체로 계속 일치하지만, 세로 값인 pageY에는 스크롤한 거리가 포함되고 clientY는 뷰포트 위쪽을 기준으로 측정됩니다. 두 세로 값의 차이는 현재 스크롤 오프셋에 해당합니다. 두 번째 제공 화면은 스크롤한 뒤의 콘솔 화면입니다.

현재 화면에 보이는 위치를 기준으로 하려면 clientX와 clientY를 선택하세요. 스크롤된 콘텐츠를 포함해 문서를 기준으로 하려면 pageX와 pageY를 선택하세요. 브라우저 마우스 이벤트 전체 목록은 MDN 마우스 이벤트 참고 문서를 참조하세요.