위치·크기·이동 영역

위치·크기·이동 영역 — 소스라이브 플레이어

⏱ 예상 소요 시간: 5~10분

🔧 선택 단계 — 생략하면 기본 크기·위치로 동작합니다

위치·크기·이동 영역

플로팅 플레이어를 어디에 얼마나 크게 띄울지, 어느 범위 안에서 움직이게 할지 정합니다. 아래 옵션은 초기화 방식(setInit · setOnAirInit)과 UI 레이아웃(컨트롤형 · 배지형)에 관계없이 동일하게 적용됩니다. 전체 파라미터는 파라미터 레퍼런스 — setFloatingType에 있습니다.

파라미터	타입	필수	기본값	설명
type	'basic' \| 'scroll'	필수	—	플로팅 모드 타입
size	{ width, height? }	선택	—	플로팅 플레이어 크기. CSS 값으로 지정합니다. (예: `{ width: '135px', height: '230px' }`)
position	{ position, offsetX?, offsetY? }	선택	`bottom right`	플로팅 노출 위치. `'top left'` · `'top right'` · `'bottom left'` · `'bottom right'` 중 선택 기본 20px 여백이 적용되며, `offsetX`/`offsetY`로 미세 조정할 수 있습니다.
restrictionArea	{ element? \| elementId? }	선택	—	플로팅 플레이어가 이동할 수 있는 영역을 특정 HTML 요소 안으로 제한합니다.
layout	{ type, badgeImageUrl?, buttonList? }	선택	`{ type: 'control' }`	작은 창 위에 그릴 UI를 지정합니다. `type` — `'control'`(기본, 버튼형) 또는 `'badge'`(LIVE 배지형) `badgeImageUrl` — 배지형 전용, 배지 이미지 교체 `buttonList` — 컨트롤형 전용, 노출할 버튼 지정. `'exit'` 닫기 · `'mute'` 음소거 · `'fullscreen'` 확대. 미설정 시 기본 3개 자세한 내용은 작은 창 UI 레이아웃에 있습니다.

⚠️ layout.buttonList는 1개 또는 3개만 지정하세요. 2개만 지정하면 기본 3개 구성(['exit','mute','fullscreen'])으로 되돌아갑니다. 버튼 2개용 레이아웃이 없어 의도적으로 그렇게 처리됩니다.

JavaScript — 커스텀 옵션 예시

window.SauceLiveLib.setInit({ broadcastId: '라이브ID를 입력해주세요' });
window.SauceLiveLib.setFloatingType({
  type: 'basic',
  size: { width: '135px', height: '230px' },
  restrictionArea: { element: document.body },
  position: { position: 'bottom right' },
  layout: { type: 'control', buttonList: ['exit'] }  // 닫기 버튼만 노출
});
window.SauceLiveLib.load();

📌 드래그와 스냅(자동 정렬)은 기본 플로팅(basic) 전용입니다. 기본 플로팅에서는 시청자가 플로팅 플레이어를 끌어서 옮길 수 있고, 손을 떼면 화면 모서리(상단 좌/우, 하단 좌/우) 중 가장 가까운 곳으로 자동 정렬됩니다. 별도 설정 없이 적용되며, restrictionArea로 이동 영역을 제한한 경우 그 영역의 모서리를 기준으로 정렬됩니다.
스크롤 플로팅(scroll)은 위치가 고정되어 시청자가 옮길 수 없습니다. 단 position으로 노출 위치를 지정하는 것은 두 모드 모두 가능합니다 — "개발자가 위치를 정하는 것"과 "시청자가 옮기는 것"은 다른 기능입니다.

다음 단계

🖲 버튼 동작·이벤트 추적 — 기본 동작 교체와 태깅

→