Using fullscreen mode

Fullscreen API 에는 자체 인터페이스가 없습니다. 대신에, full-screen 기능을 제공하는데 필요한 메서드, 속성(property), 이벤트 핸들러를 추가하기 위해, 다음 섹션에 나열된 것과 같은 몇 가지 다른 인터페이스를 추가합니다.

Fullscreen API 는 Document, Element 인터페이스에 메서드를 추가하여 full-screen mode를 설정하거나 해제할 수 있습니다.

Document.exitFullscreen()

user agent 가 full-screen mode에서 창 모드로 다시 전환되도록 요청합니다. full-screen mode가 완전히 종료되면 Promise resolved 를 반환합니다.

Element.requestFullscreen()

유저 에이전트가 지정한 요소(그리고 그 자손들까지)를 full-screen mode로 설정하고, 브라우저의 모든 UI 요소와 다른 모든 애플리케이션을 화면에서 제거하도록 요구합니다. full-screen mode가 활성화되면 Promise resolved를 반환합니다.

Document 인터페이스는 full-screen mode가 지원되고 사용 가능한지, full-screen mode가 현재 활성화 되어있는지, 어떤 요소가 스크린을 사용하고 있는지 확인하는데 사용할 수 있는 속성(property)을 제공합니다.

DocumentOrShadowRoot.fullscreenElement

fullscreenElement 속성은 DOM(혹은 shadow DOM)에서 현재 full-screen mode로 표시되는 요소Element를 알려줍니다. 이것이 null인 경우, document는 full-screen mode가 아닙니다.

Document.fullscreenEnabled

fullscreenEnabled 속성(property)은 full-screen mode를 사용할 수 있는지 여부를 알려줍니다. 이유가 어떻든(예를들어, "fullscreen" 기능이 허락되지 않거나, full-screen mode가 지원되지 않는 경우) full-screen mode를 사용할 수 없으면 false 입니다.

Fullscreen API는 full-screen mode를 켜고 끌 때 혹은, full-screen mode와 window mode간에 변경하는 과정에서 오류가 발생하는 것을 감지하는데 사용할 수 있는 두 가지 이벤트를 정의합니다. 이러한 이벤트에 대한 이벤트 핸들러는 Document 와Element 인터페이스 에서 사용할 수 있습니다.

Event handlers on documents

Document.onfullscreenchange

문서(document)가 full-screen mode로 전환되거나 full-screen mode를 종료할 때 Document로 보내지는 fullscreenchange 이벤트에 대한 이벤트 핸들러 입니다. 이 핸들러는 오직 전체 문서가 full-screen mode로 표시될 때만 호출됩니다.

Document.onfullscreenerror

전체 문서에 대해 full-screen mode를 사용하거나, 사용하지 않도록 설정하는 동안 오류가 발생하면, Document로 보내지는 fullscreenerror 이벤트의 이벤트 핸들러입니다.

Event handlers on elements

Element.onfullscreenchange

fullscreenchange 이벤트가 요소(element)로 전송되면, 요소가 full-screen mode로 배치되거나 제거되었음을 나타내는 이벤트 핸들러입니다.

Element.onfullscreenerror

full-screen mode 를 사용하거나, 사용하지 않도록 설정하는 동안 오류가 발생하면 요소로 보내지는 fullscreenerror 이벤트의 이벤트 핸들러입니다.

Document.fullscreen 지원이 중단되었습니다

문서에 현재 full-screen mode로 표시되는 요소가 있는 경우 true, 그렇지 않으면 false의 Boolean 값입니다.

참고: 대신에 Document 나 ShadowRoot 에서 fullscreenElement 속성(property)을 사용하세요. 그것이 null이 아닌 경우 Element가 full-screen mode로 표시됩니다.

Fullscreen API는 full-screen mode를 켜고 끌 때 혹은, full-screen mode와 window mode간에 변경하는 과정에서 오류가 발생하는 것을 감지하는데 사용할 수 있는 두 가지 이벤트를 정의합니다.

fullscreenchange

full-screen mode를 사용하거나, 사용하지 않도록 전환할 때 Document 혹은Element 로 보냅니다.

fullscreenerror

full-screen mode를 사용하거나, 사용하지 않도록 전환하려고 시도하는 중에 오류가 발생하면 Document 또는 Element 로 보냅니다.

FullscreenOptions

requestFullscreen()을 호출할 때 지정할 수 있는 옵션 설정을 제공합니다.

Feature Policy을 사용하여 full-screen mode의 유효성을 제어할 수 있습니다. full-screen mode는 "fullscreen"으로 식별되고, 기본 허용 목록 값은 "self" 입니다. 이는 최상위(top-level) 문서 컨텍스트에서 full-screen mode가 허용된다는 것을 의미하며, 최상위(top-most) 문서와 같은 출처에서 로드 된 중첩 된 컨텍스트에도 적용됩니다.

기능 정책을 사용하여 API에 대한 액세스를 제어하는 자세한 내용은 Using Feature Policy을 참조하세요.

사용자는 ESC (혹은 F11) 키를 누르기만하면 사이트 또는 앱이 프로그래밍 방식으로 기다리는 대신에, full-screen mode를 종료하도록 선택할 수 있습니다. 유저 인터페이스의 어딘가에 사용자에게 이 옵션을 사용할 수 있음을 알리는, 적절한 유저 인터페이스 요소를 제공해야 합니다.

이 예제에서는 비디오가 웹 페이지에 표시됩니다. Return 또는 Enter 키를 누르면, 사용자가 비디오의 창과 full-screen 표시를 전환할 수 있습니다.

View Live Examples

페이지가 로드되면, 이 코드가 실행되어 Enter 키 를 주시하는 이벤트 리스너를 설정합니다.

document.addEventListener(
  "keypress",
  function (e) {
    if (e.keyCode === 13) {
      toggleFullScreen();
    }
  },
  false,
);

이 코드는 사용자가 Enter 키를 누를 때, 위의 이벤트 핸들러에 의해 호출됩니다.

function toggleFullScreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    }
  }
}

먼저 document의 fullscreenElement 속성(attribute)값을 살펴보겠습니다. 실제 배포 시에는 이 시점에 접두어가 붙은 버전(예를들어, mozFullscreenElement, msFullscreenElement, webkitFullscreenElement)을 확인해야 합니다. 값이 null인 경우, 문서는 현재 window mode에 있으므로, full-screen mode로 전환해야 합니다. 그렇지 않으면, 이 요소는 지금 full-screen mode 상태입니다. full-screen mode로 전환하는 작업은, <video>요소에서 Element.requestFullscreen()을 호출하여 수행합니다.

full-screen mode가 이미 활성화 된 경우(fullscreenElement 가 null이 아닌 경우), document에서 exitFullscreen()을 호출하여 full-screen mode를 종료합니다.

• Using full-screen mode
• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen