[해피CGI][cgimall] jQuery 360도 상품 이미지 회전 뷰어 플러그인 Turntable.js

# 라이센스

 

Turntable.js는 MIT 라이센스로 제공되는 jQuery 플러그인입니다.

MIT 라이센스는 비교적 자유로운 오픈소스 라이센스로, 라이센스 고지 조건을 준수하면 개인 프로젝트, 상업용 프로젝트, 웹사이트 제작, 쇼핑몰 상품 상세 페이지 등 다양한 용도로 활용할 수 있습니다.

단, 실제 프로젝트에 적용하기 전에는 배포 파일 또는 GitHub 저장소에 포함된 라이센스 파일을 함께 확인하는 것이 좋습니다.

공식 안내 기준 라이센스: MIT

출처: jQueryScript / GitHub PolarNotion Turntable.js

# 특징 및 설명

 

Turntable.js는 상품 이미지를 360도 회전하는 것처럼 보여주기 위한 jQuery 기반 이미지 로테이터 플러그인입니다.

일반적인 3D 모델링 방식이 아니라, 여러 각도에서 촬영한 이미지들을 순서대로 배치한 뒤 사용자의 마우스 움직임 또는 손가락 터치 움직임에 따라 이미지를 바꿔 보여주는 방식입니다.

예를 들어 상품을 10도 또는 15도 간격으로 여러 장 촬영해 두면, 사용자가 좌우로 드래그하거나 마우스를 움직일 때 이미지가 순차적으로 전환되면서 상품이 회전하는 것처럼 보입니다.

반응형 이미지 구성이 가능하며, 이미지의 가로 폭을 100%로 설정하여 컨테이너 크기에 맞게 출력할 수 있습니다.

마우스 이동 방향에 따라 이미지를 전환할 수 있으며, 기본적으로 x축 방향 움직임을 기준으로 작동합니다.

설정에 따라 y축 방향 또는 스크롤 기반 전환도 사용할 수 있습니다.

이미지 순서를 반대로 재생하는 reverse 옵션도 지원합니다.

상품 상세페이지, 제품 소개 페이지, 포트폴리오, 피규어·가구·전자제품·의류·기계 부품 등 여러 각도에서 보여줘야 하는 콘텐츠에 적합합니다.

브라우저 지원 안내에는 Chrome, IE9+, Firefox, Opera, Safari가 포함되어 있습니다.

주의할 점은 이 플러그인이 실제 3D 렌더링을 하는 것이 아니라 여러 장의 이미지를 빠르게 전환하는 방식이라는 점입니다. 따라서 자연스러운 360도 효과를 내려면 상품을 일정한 각도와 동일한 조명, 동일한 배경에서 촬영한 이미지 세트가 필요합니다.

# 사용 방법 & 설치 방법

1. 필요한 CSS/JS 파일을 설치하고 포함시키세요.

  브라우저 우선 설정을 하려면 컴파일된 파일을 다운로드하고 IIFE 스크립트 앞에 CSS를 포함시키세요. 

  Turntable v2는 jQuery를 필요로 하지 않습니다. 

<link rel="stylesheet" href="dist/turntable.css">

<script src="dist/turntable.iife.min.js"></script>

2. npm 프로젝트의 경우, scoped 패키지를 설치하고 클래스와 스타일시트를 가져오세요.

npm install @goboldlyforward/turntable

import { Turntable } from "@goboldlyforward/turntable";

import "@goboldlyforward/turntable/css";

 

3. 직접적인 자식 요소를 가진 컨테이너를 생성합니다 .
  각 프레임은 값을 가진 ul직접적인 요소를 사용합니다 .
  Turntable은 이러한 요소를 자동으로 생성해 줍니다. 또한 값을 읽어 DOM 속성을 통해 각 URL을 할당합니다.

<div id="shoeSpin" class="turntable">

  <ul>

    <li data-img-src="images/shoe-angle-01.webp"></li>

    <li data-img-src="images/shoe-angle-02.webp"></li>

    <li data-img-src="images/shoe-angle-03.webp"></li>

    <li data-img-src="images/shoe-angle-04.webp"></li>

    <li data-img-src="images/shoe-angle-05.webp"></li>

    <li data-img-src="images/shoe-angle-06.webp"></li>

  </ul>

</div>

4. 턴테이블을 초기화하여 포인터 기반 360도 이미지 뷰어를 생성합니다.

const cameraViewer = new Turntable("#cameraSpin", {

  axis: "x"

});

 

5. 사용 가능한 모든 구성 옵션.

 

- axis( "x" | "y" | "scroll"): 프레임 선택의 입력 방향을 설정합니다. "x"수평 포인터 이동, "y"수직 포인터 이동 또는 "scroll"뷰포트 기반 프레임 변경에 사용합니다.

- reverse( boolean): 상호 작용 중 프레임 순서를 반전시킵니다. 소스 이미지가 원하는 UI 동작과 반대 방향으로 회전하는 경우에 사용하십시오.

- scrollStart( "top" | "middle" | "bottom"): 스크롤 기반 회전을 위한 뷰포트 앵커를 설정합니다. 이 옵션은 axis를 사용하는 경우에만 적용됩니다 "scroll".

- autorotate( false | number): 초기화 시 자동 프레임 순환을 시작합니다. 프레임당 밀리초를 설정할 숫자를 전달하세요.

- controller( HTMLInputElement | null): 범위 입력을 뷰어에 연결합니다. 사용자가 범위를 변경하면 프레임이 설정되고, 뷰어의 프레임이 변경되면 범위 값이 업데이트 됩니다.

 

 

6. API 메서드.

// Jump to a specific frame index.

// The class clamps the value to the available frame range.

viewer.setFrame(3);

// Start automatic frame cycling.

// Pass a number to override the configured interval.

viewer.start(200);

// Stop automatic frame cycling.

viewer.stop();

// Recalculate frame sections.

// Call this after layout changes or after a hidden container becomes visible.

viewer.update();

// Remove listeners, observers, timers, and the active frame class.

viewer.destroy();

 

# 참고사항

- Turntable.js는 비교적 오래전에 공개된 플러그인이므로 최신 프론트엔드 환경에서는 직접 테스트 후 적용하는 것이 좋습니다.

- 특히 모바일 터치, 최신 jQuery 버전, 반응형 레이아웃, 이미지 지연 로딩, CDN 환경 등에서는 실제 운영 페이지에서 정상 작동 여부를 반드시 확인하는 것이 좋습니다.

- 파일 크기 안내 기준으로 jQueryScript 페이지에는 2.59MB로 표시되어 있습니다. 실제 적용 시에는 예제 이미지나 데모 파일까지 포함된 용량일 수 있으므로, 운영 사이트에는 필요한 JS, CSS, 이미지 파일만 선별해서 업로드하는 것이 좋습니다.

- 이 플러그인은 360도 회전 효과 자체보다 이미지 품질과 촬영 방식이 더 중요합니다. 상품을 일정한 간격으로 촬영하지 않으면 회전이 부자연스럽게 보일 수 있습니다.

- 쇼핑몰 상품 상세페이지에 적용할 경우, 최소 12장 이상 이미지를 준비하는 것이 좋고, 더 부드러운 회전을 원한다면 24장, 36장 이상의 이미지 세트를 사용하는 것이 좋습니다.

- 이미지 수가 많아질수록 로딩 속도에 영향을 줄 수 있으므로, 이미지 용량 최적화가 필요합니다.

- WebP 형식 사용, 썸네일 압축, lazy loading 적용, CDN 사용 등을 함께 고려하면 사용자 체감 속도를 개선할 수 있습니다.

- 적용 추천 분야는 쇼핑몰 상품 상세페이지, 제품 소개 페이지, 기계 장비 소개, 가구·인테리어 제품 소개, 피규어·소품 소개, 자동차·부품 소개, 전시품 소개 페이지 등입니다.