Using fullscreen mode
=====================

**Fullscreen API** 는 특정 요소`Element` (en-US)(와 해당 자손들을)를 full-screen mode로 표시하고, 더 이상 필요하지 않으면 full-screen mode를 종료하는 메서드를 추가합니다. 이렇게 하면 사용자의 전체 화면을 사용하여, 온라인 게임과 같은 원하는 내용을 표시할 수 있습니다. full-screen mode가 종료될 때까지 화면에서 브라우저의 모든 유저 인터페이스 요소와 기타 응용 프로그램을 제거할 수 있습니다.

API 사용 방법에 대한 자세한 내용은 Guide to the Fullscreen API (en-US) 문서를 참조하세요.

**참고:** **주의:** 이 API에 대한 지원은 여러 브라우저에서 이루어지며, 다양한 업체의 접두사(prefix)가 필요하거나, 최신 사양을 구현하지 않는 경우가 많습니다. 이 API 지원에 대한 자세한 내용은 아래에 있는 Browser compatibility 섹션을 참조하세요. Fullscreen API를 지원하지 않는 업체의 경우, Fscreen 과 같은 라이브러리를 사용할 수 있습니다.

Interfaces
----------

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

Methods
-------

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

### Methods on the Document interface

`Document.exitFullscreen()` (en-US)

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

### Methods on the Element interface

`Element.requestFullscreen()` (en-US)

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

Properties
----------

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

`DocumentOrShadowRoot.fullscreenElement` (en-US)

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

`Document.fullscreenEnabled` (en-US)

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

### Event handlers

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

**참고:** **주의:** 이러한 이벤트 핸들러 속성(property)은 HTML 컨텐트 속성(attribute)으로 사용할 수 없습니다. 즉, HTML 컨텐트에서 `fullscreenchange (en-US)` 및 `fullscreenerror (en-US)` 이벤트를 지정할 수 없습니다. JavaScript 코드로 추가해야만 합니다.

#### Event handlers on documents

`Document.onfullscreenchange` (en-US)

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

`Document.onfullscreenerror` (en-US)

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

#### Event handlers on elements

`Element.onfullscreenchange` (en-US)

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

`Element.onfullscreenerror` (en-US)

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

### Obsolete properties

`Document.fullscreen` (en-US) 
지원이 중단되었습니다

문서에 현재 full-screen mode로 표시되는 요소가 있는 경우 `true`, 그렇지 않으면 `false`의 Boolean 값입니다.> **참고:** **주의:** 대신에 `Document` 나 `ShadowRoot` (en-US) 에서 `fullscreenElement` (en-US) 속성(property)을 사용하세요. 그것이 `null`이 아닌 경우 `Element` (en-US)가 full-screen mode로 표시됩니다.

Events
------

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

`fullscreenchange (en-US)`

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

`fullscreenerror (en-US)`

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

Dictionaries
------------

`FullscreenOptions` (en-US)

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

Controlling access
------------------

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

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

Usage notes
-----------

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

**참고:** **주의:** 다른 페이지로 이동하거나, 탭을 변경하거나, 응용 프로그램 전환기(또는 `Alt`-`Tab`)를 사용하여, 다른 응용 프로그램으로 전환하면 마찬가지로 full-screen mode가 종료됩니다.

Example
-------

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

View Live Examples

### Watching for the Enter key

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


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

### Toggling full-screen mode

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


```js
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()` (en-US)을 호출하여 수행합니다.

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

명세서
---

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenelement① |
| Fullscreen API Standard # ref-for-dom-document-fullscreenenabled① |
| Fullscreen API Standard # ref-for-dom-document-exitfullscreen① |
| Fullscreen API Standard # ref-for-dom-element-requestfullscreen① |
| Fullscreen API Standard # dom-document-fullscreen |

브라우저 호환성
--------

### api.Document.fullscreenElement

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Document.fullscreenEnabled

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Document.exitFullscreen

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Element.requestFullscreen

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Document.fullscreen

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using full-screen mode
* `Element.requestFullscreen()` (en-US)
* `Document.exitFullscreen()` (en-US)
* `Document.fullscreen` (en-US)
* `Document.fullscreenElement` (en-US)
* `:fullscreen`, `::backdrop` (en-US)
* `allowfullscreen` (en-US)