HOWTO · JavaScript

JavaScript에서 전체 화면을 사용하는 방법

JavaScript로 요소에 전체 화면 모드를 요청하고, 종료하고, 전체 화면 상태 변화에 대응하는 방법을 알아봅니다.

이 페이지의 내용

브라우저의 전체 화면 API를 사용하면 원하는 요소에 전체 화면 전환을 요청하고, document.exitFullscreen()으로 종료하며, fullscreenchange를 감지해 인터페이스를 상태에 맞게 업데이트할 수 있습니다. 버튼 클릭 같은 사용자 동작에서 요청을 호출하고, 브라우저가 요청을 거부할 수 있으므로 반환된 프로미스를 처리하세요.

전체 화면 API 이해하기

전체 화면 모드는 동영상 플레이어, 게임, 프레젠테이션 또는 페이지 컨테이너처럼 특정 요소에 적용됩니다. 브라우저는 현재 활성화된 요소를 document.fullscreenElement로 제공합니다. 전체 화면인 요소가 없으면 값은 null입니다. 전체 화면 API의 동작은 브라우저가 제어하므로 사용자 동작, 브라우징 컨텍스트, 기기에 따라 요청을 사용할 수 없거나 거부될 수 있습니다.

메서드와 이벤트에 관한 자세한 내용은 MDN의 전체 화면 API 문서를 참조하세요.

방법 1: requestFullscreen()으로 전체 화면 모드 시작하기

확장할 요소를 선택한 다음 클릭에 대한 응답으로 requestFullscreen()을 호출하세요. 전체 화면 API를 사용하려면 일반적으로 HTTPS와 같은 보안 컨텍스트가 필요합니다. 페이지가 보안 컨텍스트가 아니거나 메서드가 없으면 사용할 수 없습니다. 사용자 동작으로 요청을 시작하지 않았거나 브라우징 컨텍스트 또는 기기에서 허용하지 않는 경우에도 요청이 거부될 수 있습니다. 다음 페이지 조각은 정적인 브라우저 예제입니다. API 동작은 브라우저에 따라 달라지며, 이 내용은 런타임 출력으로 제시하지 않습니다.

<button id="enter-fullscreen">Enter full screen</button>
<button id="exit-fullscreen">Exit full screen</button>
<div id="player">Video or other content</div>
<p id="status" role="status"></p>
<script>
const enterButton = document.getElementById('enter-fullscreen');
const exitButton = document.getElementById('exit-fullscreen');
const player = document.getElementById('player');
const status = document.getElementById('status');

enterButton.addEventListener('click', async () => {
  if (typeof player.requestFullscreen !== 'function') {
    status.textContent = 'Full-screen mode is unavailable.';
    return;
  }

  try {
    await player.requestFullscreen();
  } catch (error) {
    status.textContent = 'The browser did not enter full-screen mode.';
  }
});

exitButton.addEventListener('click', async () => {
  if (!document.fullscreenElement) return;
  try {
    await document.exitFullscreen();
  } catch (error) {
    status.textContent = 'The browser did not exit full-screen mode.';
  }
});

document.addEventListener('fullscreenchange', () => {
  const active = document.fullscreenElement === player;
  status.textContent = active
    ? 'Player is full screen.'
    : document.fullscreenElement
      ? 'Another element is full screen.'
      : 'Full-screen mode has ended.';
  enterButton.disabled = active;
  exitButton.disabled = !document.fullscreenElement;
});
</script>

앞의 브라우저 예제는 실제 DOM 요소를 사용합니다. 다음 예제는 대체 객체를 사용해 프로미스 처리 흐름과 요청 완료 후 반환되는 메시지를 보여 줍니다. 이 예제를 실행하세요.

const element = {
  requestFullscreen: () => Promise.resolve()
};

async function enterFullscreen(target) {
  await target.requestFullscreen();
  return 'Full-screen request completed';
}

enterFullscreen(element).then(console.log);
Full-screen request completed

페이지에서는 사용자 동작에 따른 요청이 되도록 클릭 핸들러 안에서 호출하세요. 벤더 접두사가 붙은 메서드를 지원의 보장으로 여기지 마세요. 표준 메서드가 있는지 확인하고, 메서드가 없거나 프로미스가 거부되어도 나머지 인터페이스를 사용할 수 있게 유지하세요. API를 사용할 수 없는 것 같다면 일반적으로 HTTPS와 같은 보안 컨텍스트에서 페이지가 제공되는지도 확인하세요.

방법 2: exitFullscreen()으로 전체 화면 모드 종료하기

전체 화면 모드를 종료하려면 document.exitFullscreen()을 호출하세요. 이 메서드도 프로미스를 반환하므로 진입 요청과 마찬가지로 거부를 처리해야 합니다. 사용자는 브라우저나 기기의 제어 기능으로도 전체 화면을 종료할 수 있습니다. 페이지의 종료 버튼만이 모드를 끝낼 수 있다고 가정하지 말고, 인터페이스가 그 변경 사항을 반영하게 하세요.

예를 들어 브라우저 페이지에서 종료 버튼에 클릭 핸들러를 연결하고 document.fullscreenElement가 있을 때 document.exitFullscreen()을 호출할 수 있습니다. 프로미스가 거부되면 이를 처리하고 유용한 상태 메시지를 표시하세요. 이 정적 설명은 실제 브라우저 상호작용을 실행한 것이 아닙니다.

방법 3: 전체 화면 변경 이벤트 처리하기

document에서 fullscreenchange 이벤트를 수신하세요. 이 이벤트는 전체 화면 상태가 바뀔 때 발생하며, 사용자가 브라우저 제어 기능으로 종료하는 경우도 포함됩니다. 이벤트가 발생할 때마다 document.fullscreenElement를 확인하세요. 값이 null이 아니면 현재 전체 화면인 요소가 있다는 뜻이고, null이면 전체 화면이 종료된 것입니다. 이 상태에 따라 버튼 레이블, 상태 텍스트 또는 다른 컨트롤을 업데이트할 수 있습니다. CSS의 :fullscreen 의사 클래스는 브라우저가 요소를 전체 화면으로 표시하는 동안 해당 요소에 스타일을 적용합니다.

결론

사용자 동작에서 선택한 요소의 requestFullscreen()을 호출하고 반환된 프로미스를 처리하세요. 종료 컨트롤을 제공한다면 document.exitFullscreen()을 사용하세요. fullscreenchange와 document.fullscreenElement를 확인하면 페이지 밖에서 시작된 종료도 인터페이스에 반영할 수 있습니다. 브라우저와 기기에 따라 동작이 다를 수 있으므로 전체 화면이 아닌 상태에서도 사용할 수 있는 경로를 제공하세요.

자주 묻는 질문

  1. 요소가 전체 화면 모드인지 어떻게 확인하나요? document.fullscreenElement가 해당 요소인지 확인하세요. 활성 요소가 없으면 값은 null입니다.

  2. 모든 요소를 전체 화면으로 전환할 수 있나요? API는 요소를 받지만 브라우저 정책과 주변 브라우징 컨텍스트에 따라 요청 성공 여부가 달라질 수 있습니다. 사용자 동작에서 요청하고 실패를 처리하세요.

  3. requestFullscreen() 호출이 실패할 수 있는 이유는 무엇인가요? 페이지가 일반적으로 HTTPS와 같은 보안 컨텍스트가 아닌 경우를 비롯해 메서드를 사용할 수 없는 상황이 있습니다. 사용자 동작 없이 요청했거나 현재 브라우징 컨텍스트 또는 기기에서 요청을 거부할 수도 있습니다. 메서드 사용 가능 여부를 확인하고 반환된 프로미스를 처리하세요.

  4. 전체 화면 콘텐츠에 스타일을 어떻게 적용하나요? 요소가 전체 화면 모드인 동안 적용할 스타일에는 CSS :fullscreen 의사 클래스를 사용하세요.