Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
Screen Orientation 명세서는 장치의 화면 방향에 대한 유형과 각도를 표준화하고, 이를 잠그고 잠금 해제할 수 있는 수단을 제공합니다. 이 명세에 정의된 API는 장치의 화면 방향에 대한 현재 유형과 각도를 노출하고, 변경될 때 이벤트를 전송합니다. 이를 통해 웹 애플리케이션은 CSS와 함께 작동하여 여러 화면 방향에 맞게 사용자 경험을 프로그래밍적으로 적응시킬 수 있습니다. 또한 이 API는 특정 전제 조건에서 화면 방향을 잠글 수 있도록 합니다. 이는 사용자가 장치를 물리적으로 회전시키지만 화면 방향 자체는 변경되지 않아야 하는 컴퓨터 게임과 같은 애플리케이션에서 특히 유용합니다.
이 섹션은 문서가 발행된 시점의 상태를 설명합니다. 현재 W3C 간행물 목록과 이 기술 보고서의 최신 개정판은 W3C 기술 보고서 색인에서 확인할 수 있습니다: https://www.w3.org/TR/.
이 문서는 진행 중인 작업입니다.
이 문서는 웹 애플리케이션 작업 그룹에 의해 작업 초안(Working Draft)으로 발행되었으며, 권고안 트랙(Recommendation track)을 사용했습니다.
작업 초안으로서의 공개는 W3C 및 그 회원들의 승인(endorsement)을 의미하지 않습니다.
이 문서는 초안 문서로 언제든지 업데이트, 대체 또는 폐기될 수 있습니다. 다른 문서가 될 때까지 이 문서를 진행 중인 작업(work in progress) 이상의 것으로 인용하는 것은 적절하지 않습니다.
이 문서는 다음의 규정 하에 운영되는 그룹에 의해 작성되었습니다. W3C 특허 정책. W3C는 그룹의 산출물과 관련하여 제기된 특허 공개의 공개 목록을 유지합니다. 해당 페이지에는 특허 공개 절차에 대한 안내도 포함되어 있습니다. 개인이 자신이 실제로 알고 있고 핵심 청구항(Essential Claim(s))을 포함한다고 생각하는 특허를 알고 있다면, 해당 정보는 W3C 특허 정책의 6항에 따라 공개해야 합니다.
이 문서는 2023년 6월 12일 W3C 프로세스 문서의 규정에 따라 관리됩니다.
이 섹션은 비규범적입니다.
이 예제에서 "Lock" 버튼을 클릭하면 전체 화면으로 전환을 요청한 뒤 화면을 반대 방향으로 고정합니다. "Unlock" 버튼을 클릭하면 화면 고정이 해제됩니다.
<script>
function updateLockButton() {
const lockButton = document.getElementById("button");
const newOrientation = getOppositeOrientation();
lockButton.textContent = `Lock to ${newOrientation}`;
}
function getOppositeOrientation() {
return screen
.orientation
.type
.startsWith("portrait") ? "landscape" : "portrait";
}
async function rotate(lockButton) {
if (!document.fullscreenElement) {
await document.documentElement.requestFullscreen();
}
const newOrientation = getOppositeOrientation();
await screen.orientation.lock(newOrientation);
updateLockButton(lockButton);
}
screen.orientation.addEventListener("change", updateLockButton);
window.addEventListener("load", updateLockButton);
</script>
<button onclick="rotate(this)" id="button">
Lock to...
</button>
<button onclick="screen.orientation.unlock()">
Unlock
</button>
화면 방향을
잠그기를 OrientationLockType
orientation으로 설정한다는 것은 사용자가 화면을 특정
화면 방향으로만 회전할 수 있으며, 다른 방향들은 제외될 수 있음을 의미합니다. 화면을 어떤 방향으로 회전할
수 있는지는 사용자 에이전트, 사용자 설정, 운영체제의 관습 또는 화면 자체에 의해 결정됩니다. 예를 들어, 방향을 가로로 잠그면 사용자는 시스템이 허용하는 경우 landscape-primary 및 경우에 따라 landscape-secondary 로만 회전할 수
있고, portrait-secondary 로는 변경되지 않습니다.
화면 방향 잠금 해제는 최종 사용자가 시스템에서 허용하는 모든 화면 방향으로 제한 없이 회전할 수 있음을 의미합니다.
화면은 다음 중 하나의 화면 방향에 있거나, 해당 방향으로 잠길 수 있습니다:
null
인 경우). 이 방향은 운영체제,
사용자 에이전트, 최종 사용자 설정 또는 설치된 웹 애플리케이션에 의해 결정될 수 있습니다. 예를 들어, 화면
방향이 잠금 해제된 상태에서 사용자가 기기를 회전하면 일부 장치는 portrait-primary, landscape-primary, 및 landscape-secondary로만
방향을 제한하고 portrait-secondary로는 변경하지 않을 수 있습니다.
출력 장치의 화면에는 다음과 같은 관련 개념이 있습니다:
OrientationLockType
으로 나타낸 것이며, 잠금이 해제된
경우에는 null
입니다.
OrientationType
으로 나타낸 것입니다.
아래의 화면 방향 값 목록은 서로 다른 자연스러운 방향을 가진 화면들에 대해 각 화면 방향 유형에 연관된 각도를 표준화합니다:
Document
인터페이스는 다음의 내부
슬롯들로 확장됩니다:
내부 슬롯 | 설명 |
---|---|
[[orientationPendingPromise]] |
값은 null 이거나 Promise 입니다. Promise 가 할당되면,
해당 프라미스는 화면 방향 잠금을 요청하는 것을 나타냅니다.
|
WebIDLpartial interface Screen {
[SameObject] readonly attribute ScreenOrientation
orientation
;
};
Window
객체는 연관된
ScreenOrientation
을 가지며,
이는 Screen
의 orientation
객체입니다(즉, ScreenOrientation
인스턴스는
window.screen.orientation
에 있습니다).
WebIDL[Exposed=Window]
interface ScreenOrientation
: EventTarget {
Promise<undefined> lock
(OrientationLockType
orientation);
undefined unlock
();
readonly attribute OrientationType
type
;
readonly attribute unsigned short angle
;
attribute EventHandler onchange
;
};
내부 슬롯 | 설명 |
---|---|
[[angle]] |
화면의 마지막으로 알려진 현재 방향 각도를 도 단위로
나타내며,
이는 unsigned short 로 표현되고,
화면 방향 값 목록에서
파생됩니다.
|
[[initialType]] | 브라우징 컨텍스트가 생성되었을 때의 화면의 현재 방향 타입을 나타냅니다. |
[[type]] |
화면의 마지막으로 알려진 현재 방향 타입을 OrientationType
열거형 값으로
나타냅니다.
|
lock
()
메서드가 OrientationLockType
orientation과 함께 호출되면, 사용자 에이전트는 다음 단계를 반드시 실행해야 합니다.
사용자 에이전트는 화면 방향을 잠그기 위해 문서와 그에 연관된 브라우징 컨텍스트가 하나 이상의 사전 잠금 조건을 만족하도록 요구할 수 있습니다. 자세한 내용은 10. Interaction with Web Application Manifest 및 9. Interaction with Fullscreen API를 참조하세요.
Document
입니다.
NotSupportedError
" DOMException
로 거부된 프라미스를 반환하고 이
절차를 중단합니다.
[[orientationPendingPromise]]
가
null
이 아니면, 현재의 잠금 프라미스를 거부하고 null로 만듭니다
(거부 이유는 "AbortError
").
[[orientationPendingPromise]]
를
새
프라미스로 설정합니다.
[[orientationPendingPromise]]
를
반환합니다.
unlock
()
메서드가
호출되면, 사용자 에이전트는
다음 단계를 반드시 실행해야 합니다:
Document
입니다.
null
이면, undefined
를 반환합니다.
[[orientationPendingPromise]]
가
null
이 아니면, 현재의 잠금 프라미스를 거부하고 null로 만듭니다
(거부 이유는 "AbortError
").
null
을 document에 적용합니다.
common
safety checks는 Document
인 document에 대해 다음 단계들로 구성됩니다:
InvalidStateError
" DOMException
를 던집니다.
SecurityError
" DOMException
를 던집니다.
SecurityError
" DOMException
를 던집니다.
읽을 때, angle
속성은 이 객체의
this의 [[angle]]
를 반환합니다.
onchange
속성은 이벤트 핸들러 IDL 속성로, onchange
이벤트 핸들러에 대응합니다. 이 이벤트 핸들러의 이벤트
타입은 change입니다.
WebIDLenum OrientationLockType
{
"any
",
"natural
",
"landscape
",
"portrait
",
"portrait-primary
",
"portrait-secondary
",
"landscape-primary
",
"landscape-secondary
"
};
OrientationLockType
열거형은
화면이 잠길 수 있는 잠재적인 화면 방향들을 나타냅니다(lock될 수 있는 방향).
any
"는 any를 나타냅니다.
natural
"는 natural를 나타냅니다.
landscape
"는 landscape를 나타냅니다.
portrait
"는 portrait를 나타냅니다.
portrait-primary
"는 portrait-primary를 나타냅니다.
portrait-secondary
"는 portrait-secondary를 나타냅니다.
landscape-primary
"는 landscape-primary를 나타냅니다.
landscape-secondary
"는 landscape-secondary를 나타냅니다.
WebIDLenum OrientationType
{
"portrait-primary
",
"portrait-secondary
",
"landscape-primary
",
"landscape-secondary
"
};
OrientationType
열거형 값들은 화면의
현재 방향 타입을 나타내는 데 사용됩니다.
portrait-primary
"는 portrait-primary를 나타냅니다.
portrait-secondary
"는 portrait-secondary를
나타냅니다.
landscape-primary
"는 landscape-primary를 나타냅니다.
landscape-secondary
"는 landscape-secondary를
나타냅니다.
브라우징 컨텍스트 context가 생성될 때, 사용자 에이전트는 반드시 다음을 수행해야 합니다:
ScreenOrientation
로 둡니다.
[[initialType]]
내부 슬롯을
화면의 현재 방향 타입으로 초기화합니다.
[[type]]
내부 슬롯을
화면의 현재 방향 타입으로 초기화합니다.
[[angle]]
내부 슬롯을
화면의 현재 방향 각도로 초기화합니다.
단계가 문서의 현재 잠금 프라미스를 거부하고 null로 만드는 것을
DOMString exceptionName으로 Document
document에 대해
요구할 때, 사용자 에이전트는
반드시 다음을 수행해야 합니다:
[[orientationPendingPromise]]
는
null
이 아닙니다.
[[orientationPendingPromise]]
.
DOMException
.
[[orientationPendingPromise]]
를
null
로 설정합니다.
단계가 apply
orientation lock을
OrientationLockType?
orientation을 Document
document에 대해
요구할 때, 사용자 에이전트는
반드시 다음 절차를
수행해야 합니다:
[[orientationPendingPromise]]
가
null
이 아니면, 문서의 현재 잠금 프라미스를
거부하고 null로 만듭니다 (거부 이유는 "AbortError
").
[[orientationPendingPromise]]
가
null
이면, 계속합니다.
AbortError
").
[[orientationPendingPromise]]
가
null
이 아니면, 문서의 현재 잠금 프라미스를
거부하고 null로 만듭니다 (거부 이유는 "AbortError
") 그리고 이 단계들을
중단합니다.
null
이면, 화면 방향 잠금을 해제(unlock)합니다.
null
로 설정합니다.
[[orientationPendingPromise]]
가 null
이 아니면,
현재 잠금
프라미스를 거부하고 null로 만듭니다
(거부 이유는 "NotSupportedError
").
이것은 사용자가 웹 애플리케이션이 화면 방향을 변경하지 못하도록 하는 선호를 설정했거나, 기본 플랫폼(사용자 에이전트가 아닌 플랫폼 자체)이 주어진 orientation으로 화면 방향을 잠그는 것을 허용하지 않는 경우에 발생할 수 있습니다.
[[orientationPendingPromise]]
.
[[orientationPendingPromise]]
를 null
로 설정합니다.
null
이 아니면, resolve하여 promise를
undefined
로 처리합니다.
사용자 에이전트가 최상위 브라우징 컨텍스트에 대해 화면의 방향이 변경되었음을 판단하거나, 사용자가 최상위 브라우징 컨텍스트를 다른 화면으로 이동시키면, 해당 최상위 브라우징 컨텍스트의 활성 문서에서 화면 방향 변경 단계를 실행합니다.
문서(Document)용 화면 방향 변경 단계는 다음과 같습니다:
ScreenOrientation
로 둡니다.
[[type]]
와 같고,
angle이 screenOrientation의 [[angle]]
와 같으면,
이 단계들을 중단합니다.
[[angle]]
을 angle로 설정합니다.
[[type]]
을
type로 설정합니다.
[HTML]'s 가시성 상태 업데이트는 화면 방향 변경 단계를 실행합니다.
언로드 문서 정리 단계(unloading document cleanup steps)가 document와 함께 실행될 때마다, 사용자 에이전트는 반드시 다음 단계들을 실행해야 합니다:
문서(Document)용 화면 방향 완전 잠금 해제 단계는 다음과 같습니다:
[[orientationPendingPromise]]
가
null
이 아니면, 현재 잠금 프라미스를 거부하고 null로 만듭니다
(거부 이유: "AbortError
").
null
을 적용하여
topDocument에 적용합니다.
사용자 에이전트는 권장한다 lock
()
의 사용을
단순 전체 화면 문서(simple fullscreen documents)로 제한하는 것을 사전 잠금
조건으로 삼아야 합니다. [fullscreen]
문서(document)가 전체 화면을 벗어나면, 또한 화면 방향 완전 잠금 해제 단계(fully unlock the screen orientation steps)를 실행해야 합니다. [fullscreen]
Web Application Manifest 명세는 웹 애플리케이션이 기본 화면 방향(default screen orientation)을 orientation 멤버를 통해 설정하도록 허용합니다.
사용자 에이전트는 권장한다 설치된 웹 애플리케이션이 "fullscreen" display mode로 표시되도록 요구할 수 있으며, 이를 사전 잠금 조건으로 삼아야 합니다.
사용자가 기기를 고정된 방향으로 장착할 수 있기 때문에(예: 휠체어 팔대에 장착), 개발자가 화면 방향을 잠글 때 사용자가 기기를 회전시키기를 기대하는 경우에는 Web Content Accessibility Guidelines (WCAG) 2.1의 Orientation Success Criterion을 인지해야 합니다. 이 기준은 콘텐츠와 기능이 화면 방향에 관계없이 이용 가능해야 한다는 것을 필수적으로 규정합니다. 특정 방향이 필수적인 경우, 웹 애플리케이션은 사용자가 필요한 방향 요구사항을 고지해야 합니다.
화면의 type과 angle은 잠재적인 지문(피어프린팅) 벡터가 될 수 있습니다. 다음의 완화책들은 사용자의 장치가 어떻게 들려져 있는지를 노출하지 않음으로써 사용자의 프라이버시를 보호하고, 또한 secondary 방향 타입과 연관된 각도들이 지문 채집에 사용되는 것을 방지합니다.
지문 채집에 저항하기 위해(예: 개인 탐색 모드에서), 사용자 에이전트는 할 수 있다:
[[initialType]]
인 것처럼 동작합니다.
type
getter가 반환할 수 있는 값을
"portrait-primary
" 또는
"landscape-primary
"로 제한합니다. 어떤
값이 반환되는지는 화면 종횡비가 결정합니다.
[[initialType]]
와 일치하면, angle
getter에 대해 0
을 반환합니다.
그렇지 않으면 90
을 반환합니다.
비규범으로 표시된 섹션들뿐만 아니라, 이 명세서의 모든 작성 지침, 다이어그램, 예시, 및 주석은 비규범입니다. 이 명세서의 나머지 모든 내용은 규범적입니다.
문서에서 사용된 핵심 단어 할 수 있다, 반드시, 및 권장한다는 BCP 14에 설명된 대로 해석되어야 합니다. 관련 문서는 BCP 14 [RFC2119] [RFC8174] 에서와 같이, 오직 모두 대문자로 나타날 때에만 해당 의미로 해석됩니다.
WebIDLpartial interface Screen {
[SameObject] readonly attribute ScreenOrientation
orientation
;
};
[Exposed=Window]
interface ScreenOrientation
: EventTarget {
Promise<undefined> lock
(OrientationLockType
orientation);
undefined unlock
();
readonly attribute OrientationType
type
;
readonly attribute unsigned short angle
;
attribute EventHandler onchange
;
};
enum OrientationLockType
{
"any
",
"natural
",
"landscape
",
"portrait
",
"portrait-primary
",
"portrait-secondary
",
"landscape-primary
",
"landscape-secondary
"
};
enum OrientationType
{
"portrait-primary
",
"portrait-secondary
",
"landscape-primary
",
"landscape-secondary
"
};
angle
속성
(ScreenOrientation
용)
§5.
[[angle]]
내부 슬롯
(ScreenOrientation
용)
§5.1
"any"
(OrientationLockType
의 열거값)
§6.
[[initialType]]
내부 슬롯
(ScreenOrientation
용)
§5.1
"landscape"
(OrientationLockType
의 열거값)
§6.
lock
메서드
(ScreenOrientation
용)
§5.
"natural"
(OrientationLockType
의 열거값)
§6.
onchange
속성
(ScreenOrientation
용)
§5.
orientation
속성
(Screen
용)
§4.
OrientationLockType
열거형
§6.
[[orientationPendingPromise]]
내부 슬롯
(Document
용)
§3.1
OrientationType
열거형
§7.
"portrait"
(OrientationLockType
의 열거값)
§6.
ScreenOrientation
인터페이스
§5.
type
속성
(ScreenOrientation
용)
§5.
[[type]]
내부 슬롯
(ScreenOrientation
용)
§5.1
unlock
메서드
(ScreenOrientation
용)
§5.
Screen
인터페이스
Document
인터페이스
EventTarget
인터페이스
EventHandler
Window
인터페이스
AbortError
예외
DOMException
인터페이스
DOMString
타입
[Exposed]
확장 속성
InvalidStateError
예외
NotSupportedError
예외
Promise
인터페이스
[SameObject]
확장 속성
SecurityError
예외
undefined
타입
unsigned short
타입
유용한 의견을 주신 Christophe Dumez, Anne van Kesteren, Chundong Wang, Fuqiao Xue, 및 Chaals McCathie Nevile에게 감사드립니다.
이 API 초기 설계에 기여한 Chris Jones와 Jonas Sicking에게 특별히 감사드립니다.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: