\n\n \n \n ","\n Concepts\n ","\n To lock the\n screen orientation to an {{OrientationLockType}} |orientation|\n means that the screen can only be rotated by the user to a specific\n [=screen orientation=] - possibly at the exclusion of other\n orientations. The possible orientations to which the screen can be\n rotated is determined by the user agent, a user preference, the\n operating system's conventions, or the screen itself. For example,\n locking the orientation to [=landscape=] means that the screen can be\n rotated by the user to [=landscape-primary=] and maybe\n [=landscape-secondary=] if the system allows it, but won't change the\n orientation to [=portrait-secondary=] orientation.\n ","\n To unlock the screen\n orientation the end user is unrestricted to rotate the screen to\n any [=screen orientation=] that the system allows.\n ","\n Screen orientation types\n ","\n A screen can be in, or [=locked=] to, one of the following\n screen orientations:\n ","Natural","\n The most natural orientation for the device's display as determined\n by the user agent, the user, the operating system, or the screen\n itself. For example, a device viewed, or held upright in the user's\n hand, with the screen facing the user. A computer monitor are\n commonly naturally [=landscape-primary=], while a mobile phones are\n commonly naturally [=portrait-primary=].\n ","Landscape","\n The screen's aspect ratio has a width greater than the height.\n ","Portrait","\n The screen's aspect ratio has a height greater than the width.\n ","Primäre","\n The device's screen [=natural=] orientation for either [=portrait=]\n or [=landscape=].\n ","Secondary","\n The opposite of the device's screen primary orientation for\n [=portrait=] or [=landscape=].\n ","Any","\n The screen can be rotated by the user to any orientation allowed by\n the device's operating system or by the end-user.\n ","\n Default (unlocked)\n ","\n The device's default behavior for when the screen is [=unlocked=]\n (i.e., the [=Screen/active orientation lock=] is `null`). This\n orientation is determined by the device's operating system, or the\n user agent, or controlled by the end-user, or possibly set by an\n [=installed web application=]. For example, when the screen\n orientation is unlocked and the user rotates the device, some\n devices will limit orientation changes to [=portrait-primary=],\n [=landscape-primary=], and [=landscape-secondary=], but not to\n [=portrait-secondary=].\n ","\n The current screen orientation type and angle\n ","\n The screen of the output device has the following associated\n concepts:\n ","Current orientation type","\n The [=screen orientation=] of the screen, represented as a\n {{OrientationType}}.\n ","Current orientation angle","\n The angle in degrees that the screen is rotated counter-clockwise\n from its [=natural=] orientation as derived by the [=screen\n orientation values list=].\n ","Active orientation lock","\n The [=screen orientation=], represented as a\n {{OrientationLockType}}, to which the screen is [=locked=], or\n `null` when [=unlocked=].\n ","\n The screen orientation values lists below standardize the\n angles associated with each screen orientation type for screens with\n different [=natural=] orientations:\n ","\n For screens with a [=natural=] [=portrait=] orientation:\n ","[=portrait-primary=]: 0°\n ","[=landscape-primary=]: 90°\n ","[=portrait-secondary=]: 180°\n ","[=landscape-secondary=]: 270°\n ","\n For screens with a [=natural=] [=landscape=] orientation:\n ","[=landscape-primary=]: 0°\n ","[=portrait-primary=]: 90°\n ","[=landscape-secondary=]: 180°\n ","[=portrait-secondary=]: 270°\n ","\n Extensions to the `Document` interface\n ","\n Internal Slots\n ","\n The {{Document}} interface is extended with the following internal\n slots:\n ","\n Internal Slot\n ","\n Description\n ","[[\\orientationPendingPromise]]","\n Either `null` or a {{Promise}}. When assigned a {{Promise}},\n that promise represents a request to lock the screen\n orientation.\n ","\n Extensions to the `Screen` interface\n ","\n partial interface Screen {\n [SameObject] readonly attribute ScreenOrientation orientation;\n };\n ","\n The {{Window}} object has an associated `ScreenOrientation`,\n which is a {{Screen}}'s {{Screen/orientation}} object (i.e., the\n {{ScreenOrientation}} instance at `window.screen.orientation`).\n ","\n ScreenOrientation interface\n ","\n [Exposed=Window]\n interface ScreenOrientation : EventTarget {\n Promise lock(OrientationLockType orientation);\n undefined unlock();\n readonly attribute OrientationType type;\n readonly attribute unsigned short angle;\n attribute EventHandler onchange;\n };\n ","[[\\angle]]","\n Represents the screen's last known [=Screen/current orientation\n angle=] in degrees as an {{unsigned short}} as derived from the\n [=screen orientation values lists=].\n ","[[\\initialType]]","\n Represents the screen's [=Screen/current orientation type=]\n when the [=browsing context=] was created.\n ","[[\\type]]","\n Represents the screen's last known [=Screen/current orientation\n type=] as an {{OrientationType}} enum value.\n ","\n `lock()` method\n ","\n When the {{lock()}} method is invoked with {{OrientationLockType}}\n |orientation:OrientationLockType|, the [=user agent=] MUST run the\n following steps.\n ","\n The [=user agent=] MAY require a [=document=] and its associated\n [=Document/browsing context=] to meet one or more pre-lock\n conditions in order to [=lock the screen orientation=]. See\n [[[#appmanifest-interaction]]] and [[[#fullscreen-interaction]]].\n ","Let |document:Document| be [=this=]'s [=relevant global\n object=]'s [=associated `Document`=].\n ","Run the [=common safety checks=] with |document|. If an\n [=exception=] is [=exception/throw|thrown=], return [=a promise\n rejected with=] that exception and abort these steps.\n ","If the [=user agent=] does not support locking the screen\n orientation to |orientation|, return [=a promise rejected with=] a\n {{\"NotSupportedError\"}} {{DOMException}} and abort these steps.\n ","If |document|'s\n {{Document/[[orientationPendingPromise]]}} is not `null`, [=reject\n and nullify the current lock promise=] of |document| with an\n {{\"AbortError\"}}.\n ","Set |document|'s\n {{Document/[[orientationPendingPromise]]}} to [=a new promise=].\n ","[=Apply orientation lock=] |orientation| to |document|.\n ","Return |document|'s {{Document/[[orientationPendingPromise]]}}.\n ","\n `unlock()` method\n ","\n When the {{unlock()}} method is invoked, the [=user agent=] MUST run\n the following steps:\n ","Run the [=common safety checks=] with |document|. If an\n [=exception=] is [=exception/throw|thrown=], re-throw that exception\n and abort these steps.\n ","If screen's [=Screen/active orientation lock=] is `null`, return\n `undefined`.\n ","If |document|'s {{Document/[[orientationPendingPromise]]}} is not\n `null`, [=reject and nullify the current lock promise=] of |document|\n with an {{\"AbortError\"}}.\n ","[=Apply orientation lock=] `null` to |document|.\n ","\n {{unlock()}} does not return a promise because it is equivalent to\n locking to the [=default screen orientation=] which might or might\n not be known by the [=user agent=]. Hence, the [=user agent=] can not\n predict what the new orientation is going to be and even if it is\n going to change at all.\n ","\n Common Safety Checks\n ","\n The common safety checks for a {{Document}}\n |document:Document| are the following steps:\n ","If |document| is not\n [=Document/fully active=], [=exception/throw=] an\n {{\"InvalidStateError\"}} {{DOMException}}.\n ","If |document| has the\n [=sandboxed orientation lock browsing context flag=] set,\n [=exception/throw=] {{\"SecurityError\"}} {{DOMException}}.\n ","If |document|'s\n [=Document/visibility state=] is \"hidden\", [=exception/throw=]\n {{\"SecurityError\"}} {{DOMException}}.\n ","\n `type` attribute\n ","\n When getting, the {{type}} attribute returns [=this=]'s\n {{ScreenOrientation/[[type]]}}.\n ","\n `angle` attribute\n ","\n When getting, the {{angle}} attribute returns [=this=]'s\n {{ScreenOrientation/[[angle]]}}.\n ","\n The {{ScreenOrientation/angle}} attribute represents how far the\n screen has rotated from it [=natural=] orientation. The screen\n orientation values list specifies how the angle changes\n depending on the how screen is rotated.\n ","\n `onchange` event handler attribute\n ","\n The {{onchange}} attribute is an [=event handler IDL attribute=] for\n the {{onchange}} [=event handler=], whose [=event handler event type=]\n is change.\n ","\n OrientationLockType enum\n ","\n enum OrientationLockType {\n \"any\",\n \"natural\",\n \"landscape\",\n \"portrait\",\n \"portrait-primary\",\n \"portrait-secondary\",\n \"landscape-primary\",\n \"landscape-secondary\"\n };\n ","\n The {{OrientationLockType}} enum represents the screen orientations to\n which a screen can be potentially [=locked=].\n ","\n User agents might only support a subset of the possible\n {{OrientationLockType}} values. For example, a user agent might not\n support locking to the `\"portrait-secondary\"` or\n `\"landscape-secondary\"` orientations.\n ","\"any\" represents [=any=].\n ","\"natural\" represents [=natural=].\n ","\"landscape\" represents [=landscape=].\n ","\"portrait\" represents [=portrait=].\n ","\"portrait-primary\" represents [=portrait-primary=],\n ","\"portrait-secondary\" represents [=portrait-secondary=].\n ","\"landscape-primary\" represents [=landscape-primary=].\n ","\"landscape-secondary\" represents\n [=landscape-secondary=].\n ","\n OrientationType enum\n ","\n enum OrientationType {\n \"portrait-primary\",\n \"portrait-secondary\",\n \"landscape-primary\",\n \"landscape-secondary\"\n };\n ","\n The {{OrientationType}} enum values are used to represent the screen's\n [=Screen/current orientation type=].\n ","\"portrait-primary\" represents [=portrait-primary=].\n ","\n Algorithms\n ","\n Initializing the `ScreenOrientation` object\n ","\n When a [=browsing context=] |context| is created, the [=user agent=]\n MUST:\n ","Let |screenOrientation| be |context|'s [=associated\n `ScreenOrientation`=].\n ","Initialize |screenOrientation|'s\n {{ScreenOrientation/[[initialType]]}} internal slot to the screen's\n [=Screen/current orientation type=].\n ","Initialize |screenOrientation|'s {{ScreenOrientation/[[type]]}}\n internal slot to the screen's [=Screen/current orientation type=].\n ","Initialize |screenOrientation|'s {{ScreenOrientation/[[angle]]}}\n internal slot to the screen's [=Screen/current orientation angle=].\n ","\n Rejecting a document's current lock promise\n ","\n When steps require to reject and nullify the current lock\n promise of {{Document}} |document| with a {{DOMString}}\n |exceptionName|, the [=user agent=] MUST:\n ","[=/Assert=]: {{Document/[[orientationPendingPromise]]}} is not\n `null`.\n ","Let |promise:Promise| be |document|'s\n {{Document/[[orientationPendingPromise]]}}.\n ","[=Queue a global task=] on the [=DOM manipulation task source=]\n with |document|'s [=relevant global object=] to [=reject=] |promise|\n with a new |exceptionName| {{DOMException}}.\n ","Set |document|'s {{Document/[[orientationPendingPromise]]}} to\n `null`.\n ","\n Applying an orientation lock\n ","\n When steps require to apply orientation lock of\n {{OrientationLockType?}} |orientation| to {{Document}} |document|, the\n [=user agent=] MUST perform do the following steps:\n ","If |document| stops being [=Document/fully active=] while [=in\n parallel=], and {{Document/[[orientationPendingPromise]]}} is not\n `null`, [=reject and nullify the current lock promise=] of |document|\n with an {{\"AbortError\"}}.\n ","Let |topDocument| be |document|'s [=top-level browsing context=]'s\n [=navigable/active document=].\n ","Let |descendantDocs| be an [=ordered set=] consisting of\n |topDocument|'s [=Document/descendant navigables=]'s [=navigable/active\n documents=], if any, in tree order.\n ","[=Set/For each=] |doc:Document| in |descendantDocs|:\n ","If |doc| is |document|, continue.\n ","If |doc| {{Document/[[orientationPendingPromise]]}} is `null`,\n continue.\n ","[=Reject and nullify the current lock promise=] of |doc| with\n an {{\"AbortError\"}}.\n ","Run the following sub-steps [=in parallel=]:\n ","If |document| has stopped being [=Document/fully active=], and\n if the |document|'s {{Document/[[orientationPendingPromise]]}} is\n not `null`, [=reject and nullify the current lock promise=] of\n |document| with an {{\"AbortError\"}} and abort these steps.\n ","If |orientation| is `null`, [=unlock the screen orientation=].\n ","Otherwise, attempt to [=lock the screen orientation=] to\n |orientation|. Depending on platform conventions, change how the\n viewport is drawn to match |orientation|.\n ","If the attempt fails due to previously-established user\n preference, or platform limitation, or any other reason:\n ","Set the screen's [=Screen/active orientation lock=] to\n `null`.\n ","[=Queue a task=] on the [=DOM manipulation task source=]\n with |document|'s [=relevant global object=] to:\n ","If the |document|'s\n {{Document/[[orientationPendingPromise]]}} is not `null`,\n [=reject and nullify the current lock promise=] of\n |document| with a {{\"NotSupportedError\"}}.\n ","Abort these steps.\n ","\n This can happen if the user has set a preference that prevents\n web applications from changing the screen orientation, or if\n the underlying platform, rather than the user agent, does not\n allow locking the screen orientation to the given\n |orientation|.\n ","Set the screen's [=Screen/active orientation lock=] to\n |orientation| and update the [=Screen/current orientation type=]\n and [=Screen/current orientation angle=] to reflect any changes to\n the [=screen orientation=].\n ","[=Queue a global task=] on the [=DOM manipulation task source=]\n with |document|'s [=relevant global object=] to:\n ","Let |promise:Promise?| be |document|'s\n {{Document/[[orientationPendingPromise]]}}.\n ","\n As the promise needs to resolve after a \"change\" event is fired, we keep a\n reference to prevent it from being aborted by an event's\n handler function calling {{ScreenOrientation/lock()}}.\n ","Set |document|'s {{Document/[[orientationPendingPromise]]}} to\n `null`.\n ","Run the [=screen orientation change steps=] with |topDocument|.\n ","If |promise| is not `null`, [=resolve=] |promise| with\n `undefined`.\n ","\n Screen orientation change\n ","\n When a user-agent determines that the screen's orientation has changed\n for a [=top-level browsing context=], or the user moves the [=top-level\n browsing context=] to a different screen, then run the [=screen\n orientation change steps=] with the [=top-level browsing context=]'s\n [=navigable/active document=].\n ","\n The screen orientation change steps for\n {{Document}} |document:Document| are as follows:\n ","If |document|'s [=Document/visibility state=] is \"hidden\", abort\n these steps.\n ","Let |type| and |angle| be the screen's [=Screen/current orientation\n type=] and [=Screen/current orientation angle=].\n ","Let |screenOrientation| be |document|'s [=relevant global\n object=]'s [=associated `ScreenOrientation`=].\n ","If |type| is equal to |screenOrientation|'s\n {{ScreenOrientation/[[type]]}} and |angle| is equal to\n |screenOrientation|'s {{ScreenOrientation/[[angle]]}}, abort these\n steps.\n ","[=Queue a global task=] on the [=user interaction task source=]\n with |document|'s [=relevant global object=] to perform the following\n steps:\n ","Set |screenOrientation|'s {{ScreenOrientation/[[angle]]}} to\n |angle|.\n ","Set |screenOrientation|'s {{ScreenOrientation/[[type]]}} to\n |type|.\n ","[=Fire an event=] named \"change\" at |screenOrientation|.\n ","Let |descendantDocs| be an [=ordered set=] consisting of\n |document|'s [=Document/descendant navigables=]'s [=navigable/active\n documents=], if any, in tree order.\n ","[=Set/For each=] |doc:Document| in |descendantDocs|, run the\n [=screen orientation change steps=] with |doc|.\n ","\n Handling page visibility changes\n ","\n [[HTML]]'s update the visibility state runs the [=screen orientation\n change steps=].\n ","\n Developers need to be aware that [=documents=] with a \"hidden\"\n [=Document/visibility state=] will not receive an orientation change\n event. However, once the [=document=] becomes visible again, it will\n receive the change event.\n ","\n Handling unloading documents\n ","\n Whenever the [=unloading document cleanup steps=] run with a\n |document|, the user agent MUST run the following steps:\n ","If |document| is not a [=top-level browsing context=]'s\n [=navigable/active document=], abort these steps.\n ","Run the [=fully unlock the screen orientation steps=] with\n |document|.\n ","\n Fully unlocking the orientation\n ","\n The fully unlock the screen orientation steps\n for {{Document}} |document:Document| are as follows:\n ","If |document|'s {{Document/[[orientationPendingPromise]]}} is not\n `null`, [=reject and nullify the current lock promise=] of |document|\n with an {{\"AbortError\"}}.\n ","[=Apply orientation lock=] `null` to |topDocument|.\n ","\n Interaction with Fullscreen API\n ","\n A user agent SHOULD restrict the use of {{ScreenOrientation/lock()}} to\n simple fullscreen documents as a [=pre-lock condition=]. [[fullscreen]]\n ","\n When a [=document=] exits fullscreen, it also runs the [=fully unlock\n the screen orientation steps=]. [[fullscreen]]\n ","\n Interaction with Web Application Manifest\n ","\n The [[[appmanifest]]] specification allows web applications to set the\n [=default screen orientation=] via the the [=manifest/orientation=]\n member.\n ","\n A user agent SHOULD require [=installed web applications=] to be\n presented in the \"fullscreen\" [=display mode=] as a [=pre-lock\n condition=].\n ","\n Accessibility considerations\n ","\n As users can have their devices mounted in a fixed orientation (e.g. on\n the arm of a wheelchair), developers that expect users to rotate their\n device when [=locking the screen orientation=] need to be aware of the\n [[[WCAG21]]]'s Orientation Success\n Criterion. The criterion makes it essential that content and functionality is\n available regardless of the [=screen orientation=]. When a particular\n orientation is essential, web\n applications must advise the user of the orientation requirements.\n ","\n Privacy and Security Considerations\n ","\n A screen's [=Screen/current orientation type|type=] and\n [=Screen/current orientation angle|angle=] are a potential\n fingerprinting vector. The following mitigation help protect a user's\n privacy by not revealing how a device is being held, and also prevents\n the [=secondary=] orientation type and associated angles from being\n user for fingerprinting purposes.\n ","\n To resist fingerprinting (e.g., in private browsing), user agents MAY:\n ","For the life of a [=top-level browsing context=], behave as as if\n screen's [=natural=] orientation is\n {{ScreenOrientation/[[initialType]]}}.\n ","Restrict the possible return values of the\n {{ScreenOrientation/type}} getter to\n {{OrientationType/\"portrait-primary\"}} or\n {{OrientationType/\"landscape-primary\"}}. The screen aspect ratio\n determines which is returned.\n ","If the [=Screen/current orientation type=] matches\n {{ScreenOrientation/[[initialType]]}}, return `0` for the\n {{ScreenOrientation/angle}} getter. Otherwise, return `90`.\n ","If the screen orientation changes, only fire the\n change event when the\n [=Screen/current orientation type=] changes from [=portrait=] to\n [=landscape=], or vice versa.\n ","\n Acknowledgments\n ","\n Thanks Christophe Dumez, Anne van Kesteren, Chundong Wang, Fuqiao Xue,\n and Chaals McCathie Nevile for their useful comments.\n ","\n Special thanks to Chris Jones and Jonas Sicking for their contributions\n to the initial design of this API.\n "]}
The Screen Orientation specification standardizes the
types and angles for a device's screen orientation, and provides a
means for locking and unlocking it. The API, defined by this
specification, exposes the current type and angle of the device's
screen orientation, and dispatches events when it changes. This enables
web applications to programmatically adapt the user experience for
multiple screen orientations, working alongside CSS. The API also
allows for the screen orientation to be locked under certain
preconditions. This is particularly useful for applications such as
computer games, where users physically rotate the device, but the
screen orientation itself should not change.
This document is a work in progress.
Example of usage
In this example clicking the "Lock" button requests to go into
fullscreen and then locks the screen to the opposite orientation.
clicking the "unlock" button unlocks the screen.
To lock the
screen orientation to an {{OrientationLockType}} |orientation|
means that the screen can only be rotated by the user to a specific
[=screen orientation=] - possibly at the exclusion of other
orientations. The possible orientations to which the screen can be
rotated is determined by the user agent, a user preference, the
operating system's conventions, or the screen itself. For example,
locking the orientation to [=landscape=] means that the screen can be
rotated by the user to [=landscape-primary=] and maybe
[=landscape-secondary=] if the system allows it, but won't change the
orientation to [=portrait-secondary=] orientation.
To unlock the screen
orientation the end user is unrestricted to rotate the screen to
any [=screen orientation=] that the system allows.
Screen orientation types
A screen can be in, or [=locked=] to, one of the following
screen orientations:
Natural
The most natural orientation for the device's display as determined
by the user agent, the user, the operating system, or the screen
itself. For example, a device viewed, or held upright in the user's
hand, with the screen facing the user. A computer monitor are
commonly naturally [=landscape-primary=], while a mobile phones are
commonly naturally [=portrait-primary=].
Landscape
The screen's aspect ratio has a width greater than the height.
Portrait
The screen's aspect ratio has a height greater than the width.
Primäre
The device's screen [=natural=] orientation for either [=portrait=]
or [=landscape=].
Secondary
The opposite of the device's screen primary orientation for
[=portrait=] or [=landscape=].
Any
The screen can be rotated by the user to any orientation allowed by
the device's operating system or by the end-user.
Default (unlocked)
The device's default behavior for when the screen is [=unlocked=]
(i.e., the [=Screen/active orientation lock=] is `null`). This
orientation is determined by the device's operating system, or the
user agent, or controlled by the end-user, or possibly set by an
[=installed web application=]. For example, when the screen
orientation is unlocked and the user rotates the device, some
devices will limit orientation changes to [=portrait-primary=],
[=landscape-primary=], and [=landscape-secondary=], but not to
[=portrait-secondary=].
The current screen orientation type and angle
The screen of the output device has the following associated
concepts:
Current orientation type
The [=screen orientation=] of the screen, represented as a
{{OrientationType}}.
Current orientation angle
The angle in degrees that the screen is rotated counter-clockwise
from its [=natural=] orientation as derived by the [=screen
orientation values list=].
Active orientation lock
The [=screen orientation=], represented as a
{{OrientationLockType}}, to which the screen is [=locked=], or
`null` when [=unlocked=].
The screen orientation values lists below standardize the
angles associated with each screen orientation type for screens with
different [=natural=] orientations:
For screens with a [=natural=] [=portrait=] orientation:
[=portrait-primary=]: 0°
[=landscape-primary=]: 90°
[=portrait-secondary=]: 180°
[=landscape-secondary=]: 270°
For screens with a [=natural=] [=landscape=] orientation:
[=landscape-primary=]: 0°
[=portrait-primary=]: 90°
[=landscape-secondary=]: 180°
[=portrait-secondary=]: 270°
Extensions to the `Document` interface
Internal Slots
The {{Document}} interface is extended with the following internal
slots:
Internal Slot
Description
[[\orientationPendingPromise]]
Either `null` or a {{Promise}}. When assigned a {{Promise}},
that promise represents a request to lock the screen
orientation.
The {{Window}} object has an associated `ScreenOrientation`,
which is a {{Screen}}'s {{Screen/orientation}} object (i.e., the
{{ScreenOrientation}} instance at `window.screen.orientation`).
Represents the screen's last known [=Screen/current orientation
angle=] in degrees as an {{unsigned short}} as derived from the
[=screen orientation values lists=].
[[\initialType]]
Represents the screen's [=Screen/current orientation type=]
when the [=browsing context=] was created.
[[\type]]
Represents the screen's last known [=Screen/current orientation
type=] as an {{OrientationType}} enum value.
`lock()` method
When the {{lock()}} method is invoked with {{OrientationLockType}}
|orientation:OrientationLockType|, the [=user agent=] MUST run the
following steps.
The [=user agent=] MAY require a [=document=] and its associated
[=Document/browsing context=] to meet one or more pre-lock
conditions in order to [=lock the screen orientation=]. See
[[[#appmanifest-interaction]]] and [[[#fullscreen-interaction]]].
Let |document:Document| be [=this=]'s [=relevant global
object=]'s [=associated `Document`=].
Run the [=common safety checks=] with |document|. If an
[=exception=] is [=exception/throw|thrown=], return [=a promise
rejected with=] that exception and abort these steps.
If the [=user agent=] does not support locking the screen
orientation to |orientation|, return [=a promise rejected with=] a
{{"NotSupportedError"}} {{DOMException}} and abort these steps.
If |document|'s
{{Document/[[orientationPendingPromise]]}} is not `null`, [=reject
and nullify the current lock promise=] of |document| with an
{{"AbortError"}}.
Set |document|'s
{{Document/[[orientationPendingPromise]]}} to [=a new promise=].
[=Apply orientation lock=] |orientation| to |document|.
When the {{unlock()}} method is invoked, the [=user agent=] MUST run
the following steps:
Let |document:Document| be [=this=]'s [=relevant global
object=]'s [=associated `Document`=].
Run the [=common safety checks=] with |document|. If an
[=exception=] is [=exception/throw|thrown=], re-throw that exception
and abort these steps.
If screen's [=Screen/active orientation lock=] is `null`, return
`undefined`.
If |document|'s {{Document/[[orientationPendingPromise]]}} is not
`null`, [=reject and nullify the current lock promise=] of |document|
with an {{"AbortError"}}.
[=Apply orientation lock=] `null` to |document|.
{{unlock()}} does not return a promise because it is equivalent to
locking to the [=default screen orientation=] which might or might
not be known by the [=user agent=]. Hence, the [=user agent=] can not
predict what the new orientation is going to be and even if it is
going to change at all.
Common Safety Checks
The common safety checks for a {{Document}}
|document:Document| are the following steps:
If |document| is not
[=Document/fully active=], [=exception/throw=] an
{{"InvalidStateError"}} {{DOMException}}.
If |document| has the
[=sandboxed orientation lock browsing context flag=] set,
[=exception/throw=] {{"SecurityError"}} {{DOMException}}.
If |document|'s
[=Document/visibility state=] is "hidden", [=exception/throw=]
{{"SecurityError"}} {{DOMException}}.
`type` attribute
When getting, the {{type}} attribute returns [=this=]'s
{{ScreenOrientation/[[type]]}}.
`angle` attribute
When getting, the {{angle}} attribute returns [=this=]'s
{{ScreenOrientation/[[angle]]}}.
`onchange` event handler attribute
The {{onchange}} attribute is an [=event handler IDL attribute=] for
the {{onchange}} [=event handler=], whose [=event handler event type=]
is change.
When a [=browsing context=] |context| is created, the [=user agent=]
MUST:
Let |screenOrientation| be |context|'s [=associated
`ScreenOrientation`=].
Initialize |screenOrientation|'s
{{ScreenOrientation/[[initialType]]}} internal slot to the screen's
[=Screen/current orientation type=].
Initialize |screenOrientation|'s {{ScreenOrientation/[[type]]}}
internal slot to the screen's [=Screen/current orientation type=].
Initialize |screenOrientation|'s {{ScreenOrientation/[[angle]]}}
internal slot to the screen's [=Screen/current orientation angle=].
Rejecting a document's current lock promise
When steps require to reject and nullify the current lock
promise of {{Document}} |document| with a {{DOMString}}
|exceptionName|, the [=user agent=] MUST:
[=/Assert=]: {{Document/[[orientationPendingPromise]]}} is not
`null`.
Let |promise:Promise| be |document|'s
{{Document/[[orientationPendingPromise]]}}.
[=Queue a global task=] on the [=DOM manipulation task source=]
with |document|'s [=relevant global object=] to [=reject=] |promise|
with a new |exceptionName| {{DOMException}}.
Set |document|'s {{Document/[[orientationPendingPromise]]}} to
`null`.
Applying an orientation lock
When steps require to apply orientation lock of
{{OrientationLockType?}} |orientation| to {{Document}} |document|, the
[=user agent=] MUST perform do the following steps:
If |document| stops being [=Document/fully active=] while [=in
parallel=], and {{Document/[[orientationPendingPromise]]}} is not
`null`, [=reject and nullify the current lock promise=] of |document|
with an {{"AbortError"}}.
Let |topDocument| be |document|'s [=top-level browsing context=]'s
[=navigable/active document=].
Let |descendantDocs| be an [=ordered set=] consisting of
|topDocument|'s [=Document/descendant navigables=]'s [=navigable/active
documents=], if any, in tree order.
[=Set/For each=] |doc:Document| in |descendantDocs|:
If |doc| is |document|, continue.
If |doc| {{Document/[[orientationPendingPromise]]}} is `null`,
continue.
[=Reject and nullify the current lock promise=] of |doc| with
an {{"AbortError"}}.
Run the following sub-steps [=in parallel=]:
If |document| has stopped being [=Document/fully active=], and
if the |document|'s {{Document/[[orientationPendingPromise]]}} is
not `null`, [=reject and nullify the current lock promise=] of
|document| with an {{"AbortError"}} and abort these steps.
If |orientation| is `null`, [=unlock the screen orientation=].
Otherwise, attempt to [=lock the screen orientation=] to
|orientation|. Depending on platform conventions, change how the
viewport is drawn to match |orientation|.
If the attempt fails due to previously-established user
preference, or platform limitation, or any other reason:
Set the screen's [=Screen/active orientation lock=] to
`null`.
[=Queue a task=] on the [=DOM manipulation task source=]
with |document|'s [=relevant global object=] to:
If the |document|'s
{{Document/[[orientationPendingPromise]]}} is not `null`,
[=reject and nullify the current lock promise=] of
|document| with a {{"NotSupportedError"}}.
Abort these steps.
This can happen if the user has set a preference that prevents
web applications from changing the screen orientation, or if
the underlying platform, rather than the user agent, does not
allow locking the screen orientation to the given
|orientation|.
Set the screen's [=Screen/active orientation lock=] to
|orientation| and update the [=Screen/current orientation type=]
and [=Screen/current orientation angle=] to reflect any changes to
the [=screen orientation=].
[=Queue a global task=] on the [=DOM manipulation task source=]
with |document|'s [=relevant global object=] to:
Let |promise:Promise?| be |document|'s
{{Document/[[orientationPendingPromise]]}}.
Set |document|'s {{Document/[[orientationPendingPromise]]}} to
`null`.
Run the [=screen orientation change steps=] with |topDocument|.
If |promise| is not `null`, [=resolve=] |promise| with
`undefined`.
Screen orientation change
When a user-agent determines that the screen's orientation has changed
for a [=top-level browsing context=], or the user moves the [=top-level
browsing context=] to a different screen, then run the [=screen
orientation change steps=] with the [=top-level browsing context=]'s
[=navigable/active document=].
The screen orientation change steps for
{{Document}} |document:Document| are as follows:
If |document|'s [=Document/visibility state=] is "hidden", abort
these steps.
Let |type| and |angle| be the screen's [=Screen/current orientation
type=] and [=Screen/current orientation angle=].
Let |screenOrientation| be |document|'s [=relevant global
object=]'s [=associated `ScreenOrientation`=].
If |type| is equal to |screenOrientation|'s
{{ScreenOrientation/[[type]]}} and |angle| is equal to
|screenOrientation|'s {{ScreenOrientation/[[angle]]}}, abort these
steps.
[=Queue a global task=] on the [=user interaction task source=]
with |document|'s [=relevant global object=] to perform the following
steps:
Set |screenOrientation|'s {{ScreenOrientation/[[angle]]}} to
|angle|.
Set |screenOrientation|'s {{ScreenOrientation/[[type]]}} to
|type|.
[=Fire an event=] named "change" at |screenOrientation|.
Let |descendantDocs| be an [=ordered set=] consisting of
|document|'s [=Document/descendant navigables=]'s [=navigable/active
documents=], if any, in tree order.
[=Set/For each=] |doc:Document| in |descendantDocs|, run the
[=screen orientation change steps=] with |doc|.
Handling page visibility changes
[[HTML]]'s update the visibility state runs the [=screen orientation
change steps=].
Handling unloading documents
Whenever the [=unloading document cleanup steps=] run with a
|document|, the user agent MUST run the following steps:
If |document| is not a [=top-level browsing context=]'s
[=navigable/active document=], abort these steps.
Run the [=fully unlock the screen orientation steps=] with
|document|.
Fully unlocking the orientation
The fully unlock the screen orientation steps
for {{Document}} |document:Document| are as follows:
If |document|'s {{Document/[[orientationPendingPromise]]}} is not
`null`, [=reject and nullify the current lock promise=] of |document|
with an {{"AbortError"}}.
Let |topDocument| be |document|'s [=top-level browsing context=]'s
[=navigable/active document=].
[=Apply orientation lock=] `null` to |topDocument|.
Interaction with Fullscreen API
A user agent SHOULD restrict the use of {{ScreenOrientation/lock()}} to
simple fullscreen documents as a [=pre-lock condition=]. [[fullscreen]]
When a [=document=] exits fullscreen, it also runs the [=fully unlock
the screen orientation steps=]. [[fullscreen]]
Interaction with Web Application Manifest
The [[[appmanifest]]] specification allows web applications to set the
[=default screen orientation=] via the the [=manifest/orientation=]
member.
A user agent SHOULD require [=installed web applications=] to be
presented in the "fullscreen" [=display mode=] as a [=pre-lock
condition=].
Accessibility considerations
As users can have their devices mounted in a fixed orientation (e.g. on
the arm of a wheelchair), developers that expect users to rotate their
device when [=locking the screen orientation=] need to be aware of the
[[[WCAG21]]]'s Orientation Success
Criterion. The criterion makes it essential that content and functionality is
available regardless of the [=screen orientation=]. When a particular
orientation is essential, web
applications must advise the user of the orientation requirements.
Privacy and Security Considerations
A screen's [=Screen/current orientation type|type=] and
[=Screen/current orientation angle|angle=] are a potential
fingerprinting vector. The following mitigation help protect a user's
privacy by not revealing how a device is being held, and also prevents
the [=secondary=] orientation type and associated angles from being
user for fingerprinting purposes.
To resist fingerprinting (e.g., in private browsing), user agents MAY:
For the life of a [=top-level browsing context=], behave as as if
screen's [=natural=] orientation is
{{ScreenOrientation/[[initialType]]}}.
Restrict the possible return values of the
{{ScreenOrientation/type}} getter to
{{OrientationType/"portrait-primary"}} or
{{OrientationType/"landscape-primary"}}. The screen aspect ratio
determines which is returned.
If the [=Screen/current orientation type=] matches
{{ScreenOrientation/[[initialType]]}}, return `0` for the
{{ScreenOrientation/angle}} getter. Otherwise, return `90`.
If the screen orientation changes, only fire the
change event when the
[=Screen/current orientation type=] changes from [=portrait=] to
[=landscape=], or vice versa.
Acknowledgments
Thanks Christophe Dumez, Anne van Kesteren, Chundong Wang, Fuqiao Xue,
and Chaals McCathie Nevile for their useful comments.
Special thanks to Chris Jones and Jonas Sicking for their contributions
to the initial design of this API.