CSS 溢出模块 第3级

W3C 工作草案

关于本文档的更多信息
此版本:
https://www.w3.org/TR/2025/WD-css-overflow-3-20251007/
最新发布版本:
https://www.w3.org/TR/css-overflow-3/
编辑草案:
https://drafts.csswg.org/css-overflow-3/
以前的版本:
历史:
https://www.w3.org/standards/history/css-overflow-3/
反馈:
CSSWG 问题仓库
在规范中内联
编辑:
Elika J. Etemad / fantasai (Apple)
Florian Rivoal (代表 Bloomberg)
前编辑:
L. David Baron (Mozilla)
为此规范建议编辑:
GitHub 编辑器

摘要

本模块包含了与 CSS 在可视媒体中可滚动溢出处理相关的功能。 本级重点在于对现有溢出特性的精确定义,包括 overflow 属性及其长写形式;以及 text-overflow 属性。 还定义了为支持 [CSS-CONTAIN-1][CSS-CONTAIN-2] 引入的部分新特性:overflow: clip 以及 overflow-clip-margin 属性。

CSS 是一种用于描述结构化文档(如 HTML 和 XML)在屏幕、纸张等媒介上渲染方式的语言。

本文档状态

本节描述了本文件在发布时的状态。当前的 W3C 出版物列表以及本技术报告的最新修订可在 W3C 标准与草案索引。 中找到。

本文件由 CSS Working Group 作为 工作草案 发布,采用推荐程序(Recommendation track)。以工作草案的形式发布并不表示得到 W3C 及其成员的认可。

这是一个草案文件,可能随时被更新、替换或由其他文件废弃。将本文件作为正在进行中的工作以外的正式引用并不合适。

请通过 在 GitHub 提交问题(首选)发送反馈,在标题中包含规范代码“css-overflow”,例如:“[css-overflow] …评论摘要…”。所有问题和评论都会被 存档。或者,反馈也可以发送到(已存档)公共邮件列表 www-style@w3.org

本文件受 2025 年 8 月 18 日 W3C 流程文档 的管辖。

本文件由在 W3C 专利政策 框架下运作的一个小组制作。W3C 维护一份与该小组交付成果相关的 专利披露公开清单;该页面还包含披露专利的说明。若某人确有知识认为某项专利包含 必要权利要求,则必须按照 W3C 专利政策第 6 节 披露相关信息。

overflow 及其 longhands 的描述被认为比以前的工作草案或 [CSS2] 更完整、更正确,但仍有一些问题悬而未决。overflow: clipoverflow-clip-margin 相对较新,缺乏实现经验。text-overflow 已经稳定,与其在早期 [CSS-UI-3] 中的定义一致。尽管尚未完全通过实现经验验证,line-clamp 及其 longhands 的设计被认为大致完成。本规范的早期版本包含了通过分片创建新盒子来处理溢出的实验性新想法。这些想法并未被放弃;它们只是被 延期到第 4 级。一旦该级别稳定并完成,将恢复对分片溢出的工作。

下列特性处于风险状态,可能会在候选推荐(CR)阶段被移除:

“处于风险”(At-risk)是 W3C 流程中的术语,未必意味着该特性面临被删除或延迟的危险。它表示工作组认为该特性在可互操作地及时实现方面可能存在困难,将其标记为如此可以在过渡到提议推荐阶段时(如有必要)移除该特性,而无需先发布一份不包含该特性的新的候选推荐。

1. 引言

在 CSS Level 1 [CSS1] 中,向具有指定尺寸的元素中放入超出其容纳范围的内容通常被视为作者错误。 这样做会导致内容超出元素边界, 这很可能会导致内容与其他元素重叠。

CSS Level 2 [CSS2] 引入了 overflow 属性, 允许作者通过滚动来处理溢出, 这意味着这不再是作者错误。 同时也允许作者指定 通过裁剪来处理溢出, 当作者希望内容不被显示时,这种方式是合理的。

本规范引入了长期实际使用的 overflow-xoverflow-y 属性, 增加了 clip 值, 并对溢出处理进行了更完整的定义。

[关于 max-lines 的内容待补充]

注: 本规范还复述了 text-overflow 属性的定义, 该定义此前已在 [CSS-UI-3] 中给出, 本规范未做任何新增或修改, 目的是将 text-overflowblock-ellipsis 一并呈现。

1.1. 值定义

本规范遵循 CSS 属性定义约定(见 [CSS2]),并采用 值定义语法(见 [CSS-VALUES-3])。 未在本规范中定义的值类型,均在 CSS Values & Units [CSS-VALUES-3] 中定义。 与其他 CSS 模块结合时,这些值类型的定义可能会扩展。

除各属性定义中列出的特定值外, 本规范定义的所有属性 也接受 CSS 全局关键字 作为属性值。 为便于阅读,未在各处重复列出。

1.2. 模块交互

本模块替代并扩展了 [CSS2]11.1 溢出与裁剪 以及 [CSS-UI-3]5.2. 溢出省略号:text-overflow 属性 的相关内容。

2. 溢出概念与术语

CSS 使用 overflow 一词描述 超出盒子某一边界(即 content edgepadding edgeborder edgemargin edge)的内容。 该术语既可指导致溢出的元素或特性, 也可指这些特性所占据的非矩形区域, 更常见的是指包围该区域的最小矩形。 盒子的溢出根据其自身及所有包含该盒子的 包含块链 的后代的布局和样式计算。

在大多数情况下,overflow 可通过盒子自身的边界和属性, 加上其每个子元素的 overflow,计算得出。 但并非总是如此;例如, 当某些子元素使用 transform-style: preserve-3d [CSS3-TRANSFORMS] 时, 其后代中同样设置了 transform-style: preserve-3d 的元素也需一并考虑。

溢出有两种类型, UA 会根据不同目的使用:

2.1. 墨水溢出

盒子的 墨水溢出 是指该盒子及其内容在盒子边框外产生的视觉效果部分。 墨水溢出是指那些不会影响布局或扩展 可滚动溢出区域 的绘制效果的溢出, 如 盒阴影边框图片文本装饰、 悬挂字形(如负边距或字母升降超出 em 框)、轮廓线等。

由于 CSS 中某些效果(如 text-shadow [CSS-TEXT-3]box-shadow [CSS-BACKGROUNDS-3] 的模糊效果,理论上可无限扩展) 并未定义其视觉范围,因此 墨水溢出 的范围是未定义的。

墨水溢出区域是 盒子及其内容的 墨水溢出 所占据的非矩形区域, 墨水溢出矩形是 包含 墨水溢出区域的、与盒子轴线对齐的最小矩形。 注意 墨水溢出矩形 在盒子的坐标系下是矩形, 但在其他坐标系下由于变换可能不是矩形。[CSS3-TRANSFORMS]

任何 替换内容 的溢出始终属于 墨水溢出(而非 可滚动溢出)。

2.2. 可滚动溢出

可滚动溢出指的是一个盒子的需要提供滚动机制的、超出该盒子内边距边界的所有内容集合。

可滚动溢出区域是由可滚动溢出所占据的非矩形区域,而可滚动溢出矩形是与盒子轴对齐且包含可滚动溢出区域的最小矩形。

可滚动溢出区域是以下内容的并集:

此外,由于Web兼容性约束(因为作者利用遗留bug悄悄隐藏内容以避免视觉用户而非搜索引擎和/或语音输出),UA必须裁剪任何在不可达可滚动溢出区域中的内容。

注意:内容分布属性可以改变不可达可滚动溢出区域,以确保滚动容器对齐目标在对齐后可达。 [CSS-ALIGN-3]

注意:可滚动溢出矩形在盒子自身的坐标系中始终为矩形,但由于变换的影响,在其他坐标系下可能为非矩形[CSS3-TRANSFORMS]。这意味着有时滚动条会出现,即使实际并不需要。

2.3. 滚动溢出

盒子的溢出可以是可见的或被裁剪的。 CSS 还允许盒子成为一个滚动容器, 使其可滚动溢出区域被裁剪的部分可以通过滚动显示出来。 滚动容器的视觉“视口”(用于查看可滚动溢出区域)与其内边距盒重合,被称为滚动端口。 盒子的最近滚动端口 是其最近滚动容器祖先的滚动端口

滚动操作可以由用户发起 (例如操作滚动条、滑动触摸屏或使用键盘控制), 也可以由脚本触发 (例如通过scrollIntoView()focus() API)。 在任何滚动操作生效之前,可滚动溢出矩形滚动端口中的初始位置即为初始滚动位置初始滚动位置 通常取决于滚动容器书写模式, 并且除非另有规定,通常与其滚动原点位置一致。 例如,scroll-initial-target属性 可以用于改变初始滚动位置[CSS-SCROLL-SNAP-2]

滚动位置可滚动溢出矩形 在其滚动端口内的某种对齐方式。 它与一个滚动偏移相关联, 即它距离滚动原点的距离。

滚动原点可滚动溢出矩形的锚点坐标, 从这个点开始可滚动溢出矩形向外扩展。 除非另有规定, 它是块起点行内起点角上的可滚动溢出矩形。 (比如在弹性容器中,它是主轴起点交叉轴起点角。) 除非另有调整 (例如通过内容对齐[css-align-3]), 超出滚动原点的区域即为不可达可滚动溢出区域: 在此区域渲染的内容无法被读者访问, 参见§ 2.2 可滚动溢出。 当滚动容器滚动原点与其滚动端口对应角重合时, 认为其滚动到了滚动原点。 此时的滚动位置滚动原点位置, 通常(但并非总是)与初始滚动位置一致。

例如, 滚动吸附[CSS-SCROLL-SNAP-1] 可以将初始滚动位置调整到滚动原点位置之外。

检查类似基线对齐 是否依赖初始滚动位置滚动原点位置

此处未定义滚动偏移的坐标系。 未说明其是向下/向右增加,还是块/行内轴末端增加,或是远离滚动原点增加。 应该让每个 API 定义其坐标模型吗?

根视口,用于滚动页面画布, 会用主书写模式来确定其滚动原点初始滚动位置

注意: 如果某个滚动容器(或其某个祖先)是图形变换的目标, UA 可能需要在将用户输入映射为滚动操作时考虑此变换。 例如,在触摸屏上用户直接拖动内容进行滚动时, 通常预期变换会被考虑,以使滚动方向与手势一致。 但对于其他用户输入(如 Page Down 键,或一维滚轮)则未必需要考虑变换。 为每种滚动机制选择合适的行为由 UA 决定。

3. 滚动与裁剪溢出

3.1. 管理溢出:overflow-xoverflow-yoverflow 属性

这些属性用于指定盒子的溢出是否被裁剪, 如果裁剪, 是否成为滚动容器

名称: overflow-x, overflow-y, overflow-block, overflow-inline
值: visible | hidden | clip | scroll | auto
初始值: visible
适用对象: 块容器 [CSS2]、弹性容器 [CSS3-FLEXBOX]、网格容器 [CSS3-GRID-LAYOUT]
是否继承:
百分比: N/A
计算值: 通常是指定值,但详见正文
规范顺序: 按语法
动画类型: 离散
逻辑属性组: overflow

overflow-x 属性指定在水平方向(即盒子的左右)溢出的处理方式, overflow-y 属性则指定在垂直方向(即盒子的上下)溢出的处理方式。

overflow-blockoverflow-inline 属性同样分别指定在 块轴行内轴 上的溢出处理方式。

这四个属性与 overflow 简写属性一起,形成一个逻辑属性组,并按 CSS Logical Properties 1 § 4 流向相关盒模型属性中定义的方式进行交互。

名称: overflow
值: <'overflow-block'>{1,2}
初始值: visible
适用对象: 块容器 [CSS2]、弹性容器 [CSS3-FLEXBOX]、网格容器 [CSS3-GRID-LAYOUT]
是否继承:
百分比: N/A
计算值: 详见各自属性
动画类型: 离散
规范顺序: 按语法

overflow 属性是一个简写属性, 用于按顺序设置 overflow-xoverflow-y 的指定值。 如果第二个值省略,则与第一个值相同。

各个值的含义如下:

visible
不做特殊溢出处理, 即,盒子的内容如果定位在盒子外部则直接渲染在盒子外部。 该盒子不是 滚动容器
hidden
此值表示盒子的内容被裁剪到其 内边距盒子, UA 不应提供任何用于查看裁剪区域外内容的滚动界面, 也不允许用户直接进行滚动操作, 如在触摸屏上拖动或用鼠标滚轮滚动。 但内容仍必须能通过编程方式滚动, 例如使用 [CSSOM-VIEW] 中定义的机制, 因此该盒子仍为 滚动容器
clip
此值表示盒子的内容被裁剪到其 溢出裁剪边缘, UA 不应提供任何用于查看裁剪区域外内容的滚动界面。 此外,与 overflow: hidden 仍允许编程滚动不同, overflow: clip 完全禁止所有方式的滚动, 因此该盒子不是 滚动容器

hidden 不同,此值不会使元素建立新的格式化上下文。

注意:作者如需盒子建立格式化上下文, 可将 display: flow-rootoverflow: clip 一起使用。

scroll
此值表示内容被裁剪到 内边距盒子, 但可以通过滚动显示出来 (因此盒子是 滚动容器)。 如果用户代理采用屏幕可见的滚动机制(如滚动条或平移器), 应始终显示该机制,无论内容是否被裁剪。 这样可避免滚动条在动态环境中出现和消失的问题。 当目标媒介为 print 时, 溢出内容可能被打印; 但未定义具体可能打印在哪里。
auto
当盒子有 scroll 时,表现如 scroll; 否则表现如 hidden。 因此,如果用户代理采用屏幕可见的滚动机制(如滚动条或平移器), 只有在有溢出时才会显示该机制。

scrollautohidden 这些值被称为 可滚动值visibleclip 被称为 不可滚动值

visible/clipoverflow 计算值会被转换为 auto/hidden(分别对应) 如果 overflow-xoverflow-y 的值不是 visible 也不是 clip。 在 替换元素 上, 计算值为 hidden 还会进一步解析为 使用值 clip

如果 overflow 属性在 块盒子 上的计算值 既不是 visible,也不是 clip,也不是两者组合, 则它会为其内容建立独立格式化上下文

用户代理还必须支持 overlay 关键字, 作为 遗留值别名 auto 的等价值。

3.1.1. visibilityoverflow 的交互

如果 visibility 属性的计算值为 hidden (或者 collapse 时效果与 hidden 相同), 且 overflowscrollauto, 则:

3.1.2. border-radiusoverflow 的交互

CSS Backgrounds 3 § 4.3 角裁剪中所述, 由 overflow 建立的裁剪区域可以是圆角:

3.1.3. 打印及其他静态媒介中的溢出

由于静态媒介(如打印)无法滚动, 作者应注意让内容在此类媒介下可访问, 例如可以使用 @media print, (update: none) { … } 来调整布局,使所有相关内容同时可见。

在非交互媒介中的 滚动容器overflow 属性值为 autoscroll (但不是 hidden) 时,UA 可以对可滚动溢出进行提示, 比如显示滚动条或省略号。

注意:并非所有分页媒体都是非交互式的: 例如电子书阅读器对内容分页, 但依然是交互式的。

3.2. 扩展裁剪边界:overflow-clip-margin 属性

名称: overflow-clip-margin
值: <visual-box> || <length [0,∞]>
初始值: 0px
适用对象: 应用于 overflow 属性可用的盒子
是否继承:
百分比: n/a
计算值: 计算后的 <length> 和一个 <visual-box> 关键字
规范顺序: 按语法
动画类型: 如果 <visual-box> 的值一致,则按计算值,否则为离散

该属性定义盒子的 溢出裁剪边缘, 即内容在被裁剪前允许绘制到盒子边界之外的具体距离, 裁剪效果(如上方的 overflow: clip) 会按照盒子的 溢出裁剪边缘裁剪内容。

值定义如下:

<visual-box>

指定作为 溢出裁剪边缘原点的盒子边界, 即当指定偏移为零时使用的边界。

如未指定, 默认为 padding-box

<length [0,∞]>

指定的偏移决定 溢出裁剪边缘从指定盒子边界扩展的距离。 负值无效。 未指定时默认为零。

溢出裁剪边缘在角部的形状 与 外部盒阴影完全一致, 扩展半径与盒子的 边框边界的累计偏移相同。 参见 CSS Backgrounds 3 § 4.2 角形状CSS Backgrounds 3 § 6.1.1 阴影形状、扩展与穿透, 特别注意超出 边框边界的扩展公式。

注意:该属性对 overflow: hiddenoverflow: scroll 的盒子无效, 因为它们不会使用 溢出裁剪边缘

3.3. 溢出视口传播

当根元素的 display 属性值不是 none 时,UA 必须将根元素上设置的 overflow-* 的值应用于 视口。 但如果根元素是 [HTML] html 元素 (包括 HTML 的 XML 语法) 且其 overflow 属性在两个轴上值都是 visible, 且该元素有一个 body 元素子节点,且该 display 值也不是 none, 用户代理必须改为将该第一个子元素的 overflow-* 值应用于视口。 用于传播值的元素其使用的 overflow 值必须为 visible

注意:在 HTML htmlbody 元素上使用 containment, 会禁用 HTML body 元素的这种特殊处理。 详见 CSS Containment 1 § 2 强隔离:contain 属性

注意:在根元素上使用 overflow: hidden,可能不会裁剪初始包含块(Initial Containing Block)之外的所有内容, 如果 ICB 比视口小,这种情况在移动端可能发生。

如果将 visible 应用于视口, 必须按 auto 处理。 如果将 clip 应用于视口, 必须按 hidden 处理。

3.4. 平滑滚动:scroll-behavior 属性

名称: scroll-behavior
值: auto | smooth
初始值: auto
适用对象: 滚动容器
是否继承:
百分比: n/a
计算值: 指定值
规范顺序: 按语法
动画类型: 不可动画

scroll-behavior 属性用于指定 滚动容器的滚动行为, 当因导航、滚动 API [CSSOM-VIEW]、 或用户未主动发起的滚动吸附操作 [CSS-SCROLL-SNAP-1] 发生滚动时生效。 其他滚动(如用户主动滚动)不会受此属性影响。 当该属性指定在根元素上时,会应用到 视口

注意:HTML body 元素上的 scroll-behavior 属性 不会传播到视口。

auto
滚动容器瞬时方式滚动。
smooth
滚动容器平滑方式滚动, 使用由用户代理定义的计时函数和时长。 用户代理应遵循平台习惯(如有)。

用户代理可以忽略此属性。

4. 滚动条与布局

4.1. 滚动条对尺寸的影响

在为位于元素盒子边缘的滚动条预留空间时, 预留空间会插入到内边框边缘与外部内边距边缘之间。 但对于背景定位区域背景绘制区域, 这部分预留空间被视为内边距盒子的一部分。

在下述文档片段中, 一个绝对定位的元素和一个背景图片都被定位在盒子的右上角。
<style>
  article {
    background: top right no-repeat url(circle.png);
    position: relative;
    overflow: auto; }
  aside { position: absolute; top: 0; right: 0; }
</style>
<article>
  <aside>×</aside>
</article>

如果 <article> 没有滚动条, 两者会重合在右上角的内边距边缘。 但如果存在滚动条, <aside> 会完全可见,位于靠近滚动条的内边距盒边缘; 而背景图片则会被收纳在滚动条下面, 位于滚动条扩展后的背景定位区域的右上角。

当盒子采用固有尺寸时, 预留空间会被加到内容尺寸上。 否则会从分配给内容区域的空间中减去。 在滚动条影响尺寸的情况下, UA 必须首先假设不需要滚动条, 如果发现确实需要,则重新计算尺寸。

在下面的文档片段中, 外层 <article> 设置了 height: auto, 但 max-height: 5em。 内层 <section> 有很大的外边距,通常刚好能容纳:
...
    article { overflow: auto; max-height: 5em;  width: max-content; }
    section { margin: 2em; line-height: 1 }
...
<article>
  <section>
    This section has big margins.
  </section>
</article>

如果我们假设 <article> 需要滚动条, 那么 <section> 的高度, 包括一行文本和两次 2em 的外边距, 总计为 5em 加上滚动条。 由于这超过了最大允许高度 5em, 看起来我们假设得很对,d1 确实需要滚动条。

但其实我们应当从不需要滚动条假设开始。 那样的话 <article> 的内容高度正好是最大高度 5em, 证明假设是正确的, <article> 实际上不应有滚动条。

4.2. 为滚动条预留空间:scrollbar-gutter 属性

用户代理在内边框边缘与外部内边距边缘之间为显示滚动条预留的空间, 被称为 滚动条槽

scrollbar-gutter 属性允许作者控制 滚动条槽的存在, 与通过overflow属性控制滚动条的存在是分开的。

名称: scrollbar-gutter
值: auto | stable && both-edges?
初始值: auto
适用对象: 滚动容器
是否继承:
百分比: n/a
计算值: 指定关键字
规范顺序: 按语法
动画类型: 离散

该属性会影响盒子滚动条槽行内起始边缘或行内结尾边缘的存在。

盒子的滚动条槽块起始边缘和块结束边缘上的存在 在本级别中无法控制, 并且其决定方式与滚动条槽出现在行内起始边缘或行内结尾边缘时 scrollbar-gutterauto时一致。

默认情况下放在内容盒上的滚动条 不会导致创建滚动条槽, 这些滚动条被称为覆盖型滚动条。 此类滚动条通常部分透明,可以看到其下方的内容(如果有)。 它们的外观和尺寸可能会根据用户是否以及如何与其交互而变化。

始终放在滚动条槽中、出现时会占用空间的滚动条, 被称为经典滚动条。 此类滚动条通常是不透明的。

无论使用经典滚动条 还是覆盖型滚动条, 滚动条的外观和尺寸, 以及滚动条出现在盒子的起始还是结尾边缘, 都由UA定义。

注意:滚动条在哪一侧出现可能取决于操作系统习惯、 双向性, 或其他人体工学考虑。

对于经典滚动条滚动条槽的宽度(如果存在,见下文) 与滚动条宽度相同。 对于覆盖型滚动条, 不会有滚动条槽

注意:对于覆盖型滚动条启用滚动条槽存在已知用例, 但目前尚无令人满意的设计方案。 未来属性扩展可能会解决此问题。 参见CSS Overflow 4 § B 滚动条槽的可能扩展

该属性的各值含义如下:

auto
经典滚动条overflowscroll, 或 overflowauto 且盒子溢出时, 会通过创建滚动条槽来占用空间。 覆盖型滚动条不占用空间。
stable
对于经典滚动条 只要overflow取值为 hiddenscrollauto, 无论盒子是否真的溢出, 都会有滚动条槽存在。 覆盖型滚动条不占用空间。

注意:这不会改变滚动条本身是否可见, 只影响是否有滚动条槽。

both-edges
如果在盒子的行内起始边缘或行内结尾边缘会有滚动条槽, 那么在对侧也必须有一个滚动条槽

滚动条槽存在但滚动条不存在, 或滚动条透明或不能完全遮挡滚动条槽时, 滚动条槽的背景必须作为内边距的延伸进行绘制。

overflow属性类似, 当scrollbar-gutter设置在根元素上时, 用户代理应将其应用到视口, 根元素本身的使用值为scrollbar-gutter: auto。 但与overflow属性不同, 用户代理不得从HTML body 元素传播scrollbar-gutter

注意:下表总结了overflowscrollbar-gutter的交互, 展示了在哪些情况下会为经典滚动条滚动条槽预留空间。
是否应为经典滚动条滚动条槽预留空间?
overflow scrollbar-gutter 溢出 未溢出
scroll auto
stable
auto auto
stable
hidden auto
stable
visible, clip auto
stable

5. 自动省略号

5.1. 溢出省略号:text-overflow 属性

名称: text-overflow
值: clip | ellipsis
初始值: clip
适用对象: 块容器
是否继承:
百分比: N/A
计算值: 指定关键字
规范顺序: 按语法
动画类型: 离散

该属性指定当内联内容在其块容器元素(“块”)的内联推进方向上超出 尾端 行盒边缘时的渲染方式, 且该块元素的 overflow 不为 visible 时生效。

文本溢出的情况举例:如被禁止换行(如 white-space: nowrap 或单词过长无法容纳)。 各值含义如下:

clip
对溢出块容器元素的内联内容进行裁剪。字符可能只显示部分。
ellipsis
用省略号字符(U+2026)表示被裁剪的内联内容。 实现可以根据语言、书写系统或书写模式选择更合适的省略号字符, 如果无法获取省略号字符,也可以用三个点“...”代替。

“字符”一词在本属性定义中为便于阅读而使用,实际实现时指“字素簇” [UAX29]

对于 ellipsis 值, 实现必须隐藏字符及 原子内联级元素 以确保省略号能放在行的 尾端边缘,并将省略号紧挨着剩余内联内容的尾端边缘。 行首的第一个字符或 原子内联级元素 必须裁剪而非用省略号表示。

双向文本省略号示例

这些示例演示在双向文本情况下,为省略号留空间时隐藏哪些字符:即视觉上行尾边缘的字符。

示例 CSS:

div {
  font-family: monospace;
  white-space: pre;
  overflow: hidden;
  width: 9ch;
  text-overflow: ellipsis;
}

示例 HTML 片段、渲染和你的浏览器:

HTML 参考渲染 你的浏览器
<div>שלום 123456</div>
123456 ם…
שלום 123456
<div dir=rtl>שלום 123456</div>
…456 שלום
שלום 123456

省略号细节

用户与省略号的交互

示例:

text-overflow 示例

这些示例展示了为块容器元素设置 text-overflow 属性,且文本溢出其尺寸时的效果:

div 的示例 CSS:

div {
  font-family:Helvetica,sans-serif; line-height:1.1;
  width:3.1em; padding:.2em; border:solid .1em black; margin:1em 0;
}

示例 HTML 片段、渲染和你的浏览器:

HTML 示例渲染 你的浏览器
<div>
CSS IS AWESOME, YES
</div>
首先,一个文本溢出盒子的示例。
CSS IS AWESOME, YES
<div style="text-overflow:clip; overflow:hidden">
CSS IS AWESOME, YES
</div>
其次,文本被裁剪在盒子外部的示例。
CSS IS AWESOME, YES
<div style="text-overflow:ellipsis; overflow:hidden">
CSS IS AWESOME, YES
</div>
再次,省略号代表被裁剪文本的示例。
CSS IS AWESOME, YES
<div style="text-overflow:ellipsis; overflow:hidden">
NESTED
 <p>PARAGRAPH</p>
WON’T ELLIPSE.
</div>
第四个,嵌套段落示例,演示匿名块盒等效性及属性不会继承到嵌套元素。
NESTED

PARAGRAPH

WON’T ELLIPSE.

注意:省略号出现在哪一侧取决于块的direction属性。 例如右到左(direction: rtl)的块溢出时会裁剪内容在左侧, 因此省略号会放在左侧以代表被裁剪内容。

省略号与滚动界面的交互

本节适用于 text-overflow 不为 text-overflow:clip(非 clip 的 text-overflow) 且 overflow:scroll。

当元素设置了非 clip 的 text-overflow 且在文本的内联推进方向上有 scroll 溢出, 且浏览器提供滚动机制(如滚动条、触摸滑动等), 还需实现一些细节以提升用户体验:

当元素被滚动(如用户或 DOM 操作), 元素内容会显示更多。 text-overflow 的值不应影响内容是否显示更多。 如果设置了非 clip 的 text-overflow, 随着内容滚动进入可视区域, 实现应显示可容纳的所有内容, 只截断本应被裁剪的内容 (或为省略号/字符串留空间所需), 直到滚动到内容边缘, 此时应显示内容本身而非省略号/字符串。

该示例在带 overflow scroll 的元素上使用 text-overflow,演示上述行为。

示例 CSS:

div.crawlbar {
  text-overflow: ellipsis;
  height: 2em;
  overflow: scroll;
  white-space: nowrap;
  width: 15em;
  border:1em solid black;
}

示例 HTML 片段:

<div class="crawlbar">
CSS is awesome, especially when you can scroll
to see extra text instead of just
having it overlap other text by default.
</div>

CSS 和 HTML 示例演示:

CSS is awesome, especially when you can scroll to see extra text instead of just having it overlap other text by default.

内容滚动时,实现可以调整省略号的渲染(如与盒子边缘对齐而非行边缘)。

附录A. 隐私注意事项

本规范未引入新的隐私问题。

附录B. 安全注意事项

本规范未引入新的安全问题。

附录C. 变更记录

本附录为说明性

2023年3月29日工作草案以来的主要变更:

另见之前的变更

致谢

特别感谢以下人员的反馈: Rossen Atanassov, Tab Atkins, Bert Bos, Tantek Çelik, John Daggett, Daniel Glazman, Vincent Hardy, Ian Kilpatrick, Håkon Wium Lie, Peter Linss, Robert O’Callahan, Florian Rivoal, Alan Stearns, Steve Zilles, 以及所有 www-style 社区成员。

一致性

文档约定

一致性要求通过描述性断言和 RFC 2119 术语表达。规范性部分中的关键词 “MUST”(必须)、“MUST NOT”(禁止)、“REQUIRED”(要求)、“SHALL”(应)、“SHALL NOT”(不应)、“SHOULD”(建议)、“SHOULD NOT”(不建议)、“RECOMMENDED”(推荐)、“MAY”(可以)、“OPTIONAL”(可选)应按照 RFC 2119 的说明进行解释。但为便于阅读,本规范未将这些词全部大写。

除明确标记为非规范性、示例和注释的部分外,本规范所有文本均为规范性内容。[RFC2119]

本规范中的示例以 “for example”(例如)开头,或通过 class="example" 与规范性文本区分,如下所示:

这是一个说明性示例。

说明性注释以 “Note”(注)开头,并通过 class="note" 与规范性文本区分,如下所示:

注:这是一个说明性注释。

建议性内容为规范性部分,样式突出显示,并通过 <strong class="advisement"> 与其他规范性文本区分,如下所示: 用户代理必须提供可访问的替代方案。

一致性类别

本规范定义了三类一致性对象:

样式表
CSS 样式表
渲染器
解释样式表语义并渲染使用样式表的文档的 UA
创作工具
编写样式表的 UA

如果样式表中使用本模块定义的语法的所有语句均符合通用 CSS 语法及本模块各特性的语法,则该样式表符合本规范。

渲染器符合本规范,需在解释样式表时,正确支持本规范定义的所有特性,正确解析并渲染文档。但由于设备限制导致 UA 无法正确渲染文档,并不视为不符合规范。(例如,UA 不要求在单色显示器上渲染颜色。)

创作工具符合本规范,需编写语法正确的样式表,符合通用 CSS 语法及本模块各特性的语法,并满足本模块描述的所有样式表一致性要求。

部分实现

为便于作者利用前向兼容解析规则分配回退值,CSS 渲染器必须将所有不具备可用支持级别的 at-规则、属性、属性值、关键字及其他语法结构视为无效(并按需忽略)。特别是,用户代理不得在多值属性声明中选择性忽略不支持的组件值而保留支持的值:如果任何值被视为无效(不支持的值必须如此),CSS 要求整个声明被忽略。

不稳定及专有特性的实现

为避免与未来稳定 CSS 特性冲突,CSS 工作组建议遵循最佳实践,实现不稳定特性和专有扩展

非实验性实现

一旦规范进入候选推荐阶段,允许非实验性实现,且实现者应发布任何已证明按规范正确实现的 CR 级特性的无前缀实现。

为建立和维护 CSS 在各实现间的互操作性,CSS 工作组要求非实验性 CSS 渲染器在发布任何 CSS 特性的无前缀实现前,向 W3C 提交实现报告(如有必要,还需提交用于该报告的测试用例)。提交给 W3C 的测试用例将由 CSS 工作组审核和修正。

关于提交测试用例和实现报告的更多信息,请访问 CSS 工作组网站:https://www.w3.org/Style/CSS/Test/。 如有疑问,请联系 public-css-testsuite@w3.org 邮件列表。

索引

本规范定义的术语

引用定义的术语

参考文献

规范性引用

[CSS-ALIGN-3]
Elika Etemad;Tab Atkins Jr.。CSS 盒对齐模块第3级。2025年3月11日。工作草案(WD)。网址:https://www.w3.org/TR/css-align-3/
[CSS-BACKGROUNDS-3]
Elika Etemad;Brad Kemper。CSS 背景与边框模块第3级。2024年3月11日。候选推荐草案(CRD)。网址:https://www.w3.org/TR/css-backgrounds-3/
[CSS-BOX-4]
Elika Etemad。CSS 盒模型模块第4级。2024年8月4日。工作草案(WD)。网址:https://www.w3.org/TR/css-box-4/
[CSS-CASCADE-5]
Elika Etemad;Miriam Suzanne;Tab Atkins Jr.。CSS 级联与继承第5级。2022年1月13日。候选推荐(CR)。网址:https://www.w3.org/TR/css-cascade-5/
[CSS-CONTAIN-2]
Tab Atkins Jr.;Florian Rivoal;Vladimir Levin。CSS 隔离模块第2级。2022年9月17日。工作草案(WD)。网址:https://www.w3.org/TR/css-contain-2/
[CSS-DISPLAY-3]
Elika Etemad;Tab Atkins Jr.。CSS 显示模块第3级。2023年3月30日。候选推荐(CR)。网址:https://www.w3.org/TR/css-display-3/
[CSS-DISPLAY-4]
Elika Etemad;Tab Atkins Jr.。CSS 显示模块第4级。2024年12月19日。首个公开工作草案(FPWD)。网址:https://www.w3.org/TR/css-display-4/
[CSS-GRID-2]
Tab Atkins Jr. 等。CSS 网格布局模块第2级。2025年3月26日。候选推荐草案(CRD)。网址:https://www.w3.org/TR/css-grid-2/
[CSS-INLINE-3]
Elika Etemad。CSS 内联布局模块第3级。2024年12月18日。工作草案(WD)。网址:https://www.w3.org/TR/css-inline-3/
[CSS-LOGICAL-1]
Rossen Atanassov;Elika Etemad。CSS 逻辑属性与值第1级。2018年8月27日。工作草案(WD)。网址:https://www.w3.org/TR/css-logical-1/
[CSS-MASKING-1]
Dirk Schulze;Brian Birtles;Tab Atkins Jr.。CSS 遮罩模块第1级。2021年8月5日。候选推荐草案(CRD)。网址:https://www.w3.org/TR/css-masking-1/
[CSS-OVERFLOW-4]
David Baron;Florian Rivoal;Elika Etemad。CSS 溢出模块第4级。2023年3月21日。工作草案(WD)。网址:https://www.w3.org/TR/css-overflow-4/
[CSS-SCROLL-SNAP-1]
Matt Rakow 等。CSS 滚动吸附模块第1级。2021年3月11日。候选推荐(CR)。网址:https://www.w3.org/TR/css-scroll-snap-1/
[CSS-SCROLL-SNAP-2]
Elika Etemad;Tab Atkins Jr.;Adam Argyle。CSS 滚动吸附模块第2级。2024年7月23日。首个公开工作草案(FPWD)。网址:https://www.w3.org/TR/css-scroll-snap-2/
[CSS-TEXT-DECOR-4]
Elika Etemad;Koji Ishii。CSS 文本装饰模块第4级。2022年5月4日。工作草案(WD)。网址:https://www.w3.org/TR/css-text-decor-4/
[CSS-TRANSFORMS-2]
Tab Atkins Jr. 等。CSS 变换模块第2级。2021年11月9日。工作草案(WD)。网址:https://www.w3.org/TR/css-transforms-2/
[CSS-UI-3]
Tantek Çelik;Florian Rivoal。CSS 基本用户界面模块第3级 (CSS3 UI)。2018年6月21日。推荐(REC)。网址:https://www.w3.org/TR/css-ui-3/
[CSS-VALUES-3]
Tab Atkins Jr.;Elika Etemad。CSS 单位与数值模块第3级。2024年3月22日。候选推荐草案(CRD)。网址:https://www.w3.org/TR/css-values-3/
[CSS-VALUES-4]
Tab Atkins Jr.;Elika Etemad。CSS 单位与数值模块第4级。2024年3月12日。工作草案(WD)。网址:https://www.w3.org/TR/css-values-4/
[CSS-WRITING-MODES-4]
Elika Etemad;Koji Ishii。CSS 书写模式第4级。2019年7月30日。候选推荐(CR)。网址:https://www.w3.org/TR/css-writing-modes-4/
[CSS2]
Bert Bos 等。层叠样式表第2级修订版 (CSS 2.1) 规范。2011年6月7日。推荐(REC)。网址:https://www.w3.org/TR/CSS2/
[CSS3-FLEXBOX]
Tab Atkins Jr. 等。CSS 弹性盒布局模块第1级。2018年11月19日。候选推荐(CR)。网址:https://www.w3.org/TR/css-flexbox-1/
[CSS3-GRID-LAYOUT]
Tab Atkins Jr. 等。CSS 网格布局模块第1级。2025年3月26日。候选推荐草案(CRD)。网址:https://www.w3.org/TR/css-grid-1/
[CSS3-TRANSFORMS]
Simon Fraser 等。CSS 变换模块第1级。2019年2月14日。候选推荐(CR)。网址:https://www.w3.org/TR/css-transforms-1/
[CSSOM-VIEW]
Simon Fraser;Emilio Cobos Álvarez。CSSOM 视图模块。2025年9月16日。工作草案(WD)。网址:https://www.w3.org/TR/cssom-view-1/
[HTML]
Anne van Kesteren 等。HTML 标准。动态标准。网址:https://html.spec.whatwg.org/multipage/
[RFC2119]
S. Bradner。RFC中用于指示需求级别的关键词。1997年3月。最佳当前实践。网址:https://datatracker.ietf.org/doc/html/rfc2119
[UAX29]
Josh Hadley。Unicode 文本分段。2025年8月17日。Unicode 标准附录 #29。网址:https://www.unicode.org/reports/tr29/tr29-47.html

说明性引用

[CSS-CONTAIN-1]
Tab Atkins Jr.; Florian Rivoal。CSS 隔离模块第1级。2024年6月25日。推荐(REC)。网址:https://www.w3.org/TR/css-contain-1/
[CSS-SIZING-3]
Tab Atkins Jr.; Elika Etemad。CSS 盒尺寸模块第3级。2021年12月17日。工作草案(WD)。网址:https://www.w3.org/TR/css-sizing-3/
[CSS-TEXT-3]
Elika Etemad; Koji Ishii; Florian Rivoal。CSS 文本模块第3级。2024年9月30日。候选推荐草案(CRD)。网址:https://www.w3.org/TR/css-text-3/
[CSS-WRITING-MODES-3]
Elika Etemad; Koji Ishii。CSS 书写模式第3级。2019年12月10日。推荐(REC)。网址:https://www.w3.org/TR/css-writing-modes-3/
[CSS1]
Håkon Wium Lie; Bert Bos。层叠样式表,第1级。2018年9月13日。推荐(REC)。网址:https://www.w3.org/TR/CSS1/
[MEDIAQUERIES-5]
Dean Jackson 等。媒体查询第5级。2021年12月18日。工作草案(WD)。网址:https://www.w3.org/TR/mediaqueries-5/

属性索引

名称 初始值 适用对象 是否继承 百分比 动画类型 规范顺序 计算值 逻辑属性组
overflow <'overflow-block'>{1,2} visible 块容器 [CSS2]、弹性容器 [CSS3-FLEXBOX]、网格容器 [CSS3-GRID-LAYOUT] N/A 离散 按语法 详见各自属性
overflow-block visible | hidden | clip | scroll | auto visible 块容器 [CSS2]、弹性容器 [CSS3-FLEXBOX]、网格容器 [CSS3-GRID-LAYOUT] N/A 离散 按语法 通常为指定值,详见正文 overflow
overflow-clip-margin <visual-box> || <length [0,∞]> 0px overflow 可应用的盒子 n/a 若 <visual-box> 值一致则按计算值,否则为离散 按语法 计算后的 <length> 和 <visual-box> 关键字
overflow-inline visible | hidden | clip | scroll | auto visible 块容器 [CSS2]、弹性容器 [CSS3-FLEXBOX]、网格容器 [CSS3-GRID-LAYOUT] N/A 离散 按语法 通常为指定值,详见正文 overflow
overflow-x visible | hidden | clip | scroll | auto visible 块容器 [CSS2]、弹性容器 [CSS3-FLEXBOX]、网格容器 [CSS3-GRID-LAYOUT] N/A 离散 按语法 通常为指定值,详见正文 overflow
overflow-y visible | hidden | clip | scroll | auto visible 块容器 [CSS2]、弹性容器 [CSS3-FLEXBOX]、网格容器 [CSS3-GRID-LAYOUT] N/A 离散 按语法 通常为指定值,详见正文 overflow
scroll-behavior auto | smooth auto 滚动容器 n/a 不可动画 按语法 指定值
scrollbar-gutter auto | stable && both-edges? auto 滚动容器 n/a 离散 按语法 指定关键字
text-overflow clip | ellipsis clip 块容器 N/A 离散 按语法 指定关键字

问题索引

此处的变换处理描述是否足够准确?
该内容需要进一步测试和研究,因此在本草案中暂缓讨论。
需要评估哪些内容应当裁剪 可滚动溢出,哪些不应裁剪。 [Issue #8607]
检查类似 基线对齐 是否依赖 初始滚动位置滚动原点位置
此处未定义 滚动偏移 的坐标系。 未说明其是向下/向右增加,还是块/行内轴末端增加,或是远离 滚动原点 增加。 应该让每个 API 定义其坐标模型吗?