레이아웃 시스템

TV SDK의 선언적 레이아웃 시스템을 사용하여 컨트롤바 UI를 커스터마이징하는 방법을 안내합니다.

레이아웃 구조

5개 섹션(top,upper,center,lower,bottom)과seekbar로 구성된 선언적 레이아웃입니다.

사용 가능한 아이템

아이템	설명
`PlayBtn`	재생/일시정지/다시재생
`BigPlayBtn`	중앙 대형 재생 + 이전/다음
`BackBtn`	뒤로가기
`SeekBar`	탐색바 (D-pad 좌/우로 ±10초 시킹)
`SkipBackBtn` / `SkipForwardBtn`	±10초 시킹
`PrevBtn` / `NextBtn` / `NextPrevBtn`	트랙 이동
`TimeBtn` / `CurrentTimeBtn` / `DurationBtn`	시간 표시 (라이브 시 LIVE 인디케이터)
`MuteBtn` / `VolumeBtn`	음소거/볼륨 (TV에서는 뮤트 토글)
`SubtitleBtn`	자막 메뉴
`SettingBtn`	설정 메뉴
`MetaDesc`	영상 메타정보
`Blank` / `BlankBtn`	빈 공간

TV에서 제거된 아이템: FullscreenBtn, PipBtn, ShareBtn — 레이아웃에 포함해도 무시됩니다.

커스텀 레이아웃 예제

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        top: [
            { items: ['BackBtn'], wrapper: 'Group' },
            { items: ['MetaDesc'] },
            { wrapper: 'Blank', items: [] },
        ],
        center: [
            { items: ['BigPlayBtn'], align: 'center' },
        ],
        lower: [
            { wrapper: 'Blank', items: ['SeekBar'], align: 'center' },
        ],
        bottom: [
            { items: ['PlayBtn'], wrapper: 'Group' },
            { items: ['NextPrevBtn'], wrapper: 'Group' },
            { items: ['MuteBtn'], wrapper: 'Group' },
            { items: ['TimeBtn'], wrapper: 'Group' },
            { wrapper: 'Blank', items: [] },
            { items: ['SubtitleBtn', 'SettingBtn'], wrapper: 'Group' },
        ],
    }}
    onBack={() => navigation.goBack()}
/>

VOD/Live 변형

VOD와 Live에서 서로 다른 레이아웃을 사용할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        vod: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['SettingBtn'], wrapper: 'Group' },
            ],
        },
        live: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['MuteBtn'], wrapper: 'Group' },
            ],
        },
    }}
    onBack={() => navigation.goBack()}
/>

런타임 레이아웃 변경

ref 메소드를 통해 런타임에 레이아웃을 변경할 수 있습니다.

const playerRef = useRef<PlayerHandle>(null);

// 부분 업데이트 (merge=true, 기본값)
playerRef.current?.layout(
    { bottom: [{ items: ['PlayBtn'], wrapper: 'Group' }] },
    true
);

// 전체 교체 (merge=false)
playerRef.current?.layout(newLayout, false);

그룹 옵션

속성	타입	설명
`items`	string[]	레이아웃 아이템 목록
`wrapper`	'Blank' \| 'Group'	래퍼 타입
`align`	'left' \| 'right' \| 'center'	정렬
`size`	number	버튼 크기 (기본 88)