UI Components ko

UI 컴포넌트

English

ivLyrics UI 컴포넌트에 대한 문서입니다.

---

개요

ivLyrics는 모든 UI 컴포넌트에 Spicetify의 React를 사용합니다. 컴포넌트는 모듈식이며 애플리케이션 전체에서 재사용할 수 있습니다.

---

주요 컴포넌트

FullscreenOverlay.js

전체 화면 가사 경험을 제공합니다.

기능:

• 애니메이션이 있는 가사 표시
• 앨범 아트 / 비디오 배경
• TV 모드 (앰비언트 디스플레이)
• 컨트롤 오버레이

사용법:

// 전체 화면 토글
window.dispatchEvent(new CustomEvent('ivLyrics:toggleFullscreen'));

// 전체 화면인지 확인
const isFullscreen = document.querySelector('.ivlyrics-fullscreen-container');

주요 클래스:

• .ivlyrics-fullscreen-container - 메인 컨테이너
• .ivlyrics-fullscreen-lyrics - 가사 영역
• .ivlyrics-fullscreen-controls - 컨트롤 버튼
• .ivlyrics-tv-mode - TV 모드 상태

---

Settings.js

종합적인 설정 인터페이스입니다.

섹션:

• 일반 설정
• 표시 설정
• 번역 설정
• AI 제공자
• 가사 제공자
• 키보드 단축키
• 고급 설정

설정 저장:

• SettingsObject를 통해 localStorage 사용
• 키는 ivLyrics: 접두사 사용

---

OptionsMenu.js

가사 상호작용을 위한 컨텍스트 메뉴입니다.

기능:

• 번역/발음 토글
• 싱크 오프셋 컨트롤
• 공유 기능
• 제공자 선택

트리거:

• 가사 영역 위에 마우스 올리기
• 가사에서 우클릭

---

SetupWizard.js

첫 실행 설정 마법사입니다.

단계:

1. 언어 선택
2. AI 제공자 설정
3. 가사 제공자 설정
4. 기능 소개

트리거:

// 설정 마법사 표시
window.ivLyricsShowSetupWizard?.();

---

SyncDataCreator.js

단어 수준 싱크 데이터를 만드는 도구입니다.

기능:

• 재생/일시정지 컨트롤
• 탭하여 싱크 인터페이스
• 타이밍 검토 및 편집
• 저장 및 공유

접근:

• 설정 > 싱크 데이터 생성기
• 옵션 메뉴 > 싱크 데이터 생성

---

NowPlayingPanelLyrics.js

Spotify의 Now Playing 패널에 가사를 통합합니다.

기능:

• 컴팩트 가사 뷰
• 자동 스크롤
• 번역 표시

활성화:

• 설정 > 표시 > Now Playing 패널

---

SongInfoTicker.js

스크롤되는 곡 정보 표시입니다.

기능:

• 제목 및 아티스트
• 번역된 메타데이터
• TMI (Track Music Info)

---

NoticeSystem.js

사용자 피드백을 위한 알림 시스템입니다.

사용법:

// 알림 표시
window.ivLyricsNotice?.show({
    type: 'success' | 'error' | 'info' | 'warning',
    message: '알림 메시지',
    duration: 3000  // 밀리초
});

// 모두 닫기
window.ivLyricsNotice?.dismissAll();

---

TabBar.js

탭 네비게이션 컴포넌트입니다.

사용법:

const tabs = [
    { id: 'tab1', label: '탭 1' },
    { id: 'tab2', label: '탭 2' }
];

const TabComponent = TabBar({
    tabs,
    activeTab: 'tab1',
    onTabChange: (tabId) => console.log('선택됨:', tabId)
});

---

Pages.js

페이지 라우팅 및 컨테이너 컴포넌트입니다.

사용 가능한 페이지:

• 메인 가사 페이지
• 설정 페이지
• 싱크 데이터 생성기
• 디버그 페이지

---

스타일링

CSS 구조

메인 스타일시트: style.css

주요 셀렉터:

/* 메인 컨테이너 */
.ivlyrics-container { }

/* 가사 줄 */
.ivlyrics-line { }
.ivlyrics-line.active { }

/* 번역 */
.ivlyrics-translation { }

/* 발음 */
.ivlyrics-phonetic { }

/* 노래방 단어 */
.ivlyrics-word { }
.ivlyrics-word.sung { }

CSS 변수

:root {
    --ivlyrics-primary: #1db954;
    --ivlyrics-text: #ffffff;
    --ivlyrics-text-dim: rgba(255, 255, 255, 0.6);
    --ivlyrics-background: rgba(0, 0, 0, 0.8);
}

---

컴포넌트 만들기

기본 React 컴포넌트

function MyComponent(props) {
    const React = Spicetify.React;
    const { useState, useEffect } = React;

    const [state, setState] = useState(initialValue);

    useEffect(() => {
        // 부수 효과
        return () => {
            // 정리
        };
    }, [dependencies]);

    return React.createElement('div', 
        { className: 'my-component' },
        React.createElement('span', null, '내용')
    );
}

훅과 함께

function SettingsToggle({ settingKey, label }) {
    const React = Spicetify.React;
    const { useState, useEffect } = React;

    const [enabled, setEnabled] = useState(false);

    useEffect(() => {
        const saved = SettingsObject.get(settingKey, false);
        setEnabled(saved);
    }, [settingKey]);

    const handleToggle = () => {
        const newValue = !enabled;
        setEnabled(newValue);
        SettingsObject.set(settingKey, newValue);
    };

    return React.createElement('div', { className: 'toggle-setting' },
        React.createElement('label', null, label),
        React.createElement('button', {
            className: enabled ? 'active' : '',
            onClick: handleToggle
        }, enabled ? 'ON' : 'OFF')
    );
}

---

모범 사례

1. Spicetify의 React 사용: 항상 Spicetify.React 사용
2. 효과 정리: useEffect에서 정리 함수 반환
3. 문자열 지역화: 사용자에게 보이는 모든 텍스트에 _t() 사용
4. CSS 스코핑: 클래스에 ivlyrics- 접두사 사용
5. 이벤트 정리: 언마운트 시 이벤트 리스너 제거

---

관련 문서

• 아키텍처 개요 - 프로젝트 구조
• 핵심 모듈 - 핵심 시스템 문서
• API 레퍼런스 - API 문서