Magnifier Library

웹 페이지에서 확대/축소 및 PIP(Picture-in-Picture) 돋보기 기능을 제공하는 TypeScript 라이브러리입니다.

🚀 특징

• 두 가지 모드 지원
  • zoom: 전체 화면 확대/축소 및 패닝
  • pip: 마우스/터치 위치에 따라 이동하는 돋보기 창
• 터치 및 마우스 이벤트 지원
• 드래그 기능
• 자동 화면 캡처 및 업데이트
• 커스터마이징 가능한 설정

📦 설치

npm install dabeeomaps_magnifier

Sample

cd sample && npm i && npm run dev : 개발 모드

📖 API 참조

생성자

new Magnifier(zoomContainer: HTMLElement)

메서드

init(options: ManifierOptions): void

돋보기 초기화 및 설정

magnifier.init({
    dragDistance: 10, // 드래그 감지 거리 (픽셀)
    pipSize: {
        // PIP 창 크기
        width: 540,
        height: 540,
    },
});

activate(): void

돋보기 기능 활성화

magnifier.activate();

deactivate(): void

돋보기 기능 비활성화

magnifier.deactivate();

setMode(mode: 'zoom' | 'pip'): void

돋보기 모드 설정

// 전체 화면 확대/축소 모드
magnifier.setMode('zoom');

// PIP 돋보기 모드
magnifier.setMode('pip');

getMode(): 'zoom' | 'pip'

현재 돋보기 모드 반환

const currentMode = magnifier.getMode();

setZoomScale(scale: number): void

확대 배율 설정 (zoom 모드에서만 동작)

magnifier.setZoomScale(1.5); // 1.5배 확대

getZoomScale(): number

현재 확대 배율 반환

const currentScale = magnifier.getZoomScale();

getEnabled(): boolean

돋보기 활성화 상태 확인

const isEnabled = magnifier.getEnabled();

destroy(): void

인스턴스 정리 및 리소스 해제

magnifier.destroy();

🔧 설정 옵션

ManifierOptions

interface ManifierOptions {
    dragDistance?: number; // 드래그 감지 거리
    pipSize?: {
        // PIP 창 크기 (기본값: 540x540)
        width: number;
        height: number;
    };
}

🎮 일반적인 사용 패턴

1. 기본 토글 기능

// 돋보기 ON/OFF 토글
function toggleMagnifier() {
    if (magnifier.getEnabled()) {
        magnifier.deactivate();
    } else {
        magnifier.setMode('zoom');
        magnifier.activate();
    }
}

2. 모드 전환

// zoom과 pip 모드 전환
function switchMode() {
    const currentMode = magnifier.getMode();
    const newMode = currentMode === 'zoom' ? 'pip' : 'zoom';
    magnifier.setMode(newMode);
}

3. 배율 조정

// 미리 정의된 배율 목록으로 순환
const zoomLevels = [1, 1.2, 1.4, 1.6, 1.8, 2];

function cycleZoomLevel() {
    const current = magnifier.getZoomScale();
    const currentIndex = zoomLevels.indexOf(current);
    const nextIndex = (currentIndex + 1) % zoomLevels.length;
    magnifier.setZoomScale(zoomLevels[nextIndex]);
}

4. 동적 PIP 크기 조정

// PIP 창 크기를 동적으로 변경
function resizePIP() {
    const sizes = [300, 400, 500, 600, 700];
    const randomSize = sizes[Math.floor(Math.random() * sizes.length)];

    magnifier.init({
        pipSize: {
            width: randomSize,
            height: randomSize,
        },
    });
}

🔍 모드별 특징

Zoom 모드

• 전체 화면을 확대/축소
• 1, 1.2, 1.4, 1.6, 1.8, 2배 확대 지원
• 마우스 드래그로 패닝 가능
• 스크롤을 통한 콘텐츠 탐색

PIP 모드

• 마우스/터치 위치에 따라 이동하는 돋보기 창
• 실시간 화면 캡처 및 업데이트
• 돋보기 내부 클릭으로 원본 요소 조작
• 고정된 2배 확대 배율
• 크기 조정 가능 (300px ~ 800px 권장)

🚫 주의사항

1. 필수 DOM 구조: #zoom-container와 #zoom-content 요소가 반드시 필요합니다
2. 성능: PIP 모드는 실시간 캡처로 인해 성능에 영향을 줄 수 있습니다
3. 포인터 이벤트: 돋보기 사용 시 배경 콘텐츠의 pointer-events를 적절히 관리해야 합니다
4. 정리: 페이지를 떠나기 전에 destroy() 메서드를 호출하여 리소스를 정리하세요

📱 모바일 지원

이 라이브러리는 터치 이벤트를 완전히 지원하므로 모바일 기기에서도 동일하게 작동합니다.

• 터치 드래그: 화면을 터치하여 드래그
• 터치 줌: zoom 모드에서 패닝 지원
• 터치 클릭: PIP 모드에서 돋보기 내부 터치로 원본 요소 조작

📝 라이센스

이 프로젝트는 MIT 라이센스 하에 배포됩니다.

🤝 기여하기

버그 리포트, 기능 요청, 풀 리퀘스트를 환영합니다!

dabeeomaps_magnifier

웹 콘텐츠를 위한 전체 화면 줌/패닝 및 PIP(Picture-in-Picture) 돋보기 기능을 제공하는 TypeScript 클래스입니다. 마우스와 터치 이벤트를 모두 지원하여 데스크톱과 모바일 환경에서 일관된 사용자 경험을 제공합니다.

✨ 주요 기능

• ✅ 전체 화면 줌 & 패닝: 컨테이너 전체를 지정된 배율로 확대하고, 마우스나 손가락으로 드래그하여 콘텐츠를 탐색할 수 있습니다.
• ✅ PIP 돋보기 모드: 마우스 커서나 터치 지점을 따라다니는 원형 돋보기로 특정 영역을 상세하게 볼 수 있습니다.
• ✅ 터치 & 마우스 완벽 지원: 데스크톱의 마우스 이벤트와 모바일의 터치 이벤트를 모두 처리합니다.
• ✅ 클릭 및 드래그 구분: 단순 클릭과 드래그를 구분하여, 돋보기 모드에서도 콘텐츠 내부 요소와 상호작용(예: 버튼 클릭)이 가능합니다.
• ✅ 동적 콘텐츠 지원: MutationObserver를 사용하여 DOM 콘텐츠가 변경될 때 PIP 돋보기 이미지를 자동으로 업데이트합니다.

Version History

• 0.0.1 : npm publish
• 0.0.2 :
  • pip 돋보기 사이즈 조절 가능
  • pip 돋보기 내부 드래그로 돋보기 이동 가능
• 0.0.3 :
  • README.MD 가이드 작성