CSSOM 视图模块

1. 背景

本规范中定义的许多功能已得到浏览器长时间的支持。本规范的目标是以一种所有浏览器都能以互操作方式实现这些功能的方式定义它们。本规范还定义了一些允许自定义滚动的新功能。

2. 术语

本规范使用的术语来自 DOM、CSSOM 和 HTML。[DOM] [CSSOM] [HTML]

如果以下所有条件均为真，则元素 body（即 body 元素）是潜在可滚动的：

• body 具有一个关联的 框 (box)。

• body 的 父元素的 overflow-x 或 overflow-y 属性的计算值既不是 visible 也不是 clip。

• body 的 overflow-x 或 overflow-y 属性的计算值既不是 visible 也不是 clip。

注：一个潜在可滚动的 body 元素可能没有滚动框。例如，它的 overflow 属性的实际值可能是 auto，但其内容并未溢出内容区域。

视口或元素的滚动框 (scrolling box)具有两个溢出方向 (overflow directions)，即该视口或元素的块结束和内联结束方向。请注意，初始滚动位置可能不与滚动区域原点对齐，具体取决于内容分布属性，请参阅 CSS 框对齐 3 § 5.3 对齐溢出和滚动容器。

术语滚动区域 (scrolling area)指视口或元素的一个框，它具有以下边缘，具体取决于该视口或元素的滚动框的溢出方向。

滚动区域的原点 (origin)，如果是视口，则为初始包含块的原点；否则为元素处于默认滚动位置时的顶部左侧内边距边缘。x 坐标向右增加，y 坐标向下增加。

框或元素的一组特定边缘的起始边缘 (beginning edges)是指以下边缘

如果溢出方向是向右和向下

顶部和左侧边缘。

如果溢出方向是向左和向下

顶部和右侧边缘。

如果溢出方向是向左和向上

底部和右侧边缘。

如果溢出方向是向右和向上

底部和左侧边缘。

框或元素的一组特定边缘的结束边缘 (ending edges)是指以下边缘

如果溢出方向是向右和向下

底部和右侧边缘。

如果溢出方向是向左和向下

底部和左侧边缘。

如果溢出方向是向左和向上

顶部和左侧边缘。

如果溢出方向是向右和向上

顶部和右侧边缘。

可视视口 (visual viewport)是一种视口，其滚动区域是另一个视口，称为布局视口 (layout viewport)。

除了滚动之外，可视视口还可以对其布局视口应用缩放变换。此变换应用于布局视口的画布，并且不影响其内部坐标空间。

注：可视视口的缩放变换通常被称为“捏合缩放 (pinch-zoom)”。在概念上，此变换改变了 CSS 参考像素的大小，但按比例改变了布局视口的大小，因此不会导致页面内容的重排。

缩放变换的大小被称为可视视口的缩放因子 (scale factor)。

VisualViewport 对象具有一个关联文档，这是一个 Document 对象。它是 VisualViewport 的所有者 Window 的关联文档。布局视口是所有者 Window 的视口。

为了满足本规范中的要求，display 属性的计算值为 table-column 或 table-column-group 的元素必须被视为具有关联的框（分别为列或列组）。

术语SVG 布局框指由 SVG 元素生成的、不对应于 CSS 定义的 display 类型的框。（例如由 rect 元素生成的框。）

术语变换 (transforms)指 SVG 变换和 CSS 变换。[SVG11] [CSS-TRANSFORMS-1]

当一个方法或属性被说成是调用另一个方法或属性时，用户代理必须为该属性或方法调用其内部 API，以便例如作者不能通过使用 ECMAScript 中的自定义属性或函数覆盖属性或方法来更改行为。

除非另有说明，所有字符串比较均使用 is。

2.1. CSS 像素

除非另有说明，本规范定义的 API 的所有坐标和尺寸均以 CSS 像素为单位。[CSS-VALUES]

注：这不适用于例如 matchMedia()，因为其单位已明确给出。

2.2. 缩放

有两种缩放类型：页面缩放 (page zoom)，它影响初始视口的大小；以及可视视口缩放因子，它像放大镜一样工作，不会影响初始视口或实际视口。[CSS-DEVICE-ADAPT]

注：“缩放因子”通常被称为“捏合缩放”；然而，它可以通过捏合缩放以外的方式受到影响。例如，用户代理可能会放大聚焦的输入元素以使其清晰可见。

2.3. Web 暴露的屏幕信息

用户代理可以选择隐藏有关输出设备屏幕的信息，以保护用户隐私。为了在不同 API 中以一致的方式执行此操作，本规范定义了以下术语，每个术语都具有宽度和高度，原点为左上角，x 和 y 坐标分别向右和向下增加。

Web 暴露的屏幕区域是以下之一：

• 输出设备的区域，以 CSS 像素为单位。

• 视口的区域，以 CSS 像素为单位。

Web 暴露的可用屏幕区域是以下之一：

• 输出设备渲染表面的可用区域，以 CSS 像素为单位。

• 输出设备的区域，以 CSS 像素为单位。

• 视口的区域，以 CSS 像素为单位。

3. 通用基础设施

本规范依赖于 WHATWG Infra 标准。[INFRA]

3.1. 滚动

当滚动位置没有更多待处理的更新或位移，且用户已完成手势时，滚动即完成。滚动位置更新包括平滑或即时鼠标滚轮滚动、键盘滚动、滚动捕获事件或其他导致滚动位置更新并可能插值的 API 和手势。触摸平移或触控板滚动等用户手势直到指针或按键释放才算完成。

当用户代理要对滚动框 box 执行平滑滚动到 position 时，它必须以用户代理定义的方式在用户代理定义的时间内更新 box 的滚动位置。当滚动完成时，box 的滚动位置必须为 position。滚动也可以被中止，可以通过算法或用户操作。

当用户代理要对滚动框 box 执行即时滚动到 position 时，它必须将 box 的滚动位置更新为 position。

要对文档 document 滚动到文档开头，请遵循以下步骤：

1. 设 viewport 为与 document 关联的视口。
2. 设 position 为 viewport 通过将滚动区域的起始边缘与 viewport 的起始边缘对齐时会拥有的滚动位置。
3. 如果 position 与 viewport 当前的滚动位置相同，且 viewport 没有进行中的平滑滚动，则中止这些步骤。
4. 对 viewport 执行滚动到 position，并以 document 的根元素作为关联元素（如果存在），否则为 null。

注：此算法用于导航到 #top 片段标识符时，如 HTML 中定义的那样。[HTML]

3.2. WebIDL 值

当被要求对值 x 规范化非有限值 时，如果 x 是三个特殊浮点字面量值（Infinity、-Infinity 或 NaN）之一，则 x 必须更改为值 0。[WEBIDL]

4. Window 接口的扩展

enum ScrollBehavior { "auto", "instant", "smooth" };

dictionary ScrollOptions {
    ScrollBehavior behavior = "auto";
};
dictionary ScrollToOptions : ScrollOptions {
    unrestricted double left;
    unrestricted double top;
};

partial interface Window {
    [NewObject] MediaQueryList matchMedia(CSSOMString query);
    [SameObject, Replaceable] readonly attribute Screen screen;
    [SameObject, Replaceable] readonly attribute VisualViewport? visualViewport;

    // browsing context
    undefined moveTo(long x, long y);
    undefined moveBy(long x, long y);
    undefined resizeTo(long width, long height);
    undefined resizeBy(long x, long y);

    // viewport
    [Replaceable] readonly attribute long innerWidth;
    [Replaceable] readonly attribute long innerHeight;

    // viewport scrolling
    [Replaceable] readonly attribute double scrollX;
    [Replaceable] readonly attribute double pageXOffset;
    [Replaceable] readonly attribute double scrollY;
    [Replaceable] readonly attribute double pageYOffset;
    undefined scroll(optional ScrollToOptions options = {});
    undefined scroll(unrestricted double x, unrestricted double y);
    undefined scrollTo(optional ScrollToOptions options = {});
    undefined scrollTo(unrestricted double x, unrestricted double y);
    undefined scrollBy(optional ScrollToOptions options = {});
    undefined scrollBy(unrestricted double x, unrestricted double y);

    // client
    [Replaceable] readonly attribute long screenX;
    [Replaceable] readonly attribute long screenLeft;
    [Replaceable] readonly attribute long screenY;
    [Replaceable] readonly attribute long screenTop;
    [Replaceable] readonly attribute long outerWidth;
    [Replaceable] readonly attribute long outerHeight;
    [Replaceable] readonly attribute double devicePixelRatio;
};

当调用 matchMedia(query) 方法时，必须运行这些步骤：

1. 设 parsed media query list 为解析 query 的结果。
2. 返回一个新的 MediaQueryList 对象，其文档为 this 的关联 Document，其媒体查询列表为 parsed media query list。

测试

• matchMedia-display-none-iframe.html (实时测试) (源码)
• matchMedia.html (实时测试) (源码)

screen 属性必须返回与 Window 对象关联的 Screen 对象。

注：当 Document 导航时，通过 WindowProxy 对象访问 screen 可能会产生不同的结果。

如果关联文档处于完全活动 (fully active)状态，visualViewport 属性必须返回与 Window 对象的关联文档相关联的 VisualViewport 对象。否则，它必须返回 null。

注：VisualViewport 对象仅对文档当前正在呈现的窗口返回且有用。如果保留了对文档当前未呈现的 VisualViewport 的引用，则该 VisualViewport 中的值不得泄露任何有关浏览上下文的信息。

测试

• window-screen-height-immutable.html (实时测试) (源码)
• window-screen-height.html (实时测试) (源码)
• window-screen-width-immutable.html (实时测试) (源码)
• window-screen-width.html (实时测试) (源码)

当调用 moveTo(x, y) 方法时，必须遵循以下步骤：

1. 可选地，返回。

2. 设 target 为 this 的相关全局对象的浏览上下文。

3. 如果 target 不是由脚本（而不是由用户操作）创建的辅助浏览上下文，则返回。

4. 可选地，以用户代理定义的方式限制 x 和 y，使窗口不会移出可用空间。

5. 移动 target 的窗口，使窗口的左上角位于相对于输出设备左上角的坐标 (x, y) 处，以 target 的 CSS 像素为单位。正轴方向为向右和向下。

当调用 moveBy(x, y) 方法时，必须遵循以下步骤：

1. 可选地，返回。

2. 设 target 为 this 的相关全局对象的浏览上下文。

3. 如果 target 不是由脚本（而不是由用户操作）创建的辅助浏览上下文，则返回。

4. 可选地，以用户代理定义的方式限制 x 和 y，使窗口不会移出可用空间。

5. 将 target 的窗口向右移动 x 个 target 的 CSS 像素，向下移动 y 个 target 的 CSS 像素。

当调用 resizeTo(width, height) 方法时，必须遵循以下步骤：

1. 可选地，返回。

2. 设 target 为 this 的相关全局对象的浏览上下文。

3. 如果 target 不是由脚本（而不是由用户操作）创建的辅助浏览上下文，则返回。

4. 可选地，以用户代理定义的方式限制 width 和 height，使窗口不会变得太小或超过可用空间。

5. 通过移动其右侧和底部边缘来调整 target 的窗口大小，使得视口左右边缘之间的距离为 width 个 target 的 CSS 像素，视口顶部和底部边缘之间的距离为 height 个 target 的 CSS 像素。

6. 可选地，以用户代理定义的方式移动 target 的窗口，使其不会增长到可用空间之外。

测试

• resizeTo-negative.html (实时测试) (源码)

当调用 resizeBy(x, y) 方法时，必须遵循以下步骤：

1. 可选地，返回。

2. 设 target 为 this 的相关全局对象的浏览上下文。

3. 如果 target 不是由脚本（而不是由用户操作）创建的辅助浏览上下文，则返回。

4. 可选地，以用户代理定义的方式限制 x 和 y，使窗口不会变得太小或超过可用空间。

5. 通过将右侧边缘向右移动 x 个 target 的 CSS 像素，将底部边缘向下移动 y 个 target 的 CSS 像素来调整 target 的窗口大小。

6. 可选地，以用户代理定义的方式移动 target 的窗口，使其不会增长到可用空间之外。

innerWidth 属性必须返回包含呈现的滚动条（如有）尺寸的视口宽度，如果没有视口，则返回零。

下面的代码片段展示了如何获取视口的宽度：var viewportWidth = innerWidth

innerHeight 属性必须返回包含呈现的滚动条（如有）尺寸的视口高度，如果没有视口，则返回零。

scrollX 属性必须返回相对于初始包含块原点的视口左侧 x 坐标，如果没有视口，则返回零。

pageXOffset 属性必须返回由 scrollX 属性返回的值。

scrollY 属性必须返回相对于初始包含块原点的视口顶部 y 坐标，如果没有视口，则返回零。

pageYOffset 属性必须返回由 scrollY 属性返回的值。

当调用 scroll() 方法时，必须运行这些步骤：

1. 如果使用一个参数调用，请遵循以下子步骤：

   1. 设 options 为该参数。

   2. 设 x 为 options 的 left 字典成员的值（如果存在），否则为视口当前在 x 轴上的滚动位置。

   3. 设 y 为 options 的 top 字典成员的值（如果存在），否则为视口当前在 y 轴上的滚动位置。

2. 如果使用两个参数调用，请遵循以下子步骤：

   1. 设 options 为 null 转换为 ScrollToOptions 字典。[WEBIDL]

   2. 设 x 和 y 分别为这两个参数。

3. 规范化 x 和 y 的非有限值。

4. 如果没有视口，则中止这些步骤。

5. 设 viewport width 为视口的宽度，不包括滚动条的宽度（如有）。

6. 设 viewport height 为视口的高度，不包括滚动条的高度（如有）。

7. 如果视口具有向右的溢出方向：

   设 x 为 max(0, min(x, 视口 滚动区域宽度 - viewport width))。

   如果视口具有向左的溢出方向：

   设 x 为 min(0, max(x, viewport width - 视口 滚动区域宽度))。

8. 如果视口具有向下的溢出方向：

   设 y 为 max(0, min(y, 视口 滚动区域高度 - viewport height))。

   如果视口具有向上的溢出方向：

   设 y 为 min(0, max(y, viewport height - 视口 滚动区域高度))。

9. 设 position 为 视口通过将视口滚动区域的 x 坐标 x 与视口左侧对齐，并将视口滚动区域的 y 坐标 y 与视口顶部对齐所具有的滚动位置。

10. 如果 position 与视口当前滚动位置相同，且视口没有进行中的平滑滚动，则中止这些步骤。

11. 令 document 为 视口关联的 Document。

12. 执行滚动操作，将视口滚动至 position，并以 document 的根元素（如果存在）作为关联元素，否则为 null；滚动行为取自 options 的 behavior 字典成员的值。

    用户代理对于此操作是使用（协调的）视口执行滚动，还是在布局视口的滚动框上使用滚动框执行滚动，尚无共识。

测试

• add-background-attachment-fixed-during-smooth-scroll.html (实时测试) (源码)
• HTMLBody-ScrollArea_quirksmode.html (实时测试) (源码)
• window-scroll-arguments.html (实时测试) (源码)

当 scrollTo() 方法被调用时，用户代理必须表现为调用了带有相同参数的 scroll() 方法。

测试

• background-change-during-smooth-scroll.html (实时测试) (源码)
• scrollTo-zoom.html (实时测试) (源码)

当 scrollBy() 方法被调用时，用户代理必须执行以下步骤

1. 如果使用两个参数调用，请遵循以下子步骤：

   1. 令 options 为 转换为 ScrollToOptions 字典的 null 值。[WEBIDL]

   2. 设 x 和 y 分别为这两个参数。

   3. 令 options 的 left 字典成员的值为 x。

   4. 令 options 的 top 字典成员的值为 y。

2. 规范化 options 中 left 和 top 字典成员的非有限值。

3. 将 scrollX 的值加到 left 字典成员中。

4. 将 scrollY 的值加到 top 字典成员中。

5. 表现为调用了以 options 为唯一参数的 scroll() 方法。

screenX 和 screenLeft 属性必须返回客户端窗口左侧相对于网络公开屏幕区域原点的 x 坐标（以 CSS 像素为单位），如果不存在则返回 0。

测试

• screenLeftTop.html (实时测试) (源码)

screenY 和 screenTop 属性必须返回客户端窗口顶部相对于网络公开屏幕区域的屏幕原点的 y 坐标（以 CSS 像素为单位），如果不存在则返回 0。

outerWidth 属性必须返回客户端窗口的宽度。如果没有客户端窗口，则此属性必须返回 0。

outerHeight 属性必须返回客户端窗口的高度。如果没有客户端窗口，则此属性必须返回 0。

devicePixelRatio 属性必须返回执行以下确定设备像素比算法的结果。

1. 如果没有输出设备，则返回 1 并中止这些步骤。

2. 令 CSS pixel size 为在当前页面缩放下且使用 1.0 的缩放因子时，一个CSS 像素的大小。

3. 令 device pixel size 为输出设备一个设备像素的垂直尺寸。

4. 返回 CSS pixel size 除以 device pixel size 的结果。

4.1. open() 方法的 features 参数

HTML 定义了 open() 方法。本节定义了 features 参数中给出的位置和大小的行为。[HTML]

针对给定映射 tokenizedFeatures 的浏览上下文 target，设置浏览上下文特性

1. 令 x 为 null。

2. 令 y 为 null。

3. 令 width 为 null。

4. 令 height 为 null。

5. 如果 tokenizedFeatures["left"] 存在

   1. 将 x 设置为对 tokenizedFeatures["left"] 调用整数解析规则的结果。

   2. 如果 x 是一个错误，则将 x 设置为 0。

   3. 可选地，以用户代理定义的方式对 x 进行钳制，以使窗口不会移出网络公开可用屏幕区域。

   4. 可选地，移动 target 的窗口，使其左边缘位于相对于网络公开屏幕区域左边缘的水平坐标 x 处，该坐标以 target 的CSS 像素测量。正轴向右。

6. 如果 tokenizedFeatures["top"] 存在

   1. 将 y 设置为对 tokenizedFeatures["top"] 调用整数解析规则的结果。

   2. 如果 y 是一个错误，则将 y 设置为 0。

   3. 可选地，以用户代理定义的方式对 y 进行钳制，以使窗口不会移出网络公开可用屏幕区域。

   4. 可选地，移动 target 的窗口，使其顶部边缘位于相对于网络公开屏幕区域顶部边缘的垂直坐标 y 处，该坐标以 target 的CSS 像素测量。正轴向下。

7. 如果 tokenizedFeatures["width"] 存在

   1. 将 width 设置为对 tokenizedFeatures["width"] 调用整数解析规则的结果。

   2. 如果 width 是一个错误，则将 width 设置为 0。

   3. 如果 width 不为 0

      1. 可选地，以用户代理定义的方式对 width 进行钳制，以使窗口不会变得太小或大于网络公开可用屏幕区域。

      2. 可选地，通过移动其右边缘来调整 target 窗口的大小，使得视口左右边缘之间的距离为 target 的 width 个CSS 像素。

      3. 可选地，以用户代理定义的方式移动 target 的窗口，使其不会增长到网络公开可用屏幕区域之外。

8. 如果 tokenizedFeatures["height"] 存在

   1. 将 height 设置为对 tokenizedFeatures["height"] 调用整数解析规则的结果。

   2. 如果 height 是一个错误，则将 height 设置为 0。

   3. 如果 height 不为 0

      1. 可选地，以用户代理定义的方式对 height 进行钳制，以使窗口不会变得太小或大于网络公开可用屏幕区域。

      2. 可选地，通过移动其底边来调整 target 窗口的大小，使得视口顶部和底部边缘之间的距离为 target 的 height 个CSS 像素。

      3. 可选地，以用户代理定义的方式移动 target 的窗口，使其不会增长到网络公开可用屏幕区域之外。

支持的 open() 特性名称 是以下之一：

width

视口的宽度。

height

视口的高度。

left

窗口的左侧位置。

top

窗口的顶部位置。

4.2. MediaQueryList 接口

本节与 HTML 中定义的事件循环集成。[HTML]

MediaQueryList 对象在创建时拥有一个关联的媒体查询列表和一个关联的文档。

MediaQueryList 对象有一个关联的媒体，它是关联媒体查询列表的序列化形式。

MediaQueryList 对象有一个关联的匹配状态，如果关联的媒体查询列表与文档的状态匹配，则为 true，否则为 false。

当被要求为 Document doc 评估媒体查询并报告更改时，运行以下步骤：

1. 对于每个以 doc 作为其文档的 MediaQueryList 对象 target，按它们创建的顺序（最旧的优先）运行以下子步骤：

   1. 如果 target 的匹配状态自上次运行这些步骤以来已更改，则在 target 上触发一个名为 change 的事件，使用 MediaQueryListEvent，其 isTrusted 属性初始化为 true，其 media 属性初始化为 target 的媒体，其 matches 属性初始化为 target 的匹配状态。

function handleOrientationChange(event) {
    if(event.matches) // landscape
        …
    else
        …
}
var mql = matchMedia("(orientation:landscape)");
mql.onchange = handleOrientationChange;

[Exposed=Window]
interface MediaQueryList : EventTarget {
  readonly attribute CSSOMString media;
  readonly attribute boolean matches;
  undefined addListener(EventListener? callback);
  undefined removeListener(EventListener? callback);
           attribute EventHandler onchange;
};

media 属性必须返回关联的媒体。

matches 属性必须返回关联的匹配状态。

addListener(callback) 方法在被调用时必须运行以下步骤：

1. 添加一个事件监听器，其目标为 this，且为一个事件监听器，其 类型 为 change，且回调为 callback。

removeListener(callback) 方法在被调用时必须运行以下步骤：

1. 如果 this 的事件监听器列表包含一个事件监听器，其 类型 为 change，回调为 callback，且捕获为 false，则移除事件监听器，目标为 this，并移除该事件监听器。

注意：本规范最初有一种自定义回调机制，使用 addListener() 和 removeListener()，并以关联的媒体查询列表作为参数调用回调。现在改用常规的事件机制。为了向后兼容，addListener() 和 removeListener() 方法基本上分别别名为 addEventListener() 和 removeEventListener()，且 change 事件假装为一个 MediaQueryList。

以下是所有实现 MediaQueryList 接口的对象必须支持的事件处理器（及其对应的事件处理器事件类型），作为事件处理器 IDL 属性。

[Exposed=Window]
interface MediaQueryListEvent : Event {
  constructor(CSSOMString type, optional MediaQueryListEventInit eventInitDict = {});
  readonly attribute CSSOMString media;
  readonly attribute boolean matches;
};

dictionary MediaQueryListEventInit : EventInit {
  CSSOMString media = "";
  boolean matches = false;
};

media 属性必须返回它被初始化为的值。

matches 属性必须返回它被初始化为的值。

4.2.1. 事件摘要

本节是非规范性的。

4.3. Screen 接口

顾名思义，Screen 接口代表有关输出设备屏幕的信息。

[Exposed=Window]
interface Screen {
  readonly attribute long availWidth;
  readonly attribute long availHeight;
  readonly attribute long width;
  readonly attribute long height;
  readonly attribute unsigned long colorDepth;
  readonly attribute unsigned long pixelDepth;
};

availWidth 属性必须返回网络公开可用屏幕区域的宽度。

availHeight 属性必须返回网络公开可用屏幕区域的高度。

width 属性必须返回网络公开屏幕区域的宽度。

height 属性必须返回网络公开屏幕区域的高度。

colorDepth 和 pixelDepth 属性应返回为输出设备中的像素分配的颜色位数，不包括 alpha 通道。如果用户代理无法返回输出设备使用的位数，则应返回最接近的估计值，例如，发送到显示器的帧缓冲使用的位数或任何最接近输出设备将使用的值的内部表示。用户代理对于这些属性返回的值必须至少等于color媒体特性值乘以 3。如果不同的颜色分量不是用相同数量的位数表示的，则返回值可能大于color媒体特性值的 3 倍。如果用户代理不知道色深或者出于隐私考虑不想返回该值，则应返回 24。

注意：出于兼容性原因，colorDepth 和 pixelDepth 属性返回相同的值。

注意：已知一些不符合规范的实现返回 32 而不是 24。

5. Document 接口的扩展

partial interface Document {
  Element? elementFromPoint(double x, double y);
  sequence<Element> elementsFromPoint(double x, double y);
  CaretPosition? caretPositionFromPoint(double x, double y, optional CaretPositionFromPointOptions options = {});
  readonly attribute Element? scrollingElement;
};

dictionary CaretPositionFromPointOptions {
  sequence<ShadowRoot> shadowRoots = [];
};

elementFromPoint(x, y) 方法必须遵循以下步骤：

1. 如果任一参数为负，x 大于视口宽度减去渲染滚动条的大小（如果有），y 大于视口高度减去渲染滚动条的大小（如果有），或者没有与文档关联的视口，则返回 null 并终止这些步骤。

2. 如果视口中存在一个盒子，在应用适用于视口后代的变换时，该盒子在坐标 x,y 处是点击测试的目标，则返回关联的元素并终止这些步骤。

3. 如果文档有根元素，则返回根元素并终止这些步骤。

4. 返回 null。

注意：elementFromPoint() 方法不一定返回最顶层的绘制元素。例如，可以使用 pointer-events CSS 属性将元素排除在点击测试目标之外。

elementsFromPoint(x, y) 方法必须遵循以下步骤：

1. 令 sequence 为一个新的空序列。

2. 如果任一参数为负，x 大于视口宽度减去渲染滚动条的大小（如果有），y 大于视口高度减去渲染滚动条的大小（如果有），或者没有与文档关联的视口，则返回 sequence 并终止这些步骤。

3. 对于视口中的每个盒子，按绘制顺序（从最顶层的盒子开始），在应用适用于视口后代的变换时，即使没有东西会重叠它，只要该盒子在坐标 x,y 处是点击测试的目标，就将其关联元素追加到 sequence 中。

4. 如果文档有根元素，并且 sequence 中的最后一项不是根元素，则将根元素追加到 sequence 中。

5. 返回 sequence。

caretPositionFromPoint(x, y, options) 方法必须返回运行以下步骤的结果：

1. 如果没有与文档关联的视口，则返回 null。

2. 如果任一参数为负，x 大于视口宽度减去渲染滚动条的大小（如果有），y 大于视口高度减去渲染滚动条的大小（如果有），则返回 null。

3. 如果视口坐标 x,y 处在应用适用于视口后代的变换时，不会插入任何文本插入点指示符，则返回 null。

4. 如果视口坐标 x,y 处在应用适用于视口后代的变换时，文本插入点指示符会在一个同时也是被替换元素的文本输入小部件中插入，则返回一个插入符号位置，并设置其属性如下：

   插入符号节点

   对应文本输入小部件的节点。

   插入符号偏移量

   文本插入点指示符插入位置左侧的 16 位单元数量。

5. 否则

   1. 令 caretPosition 为一个元组，由 caretPositionNode（一个节点）和 caretPositionOffset（一个非负整数）组成，用于表示在应用适用于视口后代的变换时，文本插入点指示符应插入的位置。

   2. 令 startNode 为 caretPosition 的 caretPositionNode，令 startOffset 为 caretPosition 的 caretPositionOffset。

   3. 当 startNode 是一个节点，startNode 的根是一个影子根，且 startNode 的根不是 options["shadowRoots"] 中任何一项的包含影子根的包含祖先时，重复执行这些步骤：

      1. 将 startOffset 设置为 startNode 的根的宿主的索引。

      2. 将 startNode 设置为 startNode 的根的宿主的父节点。

   4. 返回一个插入符号位置，并设置其属性如下：

      1. 插入符号节点设置为 startNode。

      2. 插入符号偏移量设置为 startOffset。

注意：此插入符号位置不是实时的。

注意：点击测试的具体细节超出了本规范的范围，因此 elementFromPoint() 和 caretPositionFromPoint() 的确切细节也超出范围。点击测试有望在 CSS 或 HTML 的未来版本中定义。

Document 接口上的 scrollingElement 属性在获取时必须运行以下步骤：

1. 如果 Document 处于怪异模式，则遵循以下子步骤：

   1. 如果body 元素存在，且它不是潜在可滚动的，则返回body 元素并中止这些步骤。

      为此，body 元素的父元素上的 overflow:clip 值必须被视为 overflow:hidden。

   2. 返回 null 并中止这些步骤。

2. 如果存在根元素，则返回根元素并中止这些步骤。

3. 返回 null。

注意：对于始终对 scrollTop 和 scrollLeft 使用怪异模式行为的不符合规范的用户代理，scrollingElement 属性预计也应始终返回body 元素（如果不存在则返回 null）。此 API 的存在是为了让 Web 开发人员可以使用它来获取用于滚动 API 的正确元素，而无需对特定用户代理的行为做出假设，也不必为了确定哪个元素滚动视口而触发滚动。

注意：body 元素与 HTML 的 document.body 不同，后者可以返回 frameset 元素。

5.1. CaretPosition 接口

插入符号位置给出了文本插入点指示符的位置。它总是拥有一个关联的插入符号节点和插入符号偏移量。它由 CaretPosition 对象表示。

[Exposed=Window]
interface CaretPosition {
  readonly attribute Node offsetNode;
  readonly attribute unsigned long offset;
  [NewObject] DOMRect? getClientRect();
};

offsetNode 属性必须返回插入符号节点。

offset 属性必须返回插入符号偏移量。

getClientRect() 方法必须遵循以下步骤，在第一个返回值的步骤中止：

1. 如果插入符号节点是一个被替换元素的文本输入小部件，并且该部件在文档中，则返回一个由插入符号偏移量值表示的、该部件中插入符号的缩放 DOMRect 对象。将适用于该元素及其祖先的变换应用上去。

2. 否则

   1. 令 caretRange 为一个折叠的 Range 对象，其开始节点和结束节点被设置为插入符号节点，且其开始偏移量和结束偏移量被设置为插入符号偏移量。

   2. 返回在 caretRange 上调用 getBoundingClientRect() 方法所得到的 DOMRect 对象。

注意：此 DOMRect 对象不是实时的。

6. Element 接口的扩展

enum ScrollLogicalPosition { "start", "center", "end", "nearest" };
dictionary ScrollIntoViewOptions : ScrollOptions {
  ScrollLogicalPosition block = "start";
  ScrollLogicalPosition inline = "nearest";
  ScrollIntoViewContainer container = "all";
};

enum ScrollIntoViewContainer { "all", "nearest" };

dictionary CheckVisibilityOptions {
    boolean checkOpacity = false;
    boolean checkVisibilityCSS = false;
    boolean contentVisibilityAuto = false;
    boolean opacityProperty = false;
    boolean visibilityProperty = false;
};

partial interface Element {
  DOMRectList getClientRects();
  [NewObject] DOMRect getBoundingClientRect();

  boolean checkVisibility(optional CheckVisibilityOptions options = {});

  undefined scrollIntoView(optional (boolean or ScrollIntoViewOptions) arg = {});
  undefined scroll(optional ScrollToOptions options = {});
  undefined scroll(unrestricted double x, unrestricted double y);
  undefined scrollTo(optional ScrollToOptions options = {});
  undefined scrollTo(unrestricted double x, unrestricted double y);
  undefined scrollBy(optional ScrollToOptions options = {});
  undefined scrollBy(unrestricted double x, unrestricted double y);
  attribute unrestricted double scrollTop;
  attribute unrestricted double scrollLeft;
  readonly attribute long scrollWidth;
  readonly attribute long scrollHeight;
  readonly attribute long clientTop;
  readonly attribute long clientLeft;
  readonly attribute long clientWidth;
  readonly attribute long clientHeight;
  readonly attribute double currentCSSZoom;
};

注意：checkOpacity 和 checkVisibilityCSS 属性是历史名称。这些属性具有符合新命名方案的别名，即 opacityProperty 和 visibilityProperty。

getClientRects() 方法在被调用时，必须返回以下算法的结果：

1. 如果调用该方法的元素没有关联的盒子，则返回一个空的 DOMRectList 对象并停止此算法。

2. 如果该元素拥有一个关联的 SVG 布局盒子，则返回一个缩放的 DOMRectList 对象，其中包含一个描述 SVG 规范定义的元素边框盒子的 DOMRect 对象，并应用适用于该元素及其祖先的变换。

3. 返回一个 DOMRectList 对象，按内容顺序包含为每个盒子片段准备的 DOMRect 对象，描述其边框区域（包括高度或宽度为零的区域），并带有以下约束：

   • 应用适用于该元素及其祖先的变换。

   • 如果调用该方法的元素的 display 属性计算值为 table 或 inline-table，则包含表格盒子和标题盒子（如果有），但不包含匿名容器盒子。

   • 用其子盒子替换每个匿名块盒子，并重复此过程直到最终列表中不再有匿名块盒子。

注意：getClientRects() 返回的 DOMRect 对象不是实时的。

getBoundingClientRect() 方法在对元素 element 调用时，必须返回获取边框盒 element 的结果。

注意：getBoundingClientRect() 返回的 DOMRect 对象不是实时的。

var example = document.getElementsByTagName("div")[0].getBoundingClientRect();
var exampleWidth = example.width;
var exampleHeight = example.height;

当 scrollIntoView(arg) 方法被调用时，必须执行以下步骤

1. 令 behavior 为 "auto"。

2. 令 block 为 "start"。

3. 令 inline 为 "nearest"。

4. 令 container 为 null。

5. 如果 arg 是一个 ScrollIntoViewOptions 字典，那么

   1. 将 behavior 设置为 options 的 behavior 字典成员。

   2. 将 block 设置为 options 的 block 字典成员。

   3. 将 inline 设置为 options 的 inline 字典成员。

   4. 如果 options 的 container 字典成员为 "nearest"，则将 container 设置为该元素。

6. 否则，如果 arg 为 false，则将 block 设置为 "end"。

7. 如果该元素没有关联的盒模型，或者对于用户代理功能不可用，则返回。

8. 以 behavior、block、inline 和 container 将该元素滚动到视图中。

9. 可选地执行某些其他引起用户注意该元素的操作。

<style>
    .scroller { overflow: auto; scroll-padding: 8px; }
    .slide { scroll-margin: 16px; scroll-snap-align: center; }
</style>
<div class="carousel">
    <div class="slides scroller">
        <div id="s1" class="slide">
        <div id="s2" class="slide">
        <div id="s3" class="slide">
    </div>
    <div class="markers">
        <button data-target="s1">1</button>
        <button data-target="s2">2</button>
        <button data-target="s3">3</button>
    </div>
</div>
<script>
    document.querySelector('.markers').addEventListener('click', (evt) => {
        const target = document.getElementById(evt.target.dataset.target);
        if (!target) return;
        // scrollIntoView correctly aligns target item respecting scroll-snap-align,
        // scroll-margin, and the scroll container’s scroll-padding.
        target.scrollIntoView({
            // Only scroll the nearest scroll container.
            container: 'nearest',
            behavior: 'smooth'
        });
    });
</script>

当 scroll() 方法被调用时，必须执行以下步骤

1. 如果使用一个参数调用，请遵循以下子步骤：

   1. 设 options 为该参数。

   2. 如果存在，归一化 left 和 top 字典成员的非有限值。

   3. 令 x 为 left 字典成员的值（如果存在），否则为该元素在 x 轴上的当前滚动位置。

   4. 令 y 为 top 字典成员的值（如果存在），否则为该元素在 y 轴上的当前滚动位置。

2. 如果使用两个参数调用，请遵循以下子步骤：

   1. 将 options 设为 null，并转换为 ScrollToOptions 字典。[WEBIDL]

   2. 设 x 和 y 分别为这两个参数。

   3. 归一化 x 和 y 的非有限值。

   4. 将 options 的 left 字典成员设为值 x。

   5. 将 options 的 top 字典成员设为值 y。

3. 令 document 为该元素的节点文档。

4. 如果 document 不是活动文档，则终止这些步骤。

5. 令 window 为 document 的 defaultView 属性值。

6. 如果 window 为 null，则终止这些步骤。

7. 如果该元素是根元素且 document 处于怪异模式，则终止这些步骤。

8. 如果该元素是根元素，则在 window 上调用 scroll()，以 window 上的 scrollX 作为第一个参数，以 y 作为第二个参数，并终止这些步骤。

9. 如果该元素是body 元素，document 处于怪异模式，且该元素不是潜在可滚动的，则在 window 上调用 scroll()，以 options 作为唯一参数，并终止这些步骤。

10. 如果该元素没有关联的盒模型，或者该元素没有关联的滚动盒模型，或该元素没有溢出，则终止这些步骤。

11. 滚动该元素至 x,y，滚动行为为 options 的 behavior 字典成员的值。

当 scrollTo() 方法被调用时，用户代理必须表现得如同 scroll() 方法以相同的参数被调用一样。

当 scrollBy() 方法被调用时，用户代理必须执行以下步骤

1. 如果使用一个参数调用，请遵循以下子步骤：

   1. 设 options 为该参数。

   2. 如果存在，归一化 left 和 top 字典成员的非有限值。

2. 如果使用两个参数调用，请遵循以下子步骤：

   1. 将 options 设为 null，并转换为 ScrollToOptions 字典。[WEBIDL]

   2. 设 x 和 y 分别为这两个参数。

   3. 归一化 x 和 y 的非有限值。

   4. 将 options 的 left 字典成员设为值 x。

   5. 将 options 的 top 字典成员设为值 y。

3. 将 scrollLeft 的值加到 left 字典成员中。

4. 将 scrollTop 的值加到 top 字典成员中。

5. 表现得如同 scroll() 方法以 options 作为唯一参数被调用一样。

当获取 scrollTop 属性时，必须返回运行以下步骤的结果

1. 令 document 为该元素的节点文档。

2. 如果 document 不是活动文档，则返回 0 并终止这些步骤。

3. 令 window 为 document 的 defaultView 属性值。

4. 如果 window 为 null，则返回 0 并终止这些步骤。

5. 如果该元素是根元素且 document 处于怪异模式，则返回 0 并终止这些步骤。

6. 如果该元素是根元素，则返回 window 上 scrollY 的值。

7. 如果该元素是body 元素，document 处于怪异模式，且该元素不是潜在可滚动的，则返回 window 上 scrollY 的值。

8. 如果该元素没有关联的盒模型，则返回 0 并终止这些步骤。

9. 返回滚动区域与该元素内边距边缘顶部对齐点的 y 坐标。

当设置 scrollTop 属性时，必须执行以下步骤

1. 令 y 为给定值。

2. 归一化 y 的非有限值。

3. 令 document 为该元素的节点文档。

4. 如果 document 不是活动文档，则终止这些步骤。

5. 令 window 为 document 的 defaultView 属性值。

6. 如果 window 为 null，则终止这些步骤。

7. 如果该元素是根元素且 document 处于怪异模式，则终止这些步骤。

8. 如果该元素是根元素，则在 window 上调用 scroll()，以 window 上的 scrollX 作为第一个参数，以 y 作为第二个参数，并终止这些步骤。

9. 如果该元素是body 元素，document 处于怪异模式，且该元素不是潜在可滚动的，则在 window 上调用 scroll()，以 window 上的 scrollX 作为第一个参数，以 y 作为第二个参数，并终止这些步骤。

10. 如果该元素没有关联的盒模型，该元素没有关联的滚动盒模型，或该元素没有溢出，则终止这些步骤。

11. 滚动该元素至 scrollLeft,y，滚动行为为 "auto"。

当获取 scrollLeft 属性时，必须返回运行以下步骤的结果

1. 令 document 为该元素的节点文档。

2. 如果 document 不是活动文档，则返回 0 并终止这些步骤。

3. 令 window 为 document 的 defaultView 属性值。

4. 如果 window 为 null，则返回 0 并终止这些步骤。

5. 如果该元素是根元素且 document 处于怪异模式，则返回 0 并终止这些步骤。

6. 如果该元素是根元素，则返回 window 上 scrollX 的值。

7. 如果该元素是body 元素，document 处于怪异模式，且该元素不是潜在可滚动的，则返回 window 上 scrollX 的值。

8. 如果该元素没有关联的盒模型，则返回 0 并终止这些步骤。

9. 返回滚动区域与该元素内边距边缘左侧对齐点的 x 坐标。

当设置 scrollLeft 属性时，必须执行以下步骤

1. 令 x 为给定值。

2. 归一化 x 的非有限值。

3. 令 document 为该元素的节点文档。

4. 如果 document 不是活动文档，则终止这些步骤。

5. 令 window 为 document 的 defaultView 属性值。

6. 如果 window 为 null，则终止这些步骤。

7. 如果该元素是根元素且 document 处于怪异模式，则终止这些步骤。

8. 如果该元素是根元素，则在 window 上调用 scroll()，以 x 作为第一个参数，以 window 上的 scrollY 作为第二个参数，并终止这些步骤。

9. 如果该元素是body 元素，document 处于怪异模式，且该元素不是潜在可滚动的，则在 window 上调用 scroll()，以 x 作为第一个参数，以 window 上的 scrollY 作为第二个参数，并终止这些步骤。

10. 如果该元素没有关联的盒模型，该元素没有关联的滚动盒模型，或该元素没有溢出，则终止这些步骤。

11. 滚动该元素至 x,scrollTop，滚动行为为 "auto"。

当获取 scrollWidth 属性时，必须返回运行以下步骤的结果

1. 令 document 为该元素的节点文档。

2. 如果 document 不是活动文档，则返回 0 并终止这些步骤。

3. 令 视口宽度 为视口的宽度，不包含滚动条宽度（如果有），或者如果不存在视口，则为 0。

4. 如果该元素是根元素且 document 不处于怪异模式，则返回 max(视口 滚动区域宽度, 视口宽度)。

5. 如果该元素是body 元素，document 处于怪异模式，且该元素不是潜在可滚动的，则返回 max(视口 滚动区域宽度, 视口宽度)。

6. 如果该元素没有关联的盒模型，则返回 0 并终止这些步骤。

7. 返回该元素滚动区域的宽度。

当获取 scrollHeight 属性时，必须返回运行以下步骤的结果

1. 令 document 为该元素的节点文档。

2. 如果 document 不是活动文档，则返回 0 并终止这些步骤。

3. 令 视口高度 为视口的高度，不包含滚动条高度（如果有），或者如果不存在视口，则为 0。

4. 如果该元素是根元素且 document 不处于怪异模式，则返回 max(视口 滚动区域高度, 视口高度)。

5. 如果该元素是body 元素，document 处于怪异模式，且该元素不是潜在可滚动的，则返回 max(视口 滚动区域高度, 视口高度)。

6. 如果该元素没有关联的盒模型，则返回 0 并终止这些步骤。

7. 返回该元素滚动区域的高度。

当获取 clientTop 属性时，必须执行以下步骤

1. 如果该元素没有关联的盒模型，或者盒模型是内联的，则返回 0。

2. 返回未缩放的 border-top-width 属性的计算值，加上在顶部内边距边缘与顶部边框边缘之间渲染的任何滚动条高度，同时忽略应用于该元素及其祖先的任何变换。

当获取 clientLeft 属性时，必须执行以下步骤

1. 如果该元素没有关联的盒模型，或者盒模型是内联的，则返回 0。

2. 返回未缩放的 border-left-width 属性的计算值，加上在左侧内边距边缘与左侧边框边缘之间渲染的任何滚动条宽度，同时忽略应用于该元素及其祖先的任何变换。

当获取 clientWidth 属性时，必须执行以下步骤

1. 如果该元素没有关联的盒模型，或者盒模型是内联的，则返回 0。

2. 如果该元素是根元素且该元素的节点文档不处于怪异模式，或者该元素是body 元素且该元素的节点文档确实处于怪异模式，则返回视口宽度（排除渲染的滚动条大小，如果有）。

3. 返回未缩放的内边距边缘宽度，排除在内边距边缘和边框边缘之间渲染的任何滚动条宽度，同时忽略应用于该元素及其祖先的任何变换。

当获取 clientHeight 属性时，必须执行以下步骤

1. 如果该元素没有关联的盒模型，或者盒模型是内联的，则返回 0。

2. 如果该元素是根元素且该元素的节点文档不处于怪异模式，或者该元素是body 元素且该元素的节点文档确实处于怪异模式，则返回视口高度（排除渲染的滚动条大小，如果有）。

3. 返回未缩放的内边距边缘高度，排除在内边距边缘和边框边缘之间渲染的任何滚动条高度，同时忽略应用于该元素及其祖先的任何变换。

当获取 currentCSSZoom 属性时，必须返回该元素的有效缩放比例；如果该元素未被渲染，则返回 1.0。

6.1. Element 滚动成员

7. HTMLElement 接口扩展

partial interface HTMLElement {
  readonly attribute Element? scrollParent;
  readonly attribute Element? offsetParent;
  readonly attribute long offsetTop;
  readonly attribute long offsetLeft;
  readonly attribute long offsetWidth;
  readonly attribute long offsetHeight;
};

当获取 scrollParent 属性时，必须返回运行以下步骤的结果

1. 如果以下任意条件为真，则返回 null 并终止此算法

   • 该元素没有关联的盒模型。

   • 该元素是根元素。

   • 该元素是body 元素。

   • 该元素的 position 属性的计算值为 fixed，且没有祖先建立固定定位包含块。

2. 令 ancestor 为该元素在扁平树中的包含块，并重复这些子步骤

   1. 如果 ancestor 是初始包含块，若该元素的文档的 scrollingElement 对该元素而言不是封闭阴影隐藏的，则返回该元素文档的 scrollingElement，否则返回 null。

   2. 如果 ancestor 对该元素而言不是封闭阴影隐藏的，且是一个滚动容器，则终止此算法并返回 ancestor。

   3. 如果 ancestor 的 position 属性的计算值为 fixed，且没有任何祖先元素建立固定定位的 包含块（containing block），则终止此算法并返回 null。

   4. 令 ancestor 为 ancestor 在 平铺树（flat tree） 中的 包含块。

offsetParent 属性必须返回运行这些步骤的结果。

1. 如果满足以下任一条件，则返回 null 并终止此算法：

   • 该元素没有关联的 盒子（box）。

   • 该元素是 根元素。

   • 该元素是 body 元素。

   • 该元素的 position 属性计算值为 fixed，且没有任何祖先元素建立固定定位的 包含块。

2. 令 ancestor 为该元素在 平铺树 中的父级，并重复这些子步骤：

   1. 如果 ancestor 对于该元素来说是 闭合阴影隐藏（closed-shadow-hidden） 的，且其 position 属性计算值为 fixed，且没有任何祖先元素建立固定定位的 包含块，则终止此算法并返回 null。

   2. 如果 ancestor 对于该元素来说不是 闭合阴影隐藏 的，并且满足以下至少一项条件，则终止此算法并返回 ancestor：

      • 该元素位于固定定位的 包含块 中，且 ancestor 是固定定位后代元素的包含块。

      • 该元素不在固定定位的 包含块 中，并且：

        • ancestor 是绝对定位后代元素的包含块（无论是否存在任何绝对定位的后代）。

        • 它是 body 元素。

        • 该元素的 position 属性计算值为 static，且该祖先元素是以下 HTML 元素 之一：td、th 或 table。

      • 该元素具有与 ancestor 不同的 有效缩放（effective zoom）。

   3. 如果 ancestor 在 平铺树 中没有更多父级，则终止此算法并返回 null。

   4. 令 ancestor 为 ancestor 在 平铺树 中的父级。

offsetTop 属性必须返回运行这些步骤的结果。

1. 如果该元素是 body 元素 或没有任何关联的 盒子，则返回 0 并终止此算法。

2. 如果该元素的 offsetParent 为 null，则返回该元素关联的第一个 盒子 的顶部 边框边缘（border edge） 相对于 初始包含块 原点的 未缩放 y 坐标，忽略应用于该元素及其祖先的任何 变换（transforms），并终止此算法。

3. 返回该元素关联的第一个 盒子 的顶部 边框边缘 y 坐标，减去该元素的 offsetParent 关联的第一个 盒子 的顶部 内边距边缘（padding edge） y 坐标的 未缩放 结果（相对于 初始包含块 原点），忽略应用于该元素及其祖先的任何 变换。

   注意：由多个行框组成的行内元素，只会考虑其第一个 盒子。

offsetLeft 属性必须返回运行这些步骤的结果。

1. 如果该元素是 body 元素 或没有任何关联的 盒子，则返回 0 并终止此算法。

2. 如果该元素的 offsetParent 为 null，则返回该元素关联的第一个 盒子 的左侧 边框边缘 相对于 初始包含块 原点的 未缩放 x 坐标，忽略应用于该元素及其祖先的任何 变换，并终止此算法。

3. 返回该元素关联的第一个 盒子 的左侧 边框边缘 x 坐标，减去该元素的 offsetParent 关联的第一个 盒子 的左侧 内边距边缘 x 坐标的 未缩放 结果（相对于 初始包含块 原点），忽略应用于该元素及其祖先的任何 变换。

offsetWidth 属性必须返回运行这些步骤的结果。

1. 如果该元素没有任何关联的 盒子，则返回 0 并终止此算法。

2. 返回该元素 主体盒子（principal box） 生成的所有片段的 边框盒子（border boxes） 的轴对齐外接矩形的 未缩放 宽度，忽略应用于该元素及其祖先的任何 变换。

   如果该元素的 主体盒子 是被 块级（block-level） 后代“分割”的 行内级盒子，则还应包含该 块级 后代生成的片段，除非它们的宽度或高度为零。

offsetHeight 属性必须返回运行这些步骤的结果。

1. 如果该元素没有任何关联的 盒子，则返回 0 并终止此算法。

2. 返回该元素 主体盒子 生成的所有片段的 边框盒子 的轴对齐外接矩形的 未缩放 高度，忽略应用于该元素及其祖先的任何 变换。

   如果该元素的 主体盒子 是被 块级 后代“分割”的 行内级盒子，则还应包含该 块级 后代生成的片段，除非它们的宽度或高度为零。

8. HTMLImageElement 接口的扩展

partial interface HTMLImageElement {
  readonly attribute long x;
  readonly attribute long y;
};

x 属性在获取时，必须返回该元素关联的第一个 盒子 的左侧 边框边缘 相对于 初始包含块 原点的 已缩放 x 坐标，忽略应用于该元素及其祖先的任何 变换；如果没有 盒子，则返回 0。

y 属性在获取时，必须返回该元素关联的第一个 盒子 的顶部 边框边缘 相对于 初始包含块 原点的 已缩放 y 坐标，忽略应用于该元素及其祖先的任何 变换；如果没有 盒子，则返回 0。

9. Range 接口的扩展

partial interface Range {
  DOMRectList getClientRects();
  [NewObject] DOMRect getBoundingClientRect();
};

getClientRects() 方法在调用时，如果该范围不在文档中，则必须返回一个空的 DOMRectList 对象，否则返回一个 DOMRectList 对象，其中包含按内容顺序排列并符合以下约束的 DOMRect 对象列表：

• 对于范围选择的每个元素，如果其父级未被该范围选择，则包含通过在该元素上调用 getClientRects() 所返回的边框区域。

• 对于被范围选择或部分选择的每个 Text 节点（包括边界点相同的情况），包含一个 已缩放 的 DOMRect 对象（针对选择的部分，而非整个行框）。这些 DOMRect 对象的边界是使用字体指标计算的；因此，对于水平书写，每个盒子的垂直维度由字体上升（ascent）和下降（descent）确定，水平维度由文本推进宽度确定。如果范围覆盖了部分 排版字符单元（typographic character unit）（例如，代理对的一半或字位簇的一部分），则为了计算相关 DOMRect 的边界，必须包含完整的 排版字符单元。 [CSS-TEXT-3] 祖先元素应用的 变换 将被应用。

注意：由 getClientRects() 返回的 DOMRect 对象不是 实时的（live）。

getBoundingClientRect() 方法在调用时，必须返回以下算法的结果。

1. 令 list 为在该方法被调用的同一范围上调用 getClientRects() 的结果。

2. 如果 list 为空，则返回一个 DOMRect 对象，其 x、y、width 和 height 成员均为 0。

3. 如果 list 中的所有矩形宽度或高度均为 0，则返回 list 中的第一个矩形。

4. 否则，返回一个 DOMRect 对象，描述包含 list 中所有高度或宽度不为 0 的矩形的最小矩形。

注意：由 getBoundingClientRect() 返回的 DOMRect 对象不是 实时的。

10. MouseEvent 接口的扩展

对象 IDL 片段重定义了一些成员。我们能以某种方式解决这个问题吗？

partial interface MouseEvent {
  readonly attribute double screenX;
  readonly attribute double screenY;
  readonly attribute double pageX;
  readonly attribute double pageY;
  readonly attribute double clientX;
  readonly attribute double clientY;
  readonly attribute double x;
  readonly attribute double y;
  readonly attribute double offsetX;
  readonly attribute double offsetY;
};

partial dictionary MouseEventInit {
  double screenX = 0.0;
  double screenY = 0.0;
  double clientX = 0.0;
  double clientY = 0.0;
};

screenX 属性必须返回事件发生位置相对于 Web 公开屏幕区域 原点的 x 坐标。

screenY 属性必须返回事件发生位置相对于 Web 公开屏幕区域 原点的 y 坐标。

pageX 属性必须遵循以下步骤：

1. 如果事件的 分发标志（dispatch flag） 已设置，则返回事件发生位置相对于 初始包含块 原点的水平坐标，并终止这些步骤。

2. 令 offset 为事件关联的 Window 对象的 scrollX 属性值（如果有），否则为 0。

3. 返回 offset 与事件 clientX 属性值的总和。

pageY 属性必须遵循以下步骤：

1. 如果事件的 分发标志 已设置，则返回事件发生位置相对于 初始包含块 原点的垂直坐标，并终止这些步骤。

2. 令 offset 为事件关联的 Window 对象的 scrollY 属性值（如果有），否则为 0。

3. 返回 offset 与事件 clientY 属性值的总和。

clientX 属性必须返回事件发生位置相对于 视口（viewport） 原点的 x 坐标。

clientY 属性必须返回事件发生位置相对于 视口 原点的 y 坐标。

x 属性必须返回 clientX 的值。

y 属性必须返回 clientY 的值。

offsetX 属性必须遵循以下步骤：

1. 如果事件的 分发标志 已设置，则返回事件发生位置相对于目标节点 内边距边缘 原点的 x 坐标，忽略应用于该元素及其祖先的 变换，并终止这些步骤。

2. 返回事件 pageX 属性的值。

offsetY 属性必须遵循以下步骤：

1. 如果事件的 分发标志 已设置，则返回事件发生位置相对于目标节点 内边距边缘 原点的 y 坐标，忽略应用于该元素及其祖先的 变换，并终止这些步骤。

2. 返回事件 pageY 属性的值。

11. 几何

11.1. GeometryUtils 接口

enum CSSBoxType { "margin", "border", "padding", "content" };
dictionary BoxQuadOptions {
  CSSBoxType box = "border";
  GeometryNode relativeTo; // XXX default document (i.e. viewport)
};

dictionary ConvertCoordinateOptions {
  CSSBoxType fromBox = "border";
  CSSBoxType toBox = "border";
};

interface mixin GeometryUtils {
  sequence<DOMQuad> getBoxQuads(optional BoxQuadOptions options = {});
  DOMQuad convertQuadFromNode(DOMQuadInit quad, GeometryNode from, optional ConvertCoordinateOptions options = {});
  DOMQuad convertRectFromNode(DOMRectReadOnly rect, GeometryNode from, optional ConvertCoordinateOptions options = {});
  DOMPoint convertPointFromNode(DOMPointInit point, GeometryNode from, optional ConvertCoordinateOptions options = {}); // XXX z,w turns into 0
};

Text includes GeometryUtils; // like Range
Element includes GeometryUtils;
CSSPseudoElement includes GeometryUtils;
Document includes GeometryUtils;

typedef (Text or Element or CSSPseudoElement or Document) GeometryNode;

getBoxQuads(options) 方法必须运行以下步骤：

1. DOM 顺序

   p1 = 左上角，即使在 RTL 中也是如此

   缩放为 0 表示除以零，返回 0x0

   不允许跨框架，抛出 WrongDocumentError？

   点被平坦化（3D 变换），z=0，类似于 getClientRect

   测试块级元素在行内元素中

   伪元素 before/after 是元素的子级

   视口盒子都是一样的

convertQuadFromNode(quad, from, options) 方法必须运行以下步骤：

1. ...

convertRectFromNode(rect, from, options) 方法必须运行以下步骤：

1. ...

convertPointFromNode(point, from, options) 方法必须运行以下步骤：

1. ...

12. VisualViewport

12.1. VisualViewport 接口

[Exposed=Window]
interface VisualViewport : EventTarget {
  readonly attribute double offsetLeft;
  readonly attribute double offsetTop;

  readonly attribute double pageLeft;
  readonly attribute double pageTop;

  readonly attribute double width;
  readonly attribute double height;

  readonly attribute double scale;

  attribute EventHandler onresize;
  attribute EventHandler onscroll;
  attribute EventHandler onscrollend;
};

offsetLeft 属性必须运行这些步骤：

1. 如果 视觉视口（visual viewport） 的 关联文档 不是 完全活动（fully active） 的，则返回 0。

2. 否则，返回 视觉视口 左边缘相对于 布局视口（layout viewport） 左边缘的偏移量。

offsetTop 属性必须运行这些步骤：

1. 如果 视觉视口 的 关联文档 不是 完全活动 的，则返回 0。

2. 否则，返回 视觉视口 顶边缘相对于 布局视口 顶边缘的偏移量。

pageLeft 属性必须运行这些步骤：

1. 如果 视觉视口 的 关联文档 不是 完全活动 的，则返回 0。

2. 否则，返回 视觉视口 左边缘相对于 布局视口 的 文档 的 初始包含块 左边缘的偏移量。

pageTop 属性必须运行这些步骤：

1. 如果 视觉视口 的 关联文档 不是 完全活动 的，则返回 0。

2. 否则，返回 视觉视口 顶边缘相对于 布局视口 的 文档 的 初始包含块 顶边缘的偏移量。

width 属性必须运行这些步骤：

1. 如果 视觉视口 的 关联文档 不是 完全活动 的，则返回 0。

2. 否则，返回 视觉视口 的宽度，减去任何固定在视觉视口上的已渲染垂直 经典滚动条（classic scrollbar） 的宽度。

注意：由于此值是以 CSS 像素返回的，因此如果增加 页面缩放（page zoom） 或 缩放因子（scale factor），该值的大小将会减小。

注意：固定在视觉视口上的滚动条是指在缩放和平移视觉视口时不会改变大小或位置的滚动条。由于此值是以 CSS 像素为单位的，因此在排除滚动条宽度时，UA 必须考虑滚动条在 CSS 像素中的大小。也就是说，当放大时，排除的数量会减少；当缩小时，排除的数量会增加。

height 属性必须运行这些步骤：

1. 如果 视觉视口 的 关联文档 不是 完全活动 的，则返回 0。

2. 否则，返回 视觉视口 的高度，减去任何固定在视觉视口上的已渲染水平 经典滚动条 的高度。

scale 属性必须运行这些步骤：

1. 如果 视觉视口 的 关联文档 不是 完全活动 的，则返回 0 并终止这些步骤。

2. 如果没有输出设备，则返回 1 并中止这些步骤。

3. 否则，返回 视觉视口 的 缩放因子。

onresize 是 resize 事件的 事件处理程序 IDL 属性。

onscroll 是 scroll 事件的 事件处理程序 IDL 属性。

onscrollend 是 scrollend 事件的 事件处理程序 IDL 属性。

13. 事件

13.1. 调整视口大小

本节与 HTML 中定义的 事件循环（event loop） 集成。 [HTML]

当被要求为 Document doc 运行调整大小步骤（run the resize steps） 时，运行以下步骤：

1. 如果 doc 的 视口 自上次运行这些步骤以来，其宽度或高度发生了变化（例如由于用户调整了浏览器窗口，或更改了 页面缩放，或 iframe 元素的尺寸发生了变化），则在与 doc 关联的 Window 对象上 触发（fire） 一个名为 resize 的事件。

2. 如果与 doc 关联的 VisualViewport 的 scale、width 或 height 属性自上次运行这些步骤以来发生了变化，则在 VisualViewport 上 触发 一个名为 resize 的事件。

13.2. 滚动

本节与 HTML 中定义的 事件循环 集成。 [HTML]

每个 Document 都有一个关联的 待处理滚动事件目标列表（pending scroll event targets），最初为空。

每个 Document 都有一个关联的 待处理 scrollend 事件目标列表，最初为空。

每当 视口 发生滚动（无论是响应用户交互还是通过 API），用户代理都必须运行以下步骤：

1. 令 doc 为 视口 的关联 Document。

2. 如果 doc 是一个 滚动捕捉容器（snap container），则运行 更新 scrollsnapchanging 目标 的步骤，其中 doc 在块轴方向的 最终捕捉目标 为 newBlockTarget，doc 在内联轴方向的 最终捕捉目标 为 newInlineTarget。

3. 如果 doc 已经在 doc 的 待处理滚动事件目标列表 中，则终止这些步骤。

4. 将 doc 添加到 doc 的 待处理滚动事件目标列表 中。

每当元素发生滚动（无论是响应用户交互还是通过 API），用户代理都必须运行以下步骤：

1. 令 doc 为该元素的 节点文档（node document）。

2. 如果该元素是 滚动捕捉容器，则运行 更新 scrollsnapchanging 目标 的步骤，其中该元素在块轴方向的 最终捕捉目标 为 newBlockTarget，该元素在内联轴方向的 最终捕捉目标 为 newInlineTarget。

3. 如果该元素已经在 doc 的 待处理滚动事件目标列表 中，则终止这些步骤。

4. 将该元素添加到 doc 的 待处理滚动事件目标列表 中。

每当 视觉视口 发生滚动（无论是响应用户交互还是通过 API），用户代理都必须运行以下步骤：

1. 令 vv 为滚动的 VisualViewport 对象。

2. 令 doc 为 vv 的 关联文档。

3. 如果 vv 已经在 doc 的 待处理滚动事件目标列表 中，则终止这些步骤。

4. 将 vv 添加到 doc 的 待处理滚动事件目标列表 中。

当被要求为 Document doc 运行滚动步骤（run the scroll steps） 时，运行以下步骤：

1. 运行为 doc 分发待处理 scrollsnapchanging 事件 的步骤。

2. 对于 doc 的 待处理滚动事件目标列表 中的每个项目 target，按添加到列表的顺序，运行以下子步骤：

   1. 如果 target 是 Document，则在 target 上 触发 一个冒泡的名为 scroll 的事件。

   2. 否则，在 target 上 触发 一个名为 scroll 的事件。

3. 清空 doc 的 待处理滚动事件目标列表。

4. 运行为 doc 分发待处理 scrollsnapchange 事件 的步骤。

每当滚动 完成（completed） 时，用户代理必须运行以下步骤：

scrollend 事件的触发顺序是什么？是基于滚动开始还是滚动完成？

1. 对于每个已滚动的滚动盒子 box：

   1. 如果 box 属于一个 视口，令 doc 为 视口 的关联 Document，target 为该 视口。如果 box 属于一个 VisualViewport，令 doc 为 VisualViewport 的 关联文档，target 为该 VisualViewport。否则，box 属于一个元素，令 doc 为该元素的 节点文档，target 为该元素。

   2. 如果 box 属于一个 滚动捕捉容器 snapcontainer，则运行 snapcontainer 的 更新 scrollsnapchange 目标 步骤。

   3. 如果 target 已经在 doc 的 待处理 scrollend 事件目标列表 中，则终止这些步骤。

   4. 将 target 添加到 doc 的 待处理 scrollend 事件目标列表 中。

2. 运行为 doc 分发待处理 scrollsnapchange 目标 的步骤。

3. 对于 doc 的 待处理 scrollend 事件目标列表 中的每个项目 target，按添加到列表的顺序，运行以下子步骤：

   1. 如果 target 是 Document，则在 target 上 触发 一个冒泡的名为 scrollend 的事件。

   2. 否则，在 target 上 触发 一个名为 scrollend 的事件。

4. 清空 doc 的 待处理 scrollend 事件目标列表。

13.3. 事件摘要

本节是非规范性的。

14. 布局后状态快照

一些 CSS 特性使用布局后的状态（如滚动位置）作为下一次样式和布局更新的输入。

当被要求为 Document doc 运行快照布局后状态步骤（run snapshot post-layout state steps） 时，运行以下步骤：

1. 对于每个需要对布局后状态进行快照的 CSS 特性，拍摄 doc 中相关状态的快照。

拍摄快照的状态在其他规范中定义。这些步骤绝不能以其他布局后快照步骤能够观察到该快照发生的方式使 doc 或任何其他 Document 失效。因此，此类快照进行的顺序必须无关紧要。

15. 隐私考量

Screen 接口公开了有关用户显示配置的信息，这些信息可能被用作指纹算法的输入。用户代理可以选择隐藏或量化有关屏幕大小或配置的信息，以保护用户的隐私。

MouseEvent 包含有关事件相对于屏幕的坐标信息。用户代理可以将这些属性设置为掩盖事件实际屏幕相对位置的值，以保护用户的隐私。

16. 安全考量

本规范未报告任何新的安全考量。

17. 变更

本节记录了本规范各个版本之间的一些变更。本节并不详尽。错误修复和编辑性更改通常不会列出。

自 2016 年 3 月 17 日工作草案以来的变更

• 添加 Simon Fraser 和 Emilio Cobos Álvarez 为现任编辑，并将 Simon Pieters 移至前任编辑。

• 阐明了 getClientRects() 如何处理 排版字符单元。

• 更改了 getBoundingClientRect() (Element) 和 getBoundingClientRect() (Range) 处理空矩形的方式。

• 更改了 Shadow DOM 的 offsetParent 定义。

• 出于隐私考虑，允许 UA 对 Screen 属性撒谎。

• 将 colorDepth 和 pixelDepth 更改为返回真实值。

• 将“CSS 像素”更改为引用 [CSS-VALUES]。

• 将 ScrollIntoViewOptions 的默认值更改为 start 和 nearest，并略微更改了 scrollIntoView() 的行为。

• 添加了 screenLeft 和 screenTop 作为 screenX 和 screenY 的别名。

• 根据 块结束（block-end） 和 行内结束（inline-end） 定义溢出方向。

• 将 resizeTo() 的参数重命名为 width 和 height。

• 将脚本触发的滚动捕捉（scroll-snap）添加到受 scroll-behavior 影响的滚动列表中。

• 修复了术语部分的一个逻辑错误。

• 添加了“安全考量”和“隐私考量”部分。

• 将 scroll-behavior 属性移至 [CSS-OVERFLOW-3]。

• 调整了 offsetWidth 和 offsetHeight 的算法。

• 向 Element 添加了 checkVisibility() 方法。

• 将 scrollend 事件从 WICG overscroll-scrollend-events 移至 [CSSOM-VIEW-1] 并添加了处理细节。

• 向 getBoundingClientRect() 添加了一个“获取外接矩形”算法。

• 引入了 VisualViewport API 及相关概念。

• 扩展滚动到视图算法，使其也能作用于 Ranges。

• 阐明了各种 API 相对于 zoom 属性返回的是缩放后还是未缩放的尺寸。

• 在各种滚动 API 中考虑了滚动捕捉和滚动目标。

• 向 Element 添加了 currentCSSZoom 属性。

• 向 caretPositionFromPoint() 方法添加了 options 参数。

• 从 CaretPosition 接口中删除了 caret range 概念。

• 定义了布局后快照。

• 使各种滚动算法能够接受伪元素。

• 向 ScrollIntoViewOptions 添加了 container 选项。

• 添加了 scrollParent 属性。

• Pinch zoom 重命名为 缩放因子（scale factor）。

自 2013 年 12 月 17 日工作草案以来的变更

• 更改并扩展了 Element 上的 scrollIntoView() 方法。

• Element 上的 scrollTop 和 scrollLeft IDL 属性已更改为不再接受对象；改为添加了 scroll()、scrollTo() 和 scrollBy() 方法。

• Element 上的 scrollWidth、scrollHeight、clientTop、clientLeft、clientWidth 和 clientHeight IDL 属性已改回返回整数。

• 删除了 DOMRectList 接口。

• 添加了 Document 上的 scrollingElement IDL 属性。

• Window 上的某些只读属性被标记为 [Replaceable] IDL 扩展属性。

• MediaQueryList、scroll 事件和 resize 事件与 HTML 中的 事件循环 集成，以便它们与动画帧同步。

• scroll-behavior 的 instant 值重命名为 auto。

• 更改了 Element 上 scrollLeft 的原点（针对 RTL）。

• Element 上的 scrollIntoView() 方法，以及 Window 上的 scroll()、scrollTo() 和 scrollBy() 方法现在将相关字典作为第一个参数。

• MediaQueryList 接口已更改为使用常规事件 API，并据此定义 addListener()。

• 添加了“变更历史”部分。

• 将 Glenn Adams 移至前任编辑。

自 2011 年 8 月 4 日工作草案以来的变更

• 添加 Simon Pieters 和 Glenn Adams 为编辑，并将 Anne van Kesteren 移至前任编辑。

• 引入了 scroll-behavior CSS 属性。

• 从 [CSS-WRITING-MODES-3] 中添加了 块流方向（Block flow direction） 和 行内基准方向（inline base direction） 到术语表。

• 添加了关于缩放的部分。

• 向 Window 添加了 moveTo()、moveBy()、resizeTo() 和 resizeBy() 方法。

• 向 Window 添加了 devicePixelRatio 属性。

• 引入了 ScrollOptions 字典，并为滚动方法添加了一个 options 参数。

• 向 Window 添加了 devicePixelRatio 属性。

• 向 open() 方法添加了 features 参数。

• 向 Document 添加了 elementsFromPoint() 方法。

• 向 CaretPosition 添加了 getClientRect() 方法。

• 引入了 GeometryUtils 接口的初步草案。

• 将 innerWidth、innerHeight 等更改为使用 double。

• 现在承认了 CSS 变换。

• 用 DOMRect 替换了 ClientRect。

• 定义了 scroll 和 resize 事件的触发行为。

• 将 colorDepth 和 pixelDepth 更改为始终返回 24。

自 2009 年 8 月 4 日工作草案以来的变更

• 删除了其他规范中冗余的术语定义，明确定义了单位（如 CSS 像素）和内容/文档内容的区分。

• 引入了 MediaQueryList 接口。

• 将 Media 的 matchMedium() 方法移至 Window 接口，并重命名为 matchMedia()，同时将其返回类型更改为 MediaQueryList。

• 移除了 AbstractView 和 Media 接口。

• 移除了 DocumentView 接口，并将 elementFromPoint() 和 caretRangeFromPoint() 方法移至 Document 接口。

• 将 caretRangeFromPoint() 方法重命名为 caretPositionFromPoint()。

• 引入了 CaretPosition 接口，并将 caretPositionFromPoint() 的返回类型更改为 CaretPosition。

• 向 Element 接口添加了 scrollIntoView() 方法。

自 2008 年 2 月 22 日工作草案以来的变更

• 移除了 WindowView 接口，并将其属性和方法移至 AbstractView 及继承的 ScreenView 接口。

• 向 AbstractView 添加了 document IDL 属性。

• 向 ScreenView 接口添加了 scroll()、scrollTo() 和 scrollBy() 方法。

• 移除了 ElementView 接口，并将其属性和方法移至 Element 和 HTMLElement 接口。

• 向 DocumentView 接口添加了 defaultView IDL 属性和 caretRangeFromPoint() 方法。

• 移除了 RangeView 接口，转而直接扩展 Range 接口。

• 移除了 MouseEventView 接口，转而直接扩展 MouseEvent 接口。

• 将 TextRectangleList 接口重命名为 ClientRectList，并将 item() 方法转换为索引获取器。

• 将 TextRectangle 接口重命名为 ClientRect，并添加了 width 和 height 属性。

18. 致谢

编辑们衷心感谢 Alan Stearns, Alexey Feldgendler, Antonio Gomes, Björn Höhrmann, Boris Zbarsky, Chris Rebert, Corey Farwell, Dan Bates, David Vest, Elliott Sprehn, Garrett Smith, Henrik Andersson, Hallvord R. M. Steen, Kang-Hao Lu, Koji Ishii, Leif Arne Storset, Luiz Agostini, Maciej Stachowiak, Michael Dyck, Mike Wilson, Morten Stenshorne, Olli Pettay, Pavel Curtis, Peter-Paul Koch, Rachel Kmetz, Rick Byers, Robert O’Callahan, Sam Weinig, Scott Johnson, Sebastian Zartner, Stewart Brodie, Sylvain Galineau, Tab Atkins, Tarquin Wilton-Jones, Thomas Moore, Thomas Shinnick 以及 Xiaomei Ji 对本文档所作的贡献。

特别感谢首先实现本草案中列出的许多功能并由 Windows Internet Explorer 浏览器广泛部署的微软员工。