Slider는 리스트 형태의 콘텐츠를 좌우 또는 상하 방향으로 자연스럽게 반복 이동시킵니다.

방향과 속도를 자유롭게 설정할 수 있으며, 마우스 오버 시 자동으로 일시 정지됩니다.

coForward Slider는 컨테이너 안의 첫 번째 ul 목록을 복제한 뒤 requestAnimationFrame()으로 자동 이동시키는 사내 공통 JavaScript 컴포넌트입니다.

별도 스타일 파일은 사용하지 않습니다. Slider.js가 실행되면 컨테이너와 ul에 필요한 기본 표시 설정을 코드에서 직접 적용합니다.

이 문서에서 다루는 기능

필수 준비물

• Slider 클래스 파일
• 슬라이더를 표시할 HTML 컨테이너
• 컨테이너 안의 첫 번째 ul 목록
• ES Module을 지원하는 브라우저 또는 프로젝트 번들러

HTML 작성

슬라이더 컨테이너 안에 하나의 ul 목록을 준비합니다.

<div id="exchangeRateSlider">
    <ul>
        <li>USD/KRW 1,380.50원 ▲ 2.30</li>
        <li>EUR/KRW 1,492.80원 ▼ 1.20</li>
        <li>JPY/KRW(100엔) 928.40원 ▲ 0.75</li>
        <li>CNY/KRW 190.65원 ▼ 0.18</li>
    </ul>
</div>

<script type="module" src="/js/exchange-rate-slider.js"></script>

클래스 불러오기

페이지용 JavaScript 파일에서 클래스를 import합니다.

// exchange-rate-slider.js
import Slider from '/path/to/Slider.js';

슬라이더는 다음 순서로 생성합니다.

import Slider from '/path/to/Slider.js';

const container = document.getElementById('exchangeRateSlider');

if (!container) {
    throw new Error('슬라이더 컨테이너를 찾을 수 없습니다.');
}

const slider = new Slider(container, 'left');
slider.setSpeed(0.5);

기본 적용 순서

HTML 컨테이너와 ul 목록 준비
↓
클래스 import
↓
컨테이너 요소 조회
↓
인스턴스 생성
↓
필요 시 속도 또는 방향 변경

Slider는 컨테이너 안의 첫 번째 ul을 기준으로 동작합니다.

기본 구조

<div id="logoSlider">
    <ul>
        <li>Alpha</li>
        <li>Beta</li>
        <li>Gamma</li>
        <li>Delta</li>
    </ul>
</div>

컨테이너 안에 ul이 없으면 슬라이드가 시작되지 않습니다.

초기화 후 내부 동작

new Slider(container, direction)을 호출하면 다음 처리가 실행됩니다.

방향별 목록 구조

가로 방향(left, right)은 일반 ul > li 구조를 그대로 사용할 수 있습니다.

<div id="horizontalSlider">
    <ul>
        <li>항목 1</li>
        <li>항목 2</li>
        <li>항목 3</li>
    </ul>
</div>

세로 방향(up, down)도 같은 HTML 구조를 사용합니다.

<div id="verticalSlider">
    <ul>
        <li>첫 번째 공지</li>
        <li>두 번째 공지</li>
        <li>세 번째 공지</li>
    </ul>
</div>

생성자 두 번째 인자 또는 setDirection()으로 방향을 지정합니다.

const slider = new Slider(container, 'left');

실행 중 방향을 변경할 수도 있습니다.

slider.setDirection('up');

유효하지 않은 값을 전달하면 방향은 변경되지 않고 Console에 경고가 출력됩니다.

slider.setDirection('left');
slider.setDirection('wrong'); // Invalid direction 경고

setSpeed(speed)로 슬라이드 속도를 변경합니다.

slider.setSpeed(0.5);

speed는 0보다 큰 숫자만 적용됩니다.

slider.setSpeed(1);
slider.setSpeed(0);      // 적용되지 않음
slider.setSpeed('fast'); // 적용되지 않음

Slider는 기본적으로 마우스 이벤트를 등록합니다.

필요하면 메서드로 직접 제어할 수 있습니다.

<button id="stopSlider" type="button">정지</button>
<button id="startSlider" type="button">시작</button>

const stopButton = document.getElementById('stopSlider');
const startButton = document.getElementById('startSlider');

stopButton.addEventListener('click', () => {
    slider.stopSlide();
});

startButton.addEventListener('click', () => {
    slider.startSlide();
});

startSlide()는 이미 실행 중이면 중복 실행하지 않습니다.

아래 예제는 KRW 기준 환율 목록을 왼쪽 방향으로 자동 슬라이드하고, 버튼으로 속도와 정지 상태를 제어합니다.

표시된 환율은 사용 예시를 위한 임의의 값입니다.

HTML

<div id="exchangeRateSlider">
    <ul>
        <li>USD/KRW 1,380.50원 ▲ 2.30</li>
        <li>EUR/KRW 1,492.80원 ▼ 1.20</li>
        <li>JPY/KRW(100엔) 928.40원 ▲ 0.75</li>
        <li>CNY/KRW 190.65원 ▼ 0.18</li>
    </ul>
</div>

<button id="slowSlider" type="button">느리게</button>
<button id="fastSlider" type="button">빠르게</button>
<button id="stopSlider" type="button">정지</button>
<button id="startSlider" type="button">시작</button>

<script type="module" src="/js/exchange-rate-slider.js"></script>

JavaScript

import Slider from '/path/to/Slider.js';

const container = document.getElementById('exchangeRateSlider');
const slowButton = document.getElementById('slowSlider');
const fastButton = document.getElementById('fastSlider');
const stopButton = document.getElementById('stopSlider');
const startButton = document.getElementById('startSlider');

if (!container || !slowButton || !fastButton || !stopButton || !startButton) {
    throw new Error('슬라이더 적용에 필요한 HTML 요소가 없습니다.');
}

const slider = new Slider(container, 'left');

slowButton.addEventListener('click', () => {
    slider.setSpeed(0.3);
});

fastButton.addEventListener('click', () => {
    slider.setSpeed(1);
});

stopButton.addEventListener('click', () => {
    slider.stopSlide();
});

startButton.addEventListener('click', () => {
    slider.startSlide();
});

슬라이더가 시작되지 않습니다.

다음 항목을 확인합니다.

1. 클래스 파일이 올바른 경로에서 import되었는지 확인합니다.
2. 슬라이더 컨테이너가 실제로 존재하는지 확인합니다.
3. 컨테이너 안에 ul이 있는지 확인합니다.
4. ul 안에 표시할 li가 있는지 확인합니다.
5. 브라우저 개발자 도구의 Console 오류를 확인합니다.

const container = document.getElementById('exchangeRateSlider');
console.log(container);
console.log(container?.querySelector('ul'));

목록이 두 개로 늘어납니다.

정상 동작입니다. Slider는 무한 반복 표시를 위해 첫 번째 ul을 복제합니다.

const container = document.getElementById('exchangeRateSlider');
console.log(container.querySelectorAll('ul').length); // 2

슬라이드가 움직이지 않는 것처럼 보입니다.

목록의 실제 너비 또는 높이가 0이면 이동 범위를 계산할 수 없습니다.

다음 항목을 확인합니다.

• li에 내용이 있는지 확인합니다.
• 컨테이너와 ul이 display: none 상태에서 초기화되지 않았는지 확인합니다.
• new Slider(container, direction)이 컨테이너가 화면에 배치된 뒤 호출되는지 확인합니다.

방향이 변경되지 않습니다.

setDirection()에는 left, right, up, down 중 하나만 전달합니다.

slider.setDirection('right');
slider.setDirection('up');

잘못된 값을 전달하면 Console에 다음 경고가 출력됩니다.

Invalid direction. Use "left", "right", "up", or "down".

속도 변경이 적용되지 않습니다.

setSpeed()는 0보다 큰 숫자만 적용합니다.

slider.setSpeed(0.5); // 적용
slider.setSpeed(0);   // 적용되지 않음

같은 컨테이너에 다시 적용해야 합니다.

setContainer(container)를 호출하면 컨테이너를 다시 초기화합니다. 기존에 복제된 ul이 여러 개 있으면 첫 번째 ul만 남기고 나머지를 제거합니다.

slider.setContainer(container);

주요 속성

주요 메서드

© team coForward