Fullscreen API

Fullscreen API는 특정 Element(와 그 자손들)를 전체화면 모드로 표시하고, 더 이상 필요하지 않을 때 전체화면 모드를 종료하는 메서드를 추가해요. 이것은 온라인 게임과 같은 원하는 콘텐츠를 사용자의 전체 화면을 사용하여 표시할 수 있게 해주며, 전체화면 모드가 꺼질 때까지 모든 브라우저 사용자 인터페이스 요소와 다른 애플리케이션을 화면에서 제거해요.

API를 사용하는 방법에 대한 자세한 내용은 Fullscreen API 가이드 문서를 참조하세요.

인터페이스 (Interfaces)

참고: Fullscreen API는 자신만의 고유한 인터페이스(클래스)를 갖고 있지 않습니다. 그 대신, 다른 기존 인터페이스들에 풀스크린 기능을 제공하는 데 필요한 메서드, 속성, 이벤트 핸들러를 살짝 얹어서(augments) 기능을 추가합니다. 추가된 내용들은 다음 섹션들에 정리되어 있습니다.

---

인스턴스 메서드 (Instance methods)

Fullscreen API는 전체 화면 모드를 켜고 끌 수 있도록 Document와 Element 인터페이스에 유용한 메서드들을 추가합니다.

Document 인터페이스에 추가된 인스턴스 메서드

Document.exitFullscreen()

사용자 에이전트(브라우저)에게 현재 켜져 있는 전체 화면 모드를 종료하고 원래의 창(windowed) 모드로 돌아가 달라고 요청합니다. 이 메서드는 전체 화면이 완전히 해제되고 나면 이행(resolve)되는 Promise를 반환합니다.

Element 인터페이스에 추가된 인스턴스 메서드

Element.requestFullscreen()

브라우저에게 특정 요소(그리고 당연히 그 안에 들어있는 자식 요소들까지)를 화면 전체에 꽉 차게 띄워달라고 요청합니다. 이때 브라우저의 UI 요소(주소창, 탭 등)는 물론 다른 애플리케이션의 화면까지 모두 가려집니다. 전체 화면 모드가 성공적으로 활성화되면 이행(resolve)되는 Promise를 반환합니다.

---

인스턴스 속성 (Instance properties)

Document.fullscreenElement / ShadowRoot.fullscreenElement

fullscreenElement 속성은 현재 DOM(또는 Shadow DOM)에서 전체 화면 모드로 띄워져 있는 Element가 무엇인지 정확히 알려줍니다. 만약 이 값이 null이라면, 현재 문서(또는 Shadow DOM)는 전체 화면 모드가 아니라는 뜻입니다.

Document.fullscreenEnabled

fullscreenEnabled 속성은 현재 전체 화면 모드를 실행하는 것이 가능한 상태인지 아닌지를 알려줍니다. 만약 브라우저 설정에서 전체 화면 권한("fullscreen")을 막아두었거나 브라우저 자체가 지원하지 않는 등 어떤 이유로든 전체 화면을 켤 수 없는 상황이라면 false를 반환합니다.

사용 중단된 속성들 (Obsolete properties)

Document.fullscreen Deprecated

문서 안에 현재 전체 화면으로 띄워진 요소가 있다면 true를 반환하고, 그렇지 않으면 false를 반환하던 불리언(Boolean) 속성입니다.

---

이벤트 (Events)

fullscreenchange

어떤 Element가 전체 화면 모드로 들어가거나 빠져나올 때(전환될 때) 해당 요소로 발송되는 이벤트입니다.

fullscreenerror

어떤 요소를 전체 화면 모드로 전환하거나 해제하려다 에러가 발생했을 때 해당 Element로 발송되는 이벤트입니다.

💡 강사의 팁: fullscreenchange 이벤트는 생각보다 아주 유용합니다. 사용자가 브라우저 UI(예: 뒤로가기 버튼)나 키보드(ESC 키)를 통해 강제로 전체 화면을 꺼버렸을 때, 자바스크립트에서 이를 감지하고 화면 레이아웃이나 아이콘(전체 화면 아이콘 -> 축소 아이콘)을 원래대로 복구하는 등 상태 동기화를 할 때 꼭 필요한 이벤트입니다!

---

접근 제어하기 (Controlling access)

전체 화면 모드를 사용할 수 있는지 여부는 권한 정책(Permissions Policy)을 통해 깐깐하게 제어할 수 있습니다. 전체 화면 기능은 문자열 "fullscreen"으로 식별되며, 기본 허용 목록(allowlist) 값은 "self"입니다. 즉, 별도의 설정을 건드리지 않아도 최상위 문서 컨텍스트에서는 당연히 전체 화면이 허용되고, 이 최상위 문서와 동일한 출처(same origin)를 가진 중첩된 iframe 등에서도 문제없이 전체 화면을 띄울 수 있다는 뜻입니다.

만약 출처가 다른 유튜브 영상 등을 iframe으로 가져왔는데 전체 화면을 허용하고 싶다면, allow="fullscreen" 속성을 명시적으로 적어주어야 합니다!

---

사용 팁 (Usage notes)

사용자들은 사이트나 앱이 스크립트를 통해 전체 화면을 꺼줄 때까지 얌전히 기다리지 않습니다. 그냥 키보드의 ESC 키나 F11 키를 쿨하게 눌러서 스스로 전체 화면 모드를 빠져나올 수 있죠. 따라서 여러분은 사용자 인터페이스(UI) 어디엔가 "버튼을 눌러서도 전체 화면을 종료할 수 있다"는 사실을 알려주는 적절한 UI 요소(예: 'X' 버튼이나 안내 문구)를 반드시 제공해야 합니다.

💡 참고: 사용자가 다른 페이지로 이동(Navigate)하거나, 탭을 전환하거나, 아니면 Alt-Tab 같은 단축키로 완전히 다른 프로그램으로 넘어가 버리는 경우에도 브라우저는 얄짤없이 전체 화면 모드를 자동으로 종료해버립니다.

---

예제 (Examples)

간단한 전체 화면 띄우기 (Simple fullscreen usage)

이 예제에서는 웹 페이지 안에 비디오가 하나 들어있습니다. 사용자가 키보드의 Enter 키를 누르면, 비디오가 원래 크기의 창 모드와 꽉 찬 전체 화면 모드를 휙휙 오가게(toggle) 만들 수 있습니다.

라이브 예제 보기 (View Live Example)

Enter 키 감시하기 (Watching for the Enter key)

페이지 로딩이 끝나면, 아래 코드가 실행되면서 Enter 키가 눌리는지를 눈을 부릅뜨고 감시하는 이벤트 리스너를 설치합니다.

const video = document.getElementById("video");

// ENTER 키가 눌리면 toggleFullScreen 메서드를 호출합니다!
document.addEventListener("keydown", (e) => {
  if (e.key === "Enter") {
    toggleFullScreen(video);
  }
});

전체 화면 모드 토글하기 (Toggling fullscreen mode)

사용자가 Enter 키를 치면 바로 위에서 설정한 이벤트 핸들러가 아래의 함수를 호출합니다.

function toggleFullScreen(video) {
  // 문서에 현재 전체 화면인 요소가 없다면 (즉, 현재 창 모드라면)
  if (!document.fullscreenElement) {
    // 비디오 요소를 전체 화면으로 꽉 차게 만듭니다!
    video.requestFullscreen();
  } else {
    // 그게 아니라면(이미 전체 화면이라면) 전체 화면을 빠져나옵니다.
    // (선택적 체이닝 '?.'을 사용해서 혹시 모를 에러를 방지하는 센스!)
    document.exitFullscreen?.();
  }
}

이 코드는 가장 먼저 document의 fullscreenElement 속성이 어떤 값을 가지고 있는지 슬쩍 확인합니다.
만약 그 값이 null이라면, 문서는 현재 얌전한 창(windowed) 모드에 있다는 뜻이므로 전체 화면으로 전환을 시도해야 합니다. (그렇지 않다면, 현재 무언가가 전체 화면으로 떡하니 떠 있다는 뜻이겠죠.) 전체 화면으로의 전환은 우리가 타겟으로 삼은 <video> 요소에 대고 Element.requestFullscreen()을 힘차게 호출하면 끝납니다.

만약 전체 화면 모드가 이미 활성화되어 있다면 (fullscreenElement가 null이 아니라면), 우리는 쿨하게 document에 대고 exitFullscreen()을 호출해서 전체 화면 모드의 전원을 꺼버립니다.

💡 강사의 팁: 여기서 정말 주의하셔야 할 점! 전체 화면을 '요청(request)'할 때는 특정 요소(video)한테 요청을 하지만, 전체 화면을 '종료(exit)'할 때는 특정 요소가 아니라 문서 전체(document)에 대고 종료 명령을 내려야 한다는 점입니다. 초보자분들이 video.exitFullscreen()이라고 적어놓고 왜 안 꺼지냐고 며칠 밤을 새우는 경우가 정말 많으니 절대 헷갈리지 마세요!