-
Notifications
You must be signed in to change notification settings - Fork 673
/
Overview.bs
610 lines (495 loc) · 26.1 KB
/
Overview.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
<pre class="metadata">
Title: CSS Viewport Module Level 1
Level: 1
Shortname: css-viewport
Group: CSSWG
Status: FPWD
Date: 2024-01-25
Prepare for TR: yes
Work Status: Exploring
TR: http://www.w3.org/TR/css-viewport-1/
ED: https://drafts.csswg.org/css-viewport-1/
Previous Version: http://www.w3.org/TR/2016/WD-css-device-adapt-1-20160329/
Editor: Florian Rivoal, Invited Expert, https://florian.rivoal.net, w3cid 43241
Editor: Emilio Cobos Álvarez, Mozilla, [email protected], w3cid 106537
Former Editor: Matt Rakow, Microsoft, w3cid 62267
Former Editor: Rune Lillesveen, Opera Software, [email protected]
Former Editor: Ryan Betts, Adobe Systems, [email protected]
Former Editor: Øyvind Stenhaug, Opera Software, [email protected]
Abstract: This specification provides a way for an author to specify, in CSS, the size, zoom factor, and orientation of the viewport that is used as the base for the initial containing block.
Issue Tracking: CSSWG GitHub https://github.com/w3c/csswg-drafts/labels/css-viewport-1
Ignored Vars: <viewport-length>
</pre>
<pre class="anchors">
spec: virtual-keyboard; urlPrefix: https://w3c.github.io/virtual-keyboard
type: interface; text: VirtualKeyboard; url: dom-virtualkeyboard
type: attribute; text: overlaysContent; for: VirtualKeyboard; url: dom-virtualkeyboard-overlayscontent
</pre>
<pre class="anchors">
spec: fenced-frames; urlPrefix: https://wicg.github.io/fenced-frame/
type: interface; text: FencedFrames
</pre>
<h2 id="intro">
Introduction</h2>
<div class=non-normative>
<em>This section is not normative.</em>
CSS 2.1 [[!CSS21]] specifies an
<a href="https://www.w3.org/TR/CSS21/visudet.html#containing-block-details">
initial containing block</a> for [=continuous media=] that has the dimensions
of the <a href="https://www.w3.org/TR/CSS21/visuren.html#viewport">
viewport</a>. Since the viewport is generally no larger than the display,
devices with smaller displays such as phones or tablets typically present
a smaller viewport than larger devices like desktop or laptops.
Unfortunately, many documents have historically been designed against larger
viewports and exhibit a variety of bugs when viewed in smaller viewports.
These include unintended layout wrapping, clipped content, awkward scrollable
bounds, and script errors. To avoid these issues, mobile browsers generally
use a fixed initial containing block width that mimics common desktop browser
window size (typically 980-1024px). The resulting layout is then scaled down
to fit in the available screen space.
Although this approach mitigates the issues mentioned above, the downscaling
means the CSS pixel size will be smaller than
<a href="https://www.w3.org/TR/CSS21/syndata.html#length-units">recommended</a>
by CSS 2.1. Users will likely need to zoom on the content to view it
comfortably.
This mitigation is unnecessary for sites that have been designed to work
well on small viewports.
Issue: This specification is written from an implementation-centric point of view,
making it arguably difficult to read.
Significant editorial work may be needed
to make it more understandable to different audiences.
It also should clarify which viewport is referred to by various js APIs.
See <a href="http://www.quirksmode.org/blog/archives/2015/09/a_new_device_ad.html">this blog post by ppk</a>
for a good discussion of these issues.
Issue: Various issues about this specification and related specifications
are listed in <a href="https://www.w3.org/Graphics/SVG/WG/wiki/Proposals/Investigation_of_APIs_for_Level_of_detail#The_issues_on_existing_APIs">this report</a>.
</div>
<h2 id="the-viewport">
The viewport</h2>
In CSS 2.1 a <a href="https://www.w3.org/TR/CSS21/visuren.html#viewport">viewport</a>
is a feature of a user agent for [=continuous media=] and used to
establish the initial containing block for [=continuous media=].
For [=paged media=], the initial containing block is based on the page area.
The page area can be set through ''@page'' rules.
This specification introduces a way of overriding the size of the viewport
provided by the user agent (UA). Because of this, we need to introduce the
difference between the ''initial viewport'' and the ''actual viewport''.
<dl>
<dt><dfn>initial viewport</dfn></dt>
<dd>
This refers to the viewport before any UA or author styles have
overridden the viewport given by the window or viewing area of the UA.
Note that the ''initial viewport'' size will change with the
size of the window or viewing area.</dd>
<dt><dfn>actual viewport</dfn></dt>
<dd>
This is the viewport you get after processing the viewport
<code><meta></code> tag.
</dd>
</dl>
ISSUE: Make ''actual viewport'' the layout viewport, define visual viewport.
When the ''actual viewport'' cannot fit inside the window or
viewing area, either because the ''actual viewport'' is
larger than the ''initial viewport'' or the zoom factor
causes only parts of the ''actual viewport'' to be visible,
the UA should offer a scrolling or panning mechanism.
It is recommended that initially the upper-left corners of the
''actual viewport'' and the window or viewing area are aligned if the
base direction of the document is ltr. Similarly, that the upper-right
corners are aligned when the base direction is rtl. The base direction
for a document is defined as the computed value of the 'direction'
property for the first <code class=html><BODY></code> element of
an HTML or XHTML document. For other document types, it is the
computed 'direction' for the root element.
<h2 id="viewport-meta">
Viewport <code class=html><meta></code> element</h2>
Issue: Specify me
<h3 id="meta-properties">
Properties</h3>
The recognized properties in the viewport
<code class=html><meta></code> element are:
<ul>
<li><code class="index" lt="width!!viewport meta">width</code></li>
<li><code class="index" lt="height!!viewport meta">height</code></li>
<li><code class="index">initial-scale</code></li>
<li><code class="index">minimum-scale</code></li>
<li><code class="index">maximum-scale</code></li>
<li><code class="index">user-scalable</code></li>
<li><code class="index">interactive-widget</code></li>
</ul>
<h3 id="parsing-algorithm">
Parsing algorithm</h3>
Below is an algorithm for parsing the <code class=html>content</code>
attribute of the <code class=html><meta></code> tag produced
from testing Safari on the iPhone. <span class="note"> The testing was
done on an iPod touch running iPhone OS 4. The UA string of the
browser: <code>"Mozilla/5.0 (iPod; U; CPU iPhone OS 4_0 like Mac OS X;
en-us) AppleWebKit/532.9 (KHTML, like Gecko) Version/4.0.5
Mobile/8A293 Safari/6531.22.7"</code>.</span> The pseudo code notation
used is based on the notation used in [[Algorithms]].
The whitespace class contains the following characters (ascii):
<ul>
<li>Horizontal tab (0x09)</li>
<li>Line feed (0x0a)</li>
<li>Carriage return (0x0d)</li>
<li>Space (0x20)</li>
</ul>
The recognized separator between property/value pairs is comma for the
Safari implementation. Some implementations have supported both commas
and semicolons. Because of that, existing content use semicolons instead
of commas. Authors should be using comma in order to ensure content works
as expected in all UAs, but implementors may add support for both to ensure
interoperability for existing content.
The separator class contains the following characters (ascii), with
comma as the preferred separator and semicolon as optional:
<ul>
<li>Comma (0x2c)</li>
<li>Semicolon (0x3b)</li>
</ul>
<style>
/* Style for algorithm pseudo code. */
#algorithm {
font-family: serif;
font-size: 1em;
white-space: pre;
margin: 1em;
padding: 1em;
}
#algorithm .method {
counter-reset: statement;
line-height: 1.5em;
}
#algorithm .method-name {
font-variant: small-caps;
}
#algorithm .statement {
counter-increment: statement;
}
#algorithm .statement:before {
content: counter(statement) " ";
display: inline-block;
width: 2em;
}
#algorithm .keyword {
font-weight: bold;
}
</style>
<pre id="algorithm">
<span class="method"><span class="method-name">Parse-Content</span>(<span class="variable">S</span>)</span>
<span class="statement"><span class="variable">i</span> ← 1</span>
<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> ≤ <span class="op">length</span>[<span class="variable">S</span>]</span>
<span class="statement"> <span class="keyword">do</span> <span class="keyword">while</span> <span class="variable">i</span> ≤ <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] in [whitespace, separator, '=']</span>
<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> ← <span class="variable">i</span> + 1</span>
<span class="statement"> <span class="keyword">if</span> <span class="variable">i</span> ≤ <span class="op">length</span>[<span class="variable">S</span>]</span>
<span class="statement"> <span class="keyword">then</span> <span class="variable">i</span> ← <span class="method-name">Parse-Property</span>(<span class="variable">S</span>, <span class="variable">i</span>)</span>
<span class="method"><span class="method-name">Parse-Property</span>(<span class="variable">S</span>, <span class="variable">i</span>)</span>
<span class="statement"><span class="variable">start</span> ← <span class="variable">i</span></span>
<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> ≤ <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] <span class="keyword">not</span> in [whitespace, separator, '=']</span>
<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> ← <span class="variable">i</span> + 1</span>
<span class="statement"><span class="keyword">if</span> <span class="variable">i</span> > <span class="op">length</span>[<span class="variable">S</span>] or <span class="variable">S</span>[<span class="variable">i</span>] in [separator]</span>
<span class="statement"> <span class="keyword">then</span> <span class="keyword">return</span> <span class="variable">i</span></span>
<span class="statement"><span class="variable">property-name</span> ← <span class="variable">S</span>[<span class="variable">start</span> .. (<span class="variable">i</span> - 1)]</span>
<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> ≤ <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] <span class="keyword">not</span> in [separator, '=']</span>
<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> ← <span class="variable">i</span> + 1</span>
<span class="statement"><span class="keyword">if</span> <span class="variable">i</span> > <span class="op">length</span>[<span class="variable">S</span>] or <span class="variable">S</span>[<span class="variable">i</span>] in [separator]</span>
<span class="statement"> <span class="keyword">then</span> <span class="keyword">return</span> <span class="variable">i</span></span>
<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> ≤ <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] in [whitespace, '=']</span>
<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> ← <span class="variable">i</span> + 1</span>
<span class="statement"><span class="keyword">if</span> <span class="variable">i</span> > <span class="op">length</span>[<span class="variable">S</span>] or <span class="variable">S</span>[<span class="variable">i</span>] in [separator]</span>
<span class="statement"> <span class="keyword">then</span> <span class="keyword">return</span> <span class="variable">i</span></span>
<span class="statement"><span class="variable">start</span> ← <span class="variable">i</span></span>
<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> ≤ <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] <span class="keyword">not</span> in [whitespace, separator, '=']</span>
<span class="statement"> <span class="keyword">do</span> <span class="variable">i</span> ← <span class="variable">i</span> + 1</span>
<span class="statement"><span class="variable">property-value</span> ← <span class="variable">S</span>[<span class="variable">start</span> .. (<span class="variable">i</span> - 1)]</span>
<span class="statement"><span class="method-name">Set-Property</span>(<span class="variable">property-name</span>, <span class="variable">property-value</span>)</span>
<span class="statement"><span class="keyword">return</span> <span class="variable">i</span></span>
</pre>
<span class="method-name">Set-Property</span> matches the
<a href="#meta-properties">listed property names</a> case-insensitively.
The <code class="variable">property-value</code> strings are interpreted
as follows:
<ol>
<li>
If a prefix of <code class="variable">property-value</code>
can be converted to a number using <code>strtod</code>, the
value will be that number. The remainder of the string is
ignored.
</li>
<li>
If the value can not be converted to a number as described above,
the whole <code class="variable">property-value</code> string
will be matched with the following strings
case-insensitively: <code class="index">yes</code>,
<code class="index">no</code>, <code class="index" lt="device-width!!viewport meta">device-width</code>,
<code class="index" lt="device-height!!viewport meta">device-height</code>
</li>
<li>
If the string did not match any of the known strings, the
value is unknown.
</li>
</ol>
<h3 id="extend-to-zoom">''extend-to-zoom''</h3>
Issue: Specify extend-to-zoom behavior by the viewport meta tag
<h3 id="interactive-widget-section">''interactive-widget''</h3>
Issue: Move the definition of ''visual viewport'' from CSSOM-View to this spec.
The <dfn export><code>interactive-widget</code></dfn> property specifies the effect that interactive UI
widgets have on the page's viewports. It defines whether widgets overlay a given viewport or whether
the viewport is shrunken so that it remains fully visible while the widget is showing. Interactive
UI widgets are transient user agent or operating system UI through which a user can provide input.
<div class="note">The most common such UI widget is a virtual keyboard.</div>
The following is a list of valid values for [=interactive-widget=] and the associated
viewport-resizing behavior:
<dl>
<dt><dfn><code>overlays-content</code></dfn></dt>
<dd>
Interactive UI widgets MUST NOT [=resize=] the [=initial viewport=] nor
the <a spec="CSSOM-VIEW">visual viewport</a>. The user agent must perform the same steps
as when {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} is set to
<code>true</code>.
</dd>
<dt><dfn><code>resizes-content</code></dfn></dt>
<dd>
Interactive UI widgets MUST [=resize=] the [=initial viewport=] by the interactive widget.
<div class="note">
Since the <a spec="CSSOM-VIEW">visual viewport</a>'s size is derived from the
[=initial viewport=], [=resizes-content=] will cause a resize of both the initial and visual
viewports.
</div>
</dd>
<dt><dfn><code>resizes-visual</code></dfn></dt>
<dd>
Interactive UI widgets MUST [=resize=] the <a spec="CSSOM-VIEW">visual viewport</a> but MUST
NOT [=resize=] the <a spec="CSS-VIEWPORT">initial viewport</a>.
</dd>
</dl>
If no value, or an invalid value, is set for [=interactive-widget=], the behavior implied by
[=resizes-visual=] is used as the default.
To <dfn lt="resize">resize a viewport by an interactive widget</dfn>, subtract from it the
intersection of the viewport rect with the widget's OS reported bounding rect. In cases where this
would result in a non-rectangular viewport, the behavior is user agent defined.
<div class="note">
Some examples where the result would non rectangular: a
<a href="https://support.apple.com/en-ca/HT207521">floating or split keyboard</a>, or a keyboard that
<a href="https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/VirtualKeyboardAPI/explainer.md#motivation">
occupies only part</a> of the viewport.
</div>
<h4 id="interaction-with-virtualkeyboard-overlayscontent">
Interaction with virtualKeyboard.overlaysContent
</h4>
[[!VIRTUAL-KEYBOARD]] provides an imperative API to apply the [=overlays-content=] behavior via
the {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} attribute. This attribute
shadows the value set to [=interactive-widget=], namely:
When {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} is set to
<code>true</code>, the UA MUST ignore any value set to [=interactive-widget=] when determining the
resizing behavior of interactive widgets.
When {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} is set to
<code>false</code>, the UA MUST use the value set to [=interactive-widget=], or the default behavior
if a value is not set, when determining the resizing behavior of interactive widgets.
Getting the value of {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} MUST return
only the value previously set to it.
<div class="note">
That is, unless previously set, <code>VirtualKeyboard.overlaysContent</code> returns false
even if <code>interactive-widget=overlays-content</code> is set via the <code><meta></code>
tag.
</div>
<pre class=biblio>
{
"Algorithms": {
"authors": [
"Thomas H. Cormen; et al"
],
"title": "Introduction to Algorithms, Second Edition, MIT Press",
"publisher": "MIT Press"
}
}
</pre>
<h2 id='zoom-property'>
The 'zoom' property
</h2>
An element becomes zoomed when the 'zoom' property has a positive computed value different than 1
(or when a flat tree ancestor has zoom).
To apply zoom, the [=used value=] of a CSS property (including values inside of [=path()=] strings) is pre-multiplied
(before any other steps in the [=used value=] stage)
by the [=used value=] of 'zoom' for the element.
It also multiplies the [=natural size=] of all replaced elements,
background images,
and nested frames
(except for fenced frames [[!FENCED-FRAME]])
by the [=used value=] of 'zoom'.
Note: This results in a magnification or minification effect.
Note: Since this multiplication is on [=computed value=]s, it applies to
all inherited properties such as 'line-height' and 'font-size'.
Nested values of 'zoom' multiply, resulting in additional scaling of <<length>> values.
The [=used value=] for zoom is always its [=effective zoom=].
The 'zoom' property has no effect on <<length>> property values with computed values that are 'auto' or <<percentage>>.
Note: Unlike 'transform',
scaling the 'zoom' property affects layout.
Note: The computed value of 'font-size' is never <<percentage>>;
thus 'zoom' always applies.
Note: 'zoom' does not affect or prevent 'transform' scaling.
<pre class="propdef">
Name: zoom
Value: <<number [0,∞]>> || <<percentage [0,∞]>>
Initial: 1
Applies to: all <<length>> property values of all elements
Inherited: no
Percentages: Converted to <<number>>
Media: visual
Computed value: as specified, but with <<percentage>> converted to the equivalent <<number>>
Animation type: not animatable
</pre>
The values of this property have the following meanings:
<dl dfn-for="zoom" dfn-type=value>
<dt><dfn><<number>></dfn>
<dd>
Positive floating point number indicating a zoom factor.
Numbers smaller than 1.0 indicate a "zoom out" or minification effect,
while numbers greater than 1.0 indicate a "zoom in" or magnification effect.
A 0 value is treated as if it was 1.
Note: The treatment of 0 is a web compatibility quirk.
<dt><dfn><<percentage>></dfn>
<dd>
Positive floating point number,
followed by a percentage character ("%") which indicates a zoom factor multiplied by 100.
A 0 percentage is treated as if it was 100%.
Note: The treatment of 0 is a web compatibility quirk.
</dl>
Negative values for 'zoom' are illegal.
<div class="example">
Example of the 'zoom' property applied during hover for magnification effect.
<pre>
<div class="messageBox">
<div class="label">Text of the label</div>
</div>
<style>
.messageBox {
width: 10em;
padding: 2em;
border: medium solid lightblue;
}
.messageBox:hover {
zoom: 150%;
}
.label {
background: lightgrey;
padding: 1em;
text-align: center;
}
</style>
</pre>
Here is an llustration of the before and after hover state of the message box element:
<img src="css_zoom_hover_example.png" alt="Two images,
showing the zooming effect before and after zoom has applied. The second is 1.5 larger.">
</div>
<div class="example">
Example of nested zoom.
In this example, "Inner text" is 4x as large as "Outer text",
and "Middle text" is 2x as large as "Outer text".
<pre>
<div style="zoom: 2">
Middle text
<div style="zoom: 2">
Inner text
<div>
<div>
Outer text
</pre>
</div>
<div class="example">
Example of replaced elements. In this example,
the image and iframe will be twice as large as their default sizing.
<pre>
<div style="zoom: 2">
<img src="...">
<iframe src="..."></iframe>
<div>
</pre>
</div>
The <dfn export>effective zoom</dfn> of an element is the product of its computed
value of 'zoom' and all flat tree ancestors' computed values of 'zoom'.
The <dfn export>scaled</dfn> value of a CSS length is the [=used value=] of that length;
in particular it includes zoom.
The <dfn export>unscaled</dfn> value of a CSS length relative to an element is the [=scaled=] value divided by the element's [=effective zoom=].
<div class="note">
The [=effective zoom=] of an element in a nested frame may be a value other than 1 even if 'zoom' is never set on an element in that frame. This can be observed by authors via APIs such as {{Window/devicePixelRatio}} and {{Element/getBoundingClientRect}}.
</div>
<h3 id='zoom-om'>
DOM and CSSOM interaction
</h3>
Computed style APIs (i.e., all values returned by {{getComputedStyle()}}) that are non-auto and non-percentage lengths must be [=unscaled=].
The {{Element/getBoundingClientRect}},
{{Element/getClientRects}},
and {{IntersectionObserver}} APIs must return rects with [=scaled=]
lengths.
All other APIs related to element geometries must return [=unscaled=] lengths
(except as detailed below).
This is explained in detail in [[cssom-view#extensions-to-the-htmlelement-interface]].
In cases where properties (such as {{Element/scrollTop}}) are propagated to the viewport,
APIs for these lengths must be in viewport units,
and not be divided by the zoom of the element.
The {{Window/devicePixelRatio}} of a frame is multiplied by the [=effective zoom=] inherited by its parent frame.
</h3>
<h2 id=extensions-to-the-window-interface>Extensions to the {{Window}} Interface</h2>
<pre class=idl>
partial interface Window {
[SameObject, Replaceable] readonly attribute Viewport viewport;
};
</pre>
<h2 id=viewport>Viewport</h2>
<h3 id="the-viewport-interface">The {{Viewport}} Interface</h3>
<pre class=idl>
[Exposed=Window]
interface Viewport {
readonly attribute FrozenArray<DOMRect>? segments;
};
</pre>
<h2 id='segments'>
The <dfn attribute for=Viewport>segments</dfn> property
</h2>
The {{segments}} property is an array of {{DOMRect}} that represent the dimensions of each existing viewport segment.
Each {{DOMRect}} contains the geometry of the segment (x, y, width, height) in CSS ''<length>/px''.
Additonal details about the definition of a viewport segment can be found here: [[css-env-1#viewport-segments]].
The {{segments}} attribute must run these steps:
1. If the {{Viewport}}'s associated {{Document}} is not <a>fully active</a>, return null.
2. Returns null if there is only a single viewport segment and abort these steps.
3. Otherwise, return the {{Viewport}}'s [[css-env-1#viewport-segments|segments]] array.
<div class=non-normative>
<em>This section is not normative.</em>
The {{segments}} property represents an immutable snapshot of the device {{segments}} when the value was queried.
If the device state changes (rotation, window resize, <a spec="DEVICE-POSTURE">posture</a> change), the value previously retrieved will be invalid. Developers can listen to {{ScreenOrientation/onchange|Screen Orientation}}, {{Window/resize|Window Resize}}, or {{DevicePosture/onchange|Posture}} changes events to detect device state changes.
<div class="example">
If a viewport of 400px by 400px is split horizontally into two side-by-side segments, the {{segments}} array will have the following content:
<code highlight=javascript>[DOMRect(0, 0, 400, 200), DOMRect(0, 200, 400, 200)]</code>
</div>
</div>
<h2 class="no-num" id="changes">Appendix A. Changes</h2>
This appendix is <em>informative</em>.
<h3 class="no-num">Since the
<a href="http://www.w3.org/TR/2016/WD-css-device-adapt-1-20160329/">29
March 2016 Working Draft</a>
</h3>
<ul>
<li>Added 'interactive-widgets' property to viewport meta</li>
<li>Removed @viewport rule</li>
<li>Renamed spec from device-adapt to css-viewport</li>
<li>CSSViewportRule exposed to Window</li>
</ul>
<h3 class="no-num">Since the
<a href="https://www.w3.org/TR/2011/WD-css-device-adapt-20110915/">15
September 2011 First Public Working Draft</a>.
</h3>
<ul>
<li>Made various editorial improvements and clarifications.
<li>Added OM Interfaces.
<li>Added semi-colon as separator in meta viewport.
<li>Created UA stylesheets section.
<li>Added recommendation for when to respect orientation property.
<li>Dropped support for the resolution descriptor.
<li>Decouple width/height and zoom, introducing ''extend-to-zoom'' value for meta viewport translation.
<li>Made normative rules about interaction of @viewport and @media.
<li>Allow 0 for <<viewport-length>> and '@viewport/zoom' values
<li>Removed support for device-width/height.
<li>Apply @viewport to top level document only.
<li>Extend [[!CSS3-CONDITIONAL]] rather than CSS21 for nesting in @media.
<li>Removed @viewport
</ul>