Fullscreen API 가이드 (Guide to the Fullscreen API)

안녕하세요! 이번에 우리가 정복할 MDN 문서는 웹 페이지를 화면 가득 시원하게 띄워주는 Fullscreen API 가이드입니다.

유튜브나 넷플릭스에서 영상을 볼 때, 화면 구석에 있는 '전체 화면' 버튼을 누르면 브라우저 주소창이나 컴퓨터 작업 표시줄이 싹 사라지고 영상만 꽉 차게 나오는 경험, 다들 해보셨죠? 바로 그 마법을 가능하게 해주는 API입니다. 이 글에서는 특정 요소를 어떻게 전체 화면 모드로 띄우는지, 그리고 브라우저가 전체 화면 모드로 들어가거나 나올 때 이를 어떻게 감지하는지 그 방법을 명쾌하게 설명해 드리겠습니다. 자, 시작해 볼까요!

---

전체 화면 모드 활성화하기 (Activating fullscreen mode)

여러분이 전체 화면 모드로 보여주고 싶은 요소(예를 들면 <video> 태그 같은 것들)가 있다면, 그 요소의 requestFullscreen() 메서드를 냅다 호출하기만 하면 됩니다.

자, 다음과 같은 <video> 요소가 하나 있다고 생각해 봅시다.

<video controls id="my-video">
  <source src="somevideo.webm" />
  <source src="somevideo.mp4" />
</video>

이 비디오를 전체 화면 모드로 띄우는 자바스크립트 코드는 다음과 같습니다.

const elem = document.getElementById("my-video");
// 브라우저가 이 기능을 지원하는지 먼저 안전하게 확인합니다.
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}

이 코드는 아주 똑똑하게도 무작정 requestFullscreen() 메서드를 호출하는 대신, 먼저 그 메서드가 실제로 존재하는지(지원되는 브라우저인지)를 확인한 후에 실행합니다. 방어적 프로그래밍의 좋은 예시죠!

요소가 성공적으로 전체 화면 모드에 진입하게 되면, CSS에서는 :fullscreen 가상 클래스(pseudo-class) 선택자가 이 요소를 찰떡같이 찾아냅니다. 브라우저는 이 가상 클래스를 통해 요소가 화면 전체를 꽉 채우도록 몇 가지 기본 스타일을 자동으로 먹여줍니다. 또한 이 요소는 브라우저 렌더링 최상단인 최상위 레이어(top layer)에 배치됩니다.

💡 강사의 팁: 만약 여러 요소가 연달아 전체 화면 모드를 요청한다면 어떻게 될까요? 예를 들어 유튜브 전체 화면 상태에서 다른 창을 또 띄우는 식이죠. 이때는 요청된 모든 요소가 :fullscreen 상태가 되어 최상위 레이어에 차곡차곡 쌓이게 됩니다. 당연히 가장 최근에 요청한 녀석이 맨 꼭대기에 나타나게 되며, 이때 Document.fullscreenElement를 찍어보면 가장 위에 있는 이 최신 요소를 반환해 줍니다.

알림 받기 (Notification)

전체 화면 모드가 성공적으로 켜지면, 해당 요소를 품고 있는 문서(document)는 fullscreenchange 이벤트를 받게 됩니다. 반대로 전체 화면 모드가 꺼졌을 때도 문서는 똑같이 fullscreenchange 이벤트를 다시 받습니다.

여기서 아주 중요한 포인트가 있습니다! fullscreenchange 이벤트 객체 자체는 "지금 화면이 켜진 거야, 아니면 꺼진 거야?"라는 직접적인 정보를 알려주지 않습니다.
대신, 여러분은 이벤트가 발생했을 때 Document.fullscreenElement 속성값을 확인해야 합니다. 만약 이 값이 null이 아니라면 "아하, 방금 전체 화면 모드로 들어갔구나!"라고 알 수 있고, 반대로 null이라면 "아하, 방금 전체 화면 모드에서 빠져나왔구나!"라고 판단할 수 있습니다.

전체 화면 요청이 실패했을 때 (When a fullscreen request fails)

우리가 원한다고 해서 브라우저가 항상 100% 전체 화면 모드를 허락해 주는 것은 아닙니다.

예를 들어, 보안과 악용 방지를 위해 <iframe> 요소는 그 안에 있는 콘텐츠가 전체 화면으로 표시되는 것을 허용할지 말지 결정하는 allowfullscreen이라는 아주 깐깐한 속성을 가지고 있습니다. 이 속성이 없으면 iframe 안에서는 절대 전체 화면을 띄울 수 없습니다. 또한 창 모드로 실행되어야만 하는 일부 플러그인(plug-ins) 같은 특정 콘텐츠들도 전체 화면 모드로 표시될 수 없습니다.

이렇게 전체 화면 모드로 표시될 수 없는 요소(또는 그 요소의 부모나 자식)를 강제로 띄우려고 시도하면 어떻게 될까요? 화면은 켜지지 않고, 대신 전체 화면을 요청했던 그 요소에게 fullscreenerror라는 에러 이벤트가 날아옵니다.

전체 화면 요청이 실패했을 때, Firefox(파이어폭스) 브라우저의 경우 왜 요청이 실패했는지 그 이유를 친절하게 웹 콘솔(Web Console)에 에러 메시지로 남겨줍니다. 하지만 아쉽게도 Chrome(크롬)이나 최신 버전의 Opera(오페라) 같은 다른 브라우저들은 묵묵부답으로 아무런 경고도 띄우지 않습니다.

---

전체 화면 모드 빠져나오기 (Getting out of full screen mode)

사용자는 우리(개발자)가 허락하지 않더라도 언제든지 자유의지로 전체 화면 모드를 종료할 수 있는 막강한 권한을 가지고 있습니다. (자세한 내용은 사용자에게 알려주어야 할 사항들을 참고하세요.)

하지만 우리도 스크립트를 통해 프로그래밍 방식으로 전체 화면을 우아하게 종료시킬 수 있습니다. 바로 Document.exitFullscreen() 메서드를 호출하는 것이죠.

💡 강사의 팁: 만약 여러 개의 요소가 차곡차곡 전체 화면 모드로 쌓여 있는 상태라면, exitFullscreen()을 한 번 호출했을 때 모든 화면이 다 꺼지는 게 아닙니다. 스택의 맨 위에 있는 최상단 요소 딱 하나만 빠져나오게 되고, 그 아래에 깔려있던 다음 요소가 다시 전체 화면으로 모습을 드러내게 됩니다. 반면, 사용자가 키보드의 Esc나 F11 키를 누르면 깔려있던 녀석들까지 모조리 한 방에 종료됩니다.

---

기타 유용한 정보들 (Other information)

Document 객체는 전체 화면 웹 애플리케이션을 개발할 때 아주 유용하게 써먹을 수 있는 몇 가지 추가적인 정보(속성)들을 제공합니다.

Document.fullscreenElement / ShadowRoot.fullscreenElement

이 fullscreenElement 속성은 현재 화면에 떡하니 전체 화면으로 떠 있는 Element 객체 자체를 콕 집어서 반환해 줍니다. 만약 이 값이 null이 아니라면 현재 문서(또는 shadow DOM)가 전체 화면 모드라는 뜻이고, null이라면 일반 창 모드라는 것을 확실하게 알 수 있죠.

Document.fullscreenEnabled

이 fullscreenEnabled 속성은 현재 문서가 전체 화면 모드를 요청해도 되는 상태인지 아닌지를 친절하게 알려줍니다. iframe 권한 문제나 브라우저 지원 문제 등으로 전체 화면을 켤 수 없는 상황이라면 false를 뱉어냅니다.

모바일 브라우저에서의 뷰포트 확대/축소 (Viewport scaling in mobile browsers)

일부 모바일 브라우저들은 전체 화면 모드에 진입했을 때, HTML에 적혀있는 뷰포트 메타 태그(viewport meta-tag)의 설정을 무시하고 사용자의 화면 확대/축소(scaling) 기능을 아예 강제로 막아버리는 경우가 있습니다.

예를 들어, 일반적인 창 모드에서는 손가락 두 개로 꼬집어 확대하는 "핀치 투 줌(pinch to zoom)" 제스처가 잘 먹히던 페이지라도, 전체 화면 모드로 띄운 상태에서는 아무리 꼬집어도 화면이 꿈쩍도 하지 않을 수 있다는 점을 모바일 웹 기획 시 유의하셔야 합니다.

---

사용자에게 알려주어야 할 사항들 (Things your users want to know)

개발자로서 우리는 친절해야 합니다. 사용자들에게 언제든지 Esc 키(또는 F11 키)를 누르면 전체 화면 모드를 빠져나올 수 있다는 사실을 UI 어딘가에 꼭 안내해 주는 것이 좋습니다.

또한, 전체 화면 모드 중이더라도 사용자가 다른 페이지로 이동(네비게이션)하거나, 다른 탭을 클릭하거나, 혹은 (예를 들어 Alt-Tab을 눌러서) 브라우저를 떠나 아예 다른 애플리케이션으로 전환해 버리면 브라우저가 스스로 전체 화면 모드를 얌전히 종료한다는 사실도 알아두시면 좋습니다.

---

예제 (Example)

저희가 준비한 mdn/dom-examples GitHub 저장소에 가시면 Fullscreen API를 완벽하게 구현해 놓은 아주 훌륭한 예제 코드가 있습니다.

이 링크를 통해 라이브 예제를 직접 실행해 보시고, 소스 코드를 브라우징하면서 공부해보시기를 강력히 추천합니다!

---

같이 보기 (See also)

• 전체 화면 모드 사용하기 (MDN 메인 문서)
• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen (주의: 사용 중단됨!)
• Document.fullscreenElement
• CSS 선택자: :fullscreen, ::backdrop
• iframe 권한 속성: allowfullscreen