본문으로 건너뛰기

크기/위치 계산 사용법 (syn.$d)

개요​

syn.$d는 HTML Element와 브라우저 화면/문서의 크기, 스크롤 위치, 오프셋(위치), 텍스트 렌더링 크기를 계산하는 기능을 제공합니다. 레이아웃 계산, 툴팁/팝업 위치 지정, 동적 텍스트 크기 측정 등에 사용됩니다.

로드 방법​

syn.js가 로드되면 전역에 syn.$d(별칭: $dimension)로 즉시 사용할 수 있습니다.

빠른 시작​

const size = syn.$d.getSize('myElement');
console.log(size.width, size.height);

주요 시나리오​

문서/윈도우 최대 크기 조회​

getDocumentSize()와 getWindowSize()로 스크롤을 포함한 문서 전체 크기와 현재 보이는 브라우저 창 크기를 각각 조회합니다.

const docSize = syn.$d.getDocumentSize();
const winSize = syn.$d.getWindowSize();

노드 위치/오프셋 계산​

offset(el)은 문서 기준 절대 좌표를, offsetLeft(el)/offsetTop(el)은 최상위 노드까지의 누적 거리를, parentOffsetLeft(el)/parentOffsetTop(el)은 직속 부모와의 거리를 계산합니다.

const pos = syn.$d.offset('myElement');
console.log(pos.top, pos.left);

마우스 위치, 스크롤 위치 추적​

getMousePosition(evt)로 이벤트 발생 시점의 마우스 좌표를, getScrollPosition(el)로 특정 노드 또는 문서의 스크롤 거리를 조회합니다.

document.addEventListener('click', (evt) => {
    const mouse = syn.$d.getMousePosition(evt);
    console.log(mouse.x, mouse.y);
});

텍스트 렌더링 크기 측정​

measureWidth, measureHeight, measureSize로 실제 렌더링되었을 때의 텍스트 크기를 fontSize 기준으로 측정합니다. 동적으로 생성되는 라벨/툴팁의 크기를 미리 계산할 때 유용합니다.

const { width, height } = syn.$d.measureSize('안녕하세요', '14px', '400px');

실전 예제 페이지​

/sample/syn/dimension.html 예제에서 다음 항목을 실습할 수 있습니다.

  • getDocumentSize(), getWindowSize(), getScrollPosition(), getMousePosition(), offset(), offsetLeft(), parentOffsetLeft(), offsetTop(), parentOffsetTop(), getSize(), measureWidth(), measureHeight(), measureSize() 메서드 실습

주의 사항​

  • getDocumentSize(true), getWindowSize(true)처럼 isTopWindow를 true로 넘기면 최상위(top) 프레임 기준으로 계산하므로, iframe 내부에서 호출할 때 교차 출처(cross-origin) 제약이 있으면 실패할 수 있습니다.
  • measureHeight(text, width, fontSize)는 세 번째 인자가 fontSize이며 두 번째 인자(width)를 생략하면 'auto'로 처리되어 줄바꿈이 발생하지 않을 수 있습니다. 인자 순서에 주의하십시오.
  • syn.$d는 별도의 공개 속성이 없고 전부 메서드로만 구성되어 있습니다.

관련 모듈​

  • API 상세는 아래 API 참조 섹션을 확인하세요.

API 참조​

모듈 정보​

항목내용
전역 별칭syn.$d (원본: context.$dimension)
예제 페이지/sample/syn/dimension.html
의존 모듈syn.$string(toBoolean, toNumber), syn.$l(getElement), syn.$object(isNumber)

속성​

공개 속성이 없습니다. syn.$d는 전부 메서드로만 구성됩니다.

메서드​

syn.$d.getDocumentSize(isTopWindow = false)​

  • 설명: scrollWidth/offsetWidth/clientWidth 등을 비교한 최대값으로 문서 전체 크기와 뷰포트(frame) 크기를 계산합니다.
  • 매개변수
    이름타입필수설명
    isTopWindowbooleanNtrue이면 최상위(top) 문서를 기준으로 계산합니다. 기본값 false.
  • 반환값: { width, height, frameWidth, frameHeight } — 모두 number.
  • 예시 
    const size = syn.$d.getDocumentSize();

syn.$d.getWindowSize(isTopWindow = false)​

  • 설명: 현재(또는 최상위) 윈도우의 innerWidth/innerHeight를 조회합니다.
  • 매개변수
    이름타입필수설명
    isTopWindowbooleanNtrue이면 최상위(top) 윈도우를 기준으로 계산합니다. 기본값 false.
  • 반환값: { width, height } — 모두 number.
  • 예시 
    const size = syn.$d.getWindowSize();

syn.$d.getScrollPosition(el)​

  • 설명: 지정한 노드(또는 생략 시 문서)의 스크롤 위치를 조회합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`N
  • 반환값: { left, top } — 모두 number.
  • 예시 
    const scroll = syn.$d.getScrollPosition('myElement');

syn.$d.getMousePosition(evt)​

  • 설명: 이벤트 객체의 pageX/pageY(또는 clientX/clientY + 스크롤 보정)와 상대 좌표(layerX/layerY 또는 offsetX/offsetY)를 계산합니다.
  • 매개변수
    이름타입필수설명
    evtEventN마우스 이벤트 객체. 생략 시 context.event/top.event를 사용합니다.
  • 반환값: { x, y, relativeX, relativeY } — 모두 number.
  • 예시 
    el.addEventListener('click', (evt) => {
        const pos = syn.$d.getMousePosition(evt);
    });

syn.$d.offset(el)​

  • 설명: getBoundingClientRect()와 문서 스크롤 위치를 합산하여 문서 기준 절대 좌표를 계산합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`Y
  • 반환값: { top, left } | null — 대상이 없으면 null.
  • 예시 
    const pos = syn.$d.offset('myElement');

syn.$d.offsetLeft(el)​

  • 설명: offsetParent를 따라 올라가며 offsetLeft를 누적하여 최상위 노드까지의 left 거리 합계를 계산합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`Y
  • 반환값: number
  • 예시 
    const left = syn.$d.offsetLeft('myElement');

syn.$d.parentOffsetLeft(el)​

  • 설명: 대상 노드와 직속 부모 노드 간의 left 거리만 계산합니다. 생략 시 document.documentElement 또는 document.body를 기준으로 합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`N
  • 반환값: number
  • 예시 
    const left = syn.$d.parentOffsetLeft('myElement');

syn.$d.offsetTop(el)​

  • 설명: offsetParent를 따라 올라가며 offsetTop을 누적하여 최상위 노드까지의 top 거리 합계를 계산합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`Y
  • 반환값: number
  • 예시 
    const top = syn.$d.offsetTop('myElement');

syn.$d.parentOffsetTop(el)​

  • 설명: 대상 노드와 직속 부모 노드 간의 top 거리만 계산합니다. 생략 시 document.documentElement 또는 document.body를 기준으로 합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`N
  • 반환값: number
  • 예시 
    const top = syn.$d.parentOffsetTop('myElement');

syn.$d.getSize(el)​

  • 설명: getComputedStyle을 이용해 padding/margin을 반영한 콘텐츠 크기, client/offset/margin 크기를 함께 계산합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`Y
  • 반환값: { width, height, clientWidth, clientHeight, offsetWidth, offsetHeight, marginWidth, marginHeight } | null
  • 예시 
    const size = syn.$d.getSize('myElement');

syn.$d.measureWidth(text, fontSize)​

  • 설명: 화면에 보이지 않는 임시 <div>를 생성해 지정된 텍스트의 렌더링 폭을 측정합니다.
  • 매개변수
    이름타입필수설명
    textstringY측정할 텍스트.
    fontSizestringNCSS font-size 값(예: '14px'). 생략 시 상속값(inherit)을 사용합니다.
  • 반환값: string — 계산된 CSS 너비 값(예: '82px'). document.body가 없으면 '0px'.
  • 예시 
    const width = syn.$d.measureWidth('hello world', '14px');

syn.$d.measureHeight(text, width, fontSize)​

  • 설명: 지정된 너비(width)로 줄바꿈된 텍스트의 렌더링 높이를 측정합니다.
  • 매개변수
    이름타입필수설명
    textstringY측정할 텍스트.
    widthstringNCSS width 값(예: '200px'). 생략 시 'auto'.
    fontSizestringNCSS font-size 값. 생략 시 상속값(inherit).
  • 반환값: string — 계산된 CSS 높이 값. document.body가 없으면 '0px'.
  • 예시 
    const height = syn.$d.measureHeight('hello world', '200px', '14px');

syn.$d.measureSize(text, fontSize, maxWidth = '800px')​

  • 설명: measureWidth와 measureHeight를 조합하여 maxWidth를 초과하지 않는 범위에서 텍스트의 너비/높이를 함께 측정합니다.
  • 매개변수
    이름타입필수설명
    textstringY측정할 텍스트. null/undefined이면 null을 반환합니다.
    fontSizestringNCSS font-size 값.
    maxWidth`string \number`N
  • 반환값: { width, height } | null — 각각 CSS 크기 문자열.
  • 예시 
    const { width, height } = syn.$d.measureSize('안녕하세요', '14px', '400px');