CSS 基础用户界面模块级别 3 (CSS3 UI)

W3C 推荐标准

关于此文档的更多细节
此版本
https://w3org.cn/TR/2026/REC-css-ui-3-20260407/
最新发布版本
https://w3org.cn/TR/css-ui-3/
编辑草案
https://drafts.csswg.org/css-ui-3/
历史版本
历史
https://w3org.cn/standards/history/css-ui-3/
实现报告
https://drafts.csswg.org/css-ui-3/implementation-report
反馈
CSS 工作组问题仓库
编辑
Tantek Çelik (Mozilla)
Florian Rivoal (代表 Bloomberg)
建议编辑此规范
GitHub 编辑器
测试套件
https://wpt.fyi/results/css/css-ui/

另请参阅 译本


摘要

本规范描述了拟议用于 CSS 3 级以设置 HTML 和 XML(包括 XHTML)样式的用户界面相关属性和值。它包含并扩展了 CSS 2 级修订版 1 的用户界面相关属性和值。它使用各种属性和值来设置文档中基本用户界面元素的样式。

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

关于本文档

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

本文档由 CSS 工作组以推荐标准形式发布,使用 推荐标准轨道。它包含 候选修正

W3C 推荐标准是一项经由广泛共识,由 W3C 及其成员背书,且工作组成员承诺为其实施提供免版税许可的规范。

候选更正内容已在文档中标记。

W3C 建议将本规范广泛部署为 Web 标准。

请通过 在 GitHub 上提交议题(推荐)发送反馈,请在标题中包含规范代码“css-ui”,例如:“[css-ui] …评论摘要…”。所有议题和评论均会 存档。或者,也可以将反馈发送至(已存档的)公开邮件列表 www-style@w3.org

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

本文档由在一个受 W3C 专利政策约束下运作的组织制作。W3C 维护着一份与该组织交付成果相关的专利披露公开列表;该页面还包含了披露专利的说明。任何个人如果确实获知其认为包含必要权利要求 (Essential Claim) 的专利,必须根据 W3C 专利政策第 6 节披露该信息。

1. 引言

本模块描述了使作者能够设置用户界面相关属性和值样式的 CSS 属性。

CSS1 第 2.1 节 [CSS1]CSS2 第 18 章 [CSS2] 引入了几个与用户界面相关的属性和值。CSS3 用户界面(2000 年 2 月 16 日)引入了几个新的用户界面相关特性。

本规范合并、扩展并取代了它们。

1.1. 目的

本规范旨在实现以下目标

2. 模块交互

本文档定义了早期规范中不存在的新特性。此外,它取代并废弃了以下内容

2.1. 值定义

本规范遵循 [CSS2] 中的 CSS 属性定义约定,并使用 [CSS-VALUES-3] 中的 值定义语法。本规范中未定义的值类型在 CSS 值与单位 [CSS-VALUES-3] 中定义。与其他 CSS 模块组合可能会扩展这些值类型的定义。

除了定义中列出的属性特定值外,本规范中定义的所有属性也都接受 CSS 全局关键字 作为其属性值。为了可读性,未明确重复列出。

候选修正 3:[CSS-CASCADE-4][WEB-ANIMATIONS-1] 改进了定义属性的方式,为 动画类型计算值 的基础概念提供了精确的定义。本规范中的属性定义已更新为使用这些术语。在许多情况下,这属于编辑性修改,但在某些情况下,它定义了以前不清晰或模棱两可的行为。

3. 盒模型补充

3.1. 更改盒模型:box-sizing 属性

名称box-sizing
content-box | border-box
初始值 content-box
应用于 所有接受 width 或 height 的元素
可继承
百分比 不适用
计算值 指定的值
规范顺序 按语法
动画类型 离散 (discrete)
content-box
这是 CSS2.1 中指定的 width 和 height 的行为。指定的 width 和 height(以及相应的 min/max 属性)分别应用于元素内容框的宽度和高度。元素的内边距和边框在指定的宽度和高度之外布局和绘制。
border-box
此元素上 width 和 height(以及相应的 min/max 属性)的长度和百分比值决定了元素的边框盒。也就是说,元素上指定的任何内边距或边框都在此指定的宽度和高度内布局和绘制。内容宽度和高度是通过从指定的 widthheight 属性中减去相应侧面的边框和内边距宽度计算得出的。由于内容宽度和高度 不能为负数[CSS2],第 10.2 节),此计算结果下限为 0。通过 getComputedStyle() 等方式获取的已用值也指代边框盒。

注意:这是传统 HTML 用户代理针对替换元素和输入元素通常实现的 width 和 height 行为。

注意:与长度和百分比值相反,width 和 height 属性的 auto 值(以及后续规范引入的其他关键字值,除非另有说明)不受 box-sizing 属性的影响,且始终设置内容框的大小。

引入了以下术语,其定义根据 box-sizing 的计算值而变化

box-sizing: content-box box-sizing: border-box
最小内部宽度 min-width max(0, min-widthpadding-leftpadding-rightborder-left-widthborder-right-width)
最大内部宽度 max-width max(0, max-widthpadding-leftpadding-rightborder-left-widthborder-right-width)
最小内部高度 min-height max(0, min-heightpadding-toppadding-bottomborder-top-widthborder-bottom-width)
最大内部高度 max-height max(0, max-heightpadding-toppadding-bottomborder-top-widthborder-bottom-width)

[CSS2]视觉格式化模型细节 编写时假设为 box-sizing: content-box。为阐明 box-sizing 所有值的行为,作出以下消歧处理

  1. 10.3.3 中,下述短语中的第二个 width 应解读为 内容宽度If width is not auto and border-left-width + padding-left + width + [...]
  2. 10.3.7 中,width 在下述方程中应解读为 内容宽度left + margin-left + border-left-width + padding-left + width + [...]
  3. 10.4 中,widthheightmin-widthmax-widthmin-heightmax-height 在下述短语中分别应解读为 内容宽度内容高度最小内部宽度最大内部宽度最小内部高度最大内部高度
    1. 尝试性已用宽度计算如下 [...]
    2. 如果尝试性已用宽度大于 max-width,则再次应用上述规则,但这次使用 max-width 的计算值作为 width 的计算值。
    3. 如果产生的宽度小于 min-width,则再次应用上述规则,但这次使用 min-width 的值作为 width 的计算值。
    4. 从表中选择对应约束违规情况的解析高度和宽度值。将 max-width 和 max-height 取为 max(min, max),使得 min ≤ max 成立。在此表中 w 和 h 代表宽度和高度计算的结果 [...]
    5. 表中所有这些词的实例
    6. 然后应用上述“计算宽度和外边距”下的规则,就好像 width 被计算为此值一样。
  4. 10.6.4 中,height 在下述方程中应解读为 内容高度top + margin-top + border-top-width + padding-top + height + [...]
  5. 10.7 中,widthheightmin-heightmax-height 在下述短语中分别应解读为 内容宽度内容高度最小内部高度最大内部高度
    1. 尝试性已用高度计算如下 [...]
    2. 如果此尝试性高度大于 max-height,则再次应用上述规则,但这次使用 max-height 的值作为 height 的计算值。
    3. 如果产生的高度小于 min-height,则再次应用上述规则,但这次使用 min-height 的值作为 height 的计算值。
    4. [...] 使用上述“最小和最大宽度”下的算法来查找已用宽度和高度。然后应用上述“计算高度和外边距”下的规则,使用产生的宽度和高度,就好像它们是计算值一样。

示例

使用 box-sizing 平均分配空间

此示例使用 box-sizing 在一个 div 容器内平均水平拆分两个具有固定大小边框的 div,否则这将需要额外的标记。

示例 CSS

div.container {
  width:38em;
  border:1em solid black;
}

div.split {
  box-sizing:border-box;
  width:50%;
  border:1em silver ridge;
  float:left;
}

示例 HTML 片段

<div class="container">
<div class="split">This div occupies the left half.</div>
<div class="split">This div occupies the right half.</div>
</div>

示例 CSS 和 HTML 的演示

此 div 应占据左半部分。
此 div 应占据右半部分。
上面的两个 div 应并排显示,每个(包括边框)占其容器内容宽度的 50%。如果它们反而上下堆叠,则说明您的浏览器不支持 box-sizing

4. 轮廓属性

有时,样式表作者可能希望在按钮、活动表单字段、图像映射等视觉对象周围创建轮廓,以使它们脱颖而出。轮廓在以下方面与边框不同

  1. 轮廓不占用空间。
  2. 轮廓可以是非矩形的。
  3. 用户代理通常会在 :focus 状态的元素上渲染轮廓。

轮廓属性控制这些动态轮廓的样式。

明确将这些轮廓渲染的堆叠留给实现者,以便在每个平台上提供更好的用户体验。这取代了 [CSS2]CSS 2.1 附录 E 定义的轮廓堆叠。

键盘用户(特别是可能无法以任何其他方式与页面交互的残障人士)依赖于轮廓在 :focus 状态下的元素上可见,因此作者不得使此类元素上的轮廓不可见,而不确保提供替代的高亮显示机制。

在 CSS3-UI 中,将变换应用于轮廓的渲染明确未定义。

4.1. 轮廓简写:outline 属性

名称大纲
[ <'outline-color'> || <'outline-style'> || <'outline-width'> ]
初始值 见各个属性
应用于 所有元素
可继承
百分比 不适用
计算值 见各个属性
动画类型 见各个属性
规范顺序 按语法

4.2. 轮廓粗细:outline-width 属性

候选修正 2:[CSS-VALUES-4] 引入了 捕捉为边框宽度 的概念,作为一种应用于某些长度的舍入方式,以确保合理的视觉显示。定义 outline-width 以使用此概念,以便与其他类似边框的事物保持一致。
候选修正 4:移除特殊情况,即 outline-width 基于 outline-style: none 计算为 0,从而与 应用于 column-rule-widthborder-width 的类似更改 保持一致。(参见 Issue 11494。)
名称outline-width
<line-width>
初始值 medium
应用于 所有元素
可继承
百分比 不适用
计算值 绝对长度 捕捉为边框宽度 ;如果轮廓样式为 none,则为 0
规范顺序 按语法
动画类型 长度 按计算值

4.3. 轮廓样式:outline-style 属性

名称outline-style
auto | <border-style>
初始值 none(无)
应用于 所有元素
可继承
百分比 不适用
计算值 按指定值
规范顺序 按语法
动画类型 离散 (discrete)

4.4. 轮廓颜色:outline-color 属性

名称outline-color
<color> | invert
初始值 invert
应用于 所有元素
可继承
百分比 不适用
计算值 invert 的计算值为 invertcurrentColor 的计算值为 currentColor(参见 currentcolor);对于其他 <color> 值,请参阅 color 属性。
规范顺序 按语法
动画类型 颜色 按计算值

使用轮廓属性创建的轮廓绘制在盒子的“上方”,即轮廓始终位于顶部,且不会影响该盒子或任何其他盒子的位置或大小。因此,显示或隐藏轮廓不会导致回流。

轮廓可以是非矩形的。例如,如果元素跨越几行,则轮廓应是包围该元素所有盒子的轮廓或最小轮廓集合。

轮廓的每一部分应完全连接,而不是在某些侧面开放(正如行断开时内联元素上的边框那样)。

轮廓的各部分不需要是矩形的。在轮廓跟随 边框边缘 的程度上,它应该跟随 border-radius 曲线。

轮廓的位置可能会受到后代盒子的影响。

用户代理应使用一种确定轮廓的算法,该轮廓包围的区域适合向用户传达焦点的概念。

注意:本规范未定义轮廓的确切位置或形状,但它通常绘制在边框盒的正外部。

outline-width 属性接受与 border-width 相同的值(CSS 背景 3 § 3.3 线条粗细:border-width 属性)。

outline-style 属性接受与 border-style 相同的值(CSS 背景 3 § 3.2 线条模式:border-style 属性),只是 hidden 不是合法的轮廓样式。此外,在 CSS3 中,outline-style 接受值 autoauto 值允许用户代理渲染自定义轮廓样式,通常是该平台的默认用户界面样式,或者是一种比 CSS 中能详细描述的样式更丰富的样式,例如带有半透明外像素且看起来发光的圆角轮廓。因此,本规范未定义在渲染 auto 样式轮廓时如何整合或使用(如果使用)outline-color。用户代理可以将 auto 视为 solid

outline-color 属性接受所有颜色,以及关键字 invertInvert 预计会对屏幕上的像素执行颜色反转。这是确保焦点边框可见的常用技巧,无论背景颜色如何。

合规的用户代理可以在不支持屏幕像素颜色反转的平台上忽略 invert 值。

如果用户代理不支持 invert 值,则必须在解析时拒绝该值,并且 outline-color 属性的初始值是 currentColor 关键字。

outline 属性是一个简写属性,并设置 outline-styleoutline-widthoutline-color 这三个属性。

注意:轮廓在所有侧面都是相同的。与边框不同,没有 outline-topoutline-left 等属性。

本规范未定义如何绘制多个重叠的轮廓,也未定义在盒子被其他元素部分遮挡时的绘制方式。

示例

这是在 BUTTON 元素周围绘制粗轮廓的示例

button { outline: thick solid }

图形用户界面可能会在元素周围使用轮廓,以告知用户页面上的哪个元素具有焦点。这些轮廓是边框之外的附加内容,打开或关闭轮廓不应导致文档回流。焦点是文档中用户交互的对象(例如,用于输入文本或选择按钮)。

示例

例如,要在元素获得焦点时在其周围绘制一条粗黑线,而在其处于激活状态时绘制一条粗红线,可以使用如下规则:

:focus  { outline: thick solid black }
:active { outline: thick solid red }

注意:由于轮廓不影响格式(即,在盒模型中不会为它预留空间),它很可能会与页面上的其他元素重叠。

4.5. 偏移轮廓:outline-offset 属性

默认情况下,轮廓的绘制始于 边框边缘 的正外部。但是,可以偏移轮廓并将其绘制在 边框边缘 之外。

名称outline-offset
<length>(长度)
初始值 0
应用于 所有元素
可继承
百分比 不适用
计算值 <length> 绝对单位(px 或物理)值。 绝对长度
规范顺序 按语法
动画类型 长度 按计算值

如果 outline-offset 的计算值不为 0,则轮廓将从 边框边缘 向外偏移该数量。

示例

例如,要在焦点轮廓和拥有焦点或活动的元素之间留出 2 像素的空间,可以使用以下规则

:focus,:active  { outline-offset: 2px }

负值必须导致轮廓向内收缩进入边框盒。由轮廓绘制的形状外部的高度和宽度不应小于 outline-width 属性计算值的两倍,以确保即使在大负值下也能渲染出轮廓。用户代理应在每个维度独立应用此约束。如果轮廓绘制为多个断开的形状,则此约束分别应用于每个形状。

5. 调整大小与溢出

CSS2.1 提供了一种控制块容器元素上滚动机制(例如滚动条)外观的机制。本规范在此基础上增加了一种控制元素用户可调整大小性的机制,以及指定文本溢出行为的能力。

5.1. 调整框的大小:resize 属性

resize 属性允许作者指定元素是否可由用户调整大小,如果可以,则指定可沿哪些轴调整。

候选修正 1:既然 overflow: visible 不再是唯一不会导致元素成为 滚动容器overflow 属性值,调整 resize 属性所适用的元素,以匹配原始意图,而非字面文本。
名称resize
none | both | horizontal | vertical
初始值 none(无)
应用于 元素 具有除 visible 之外的 overflow 滚动容器 以及可选的替换元素,例如图像、视频和 iframe
可继承
百分比 不适用
计算值 指定 关键字
规范顺序 按语法
动画类型 离散 (discrete)
none(无)
用户代理不在元素上呈现调整大小机制,且用户没有任何直接操作机制来调整该元素的大小。
both
用户代理呈现一个双向调整大小机制,允许用户同时调整元素的高度和宽度。
水平
用户代理呈现一个单向水平调整大小机制,允许用户仅调整元素的宽度。
vertical
用户代理呈现一个单向垂直调整大小机制,允许用户仅调整元素的高度。

目前可以使用 overflow 属性控制元素上滚动机制(如有)的外观(例如 overflow: scroll vs. overflow: hidden 等)。resize 属性的目的是允许控制元素上调整大小机制(例如调整大小框或小部件)的外观和功能。

注意:调整大小机制与滚动机制不同,也与任何用户代理的缩放机制无关。滚动机制允许用户确定显示元素的哪一部分内容。调整大小机制允许用户确定元素的大小。

resize 属性适用于 其计算出的 overflow 值不是 visible 滚动容器 元素。用户代理也可以无论 overflow 属性的值如何,将其应用于

resize 属性对生成内容的影响未定义。实现者不应将 resize 属性应用于生成内容。

注意:如果实现了 CSSPseudoElement 接口,resize 属性将来可能会应用于生成内容(参见 [css-pseudo-4])。

当元素被用户调整大小时,用户代理会将 widthheight 属性设置为用户所指示大小的 px 单位长度值,并将其放入元素的 style 属性 DOM 中,替换掉现有的属性声明(如有),但不包括任何 !important 声明。

如果元素仅在一个维度上调整大小,则仅设置对应的属性,而不是两者都设置。

调整大小的确切方向(即改变元素的左上角还是改变右下角)可能取决于许多 CSS 布局因素,包括元素是否为绝对定位、是否使用 rightbottom 属性定位、元素的语言是否为从右到左等。用户代理在决定如何向用户传达调整大小机制时,应考虑调整大小的方向(由 CSS 布局决定)以及平台惯例和约束。

用户代理必须允许用户在除 min-widthmax-widthmin-heightmax-height 所施加的约束之外,不带任何其他约束地调整元素大小。

注意:在某些情况下,用户尝试调整元素大小可能会显得被覆盖或被忽略,例如因为 !important 层叠声明取代了该元素 DOM 中的 style 属性 widthheight 属性。

元素 resize 属性计算值的变更不会重置因用户调整该元素大小而对 style 属性 所做的更改。

示例

例如,要使 iframe 可滚动可调整大小,可以使用以下规则

iframe,object[type^="text/"],
object[type$="+xml"],object[type="application/xml"] {
  overflow:auto;
  resize:both;
}

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

名称text-overflow
clip | ellipsis
初始值 clip
应用于 块容器
可继承
百分比 不适用
计算值 指定 关键字
规范顺序 按语法
动画类型 离散 (discrete)

此属性指定当内联内容溢出其在块容器元素(“块”)的内联进度方向上的 末端 行框边缘时,且该块的 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>
First, a box with text drawing outside of it.
CSS IS AWESOME, YES
<div style="text-overflow:clip; overflow:hidden">
CSS IS AWESOME, YES
</div>
Second, a similar box with the text clipped outside the box.
CSS IS AWESOME, YES
<div style="text-overflow:ellipsis; overflow:hidden">
CSS IS AWESOME, YES
</div>
Third, a similar box with an ellipsis representing the clipped text.
CSS IS AWESOME, YES
<div style="text-overflow:ellipsis; overflow:hidden">
NESTED
  <p>PARAGRAPH</p>
WON'T ELLIPSE.
</div>
Fourth, a box with a nested paragraph demonstrating anonymous block boxes equivalency and non-inheritance into a nested element.
NESTED

PARAGRAPH

WON’T ELLIPSE.

注意:省略号所在的行侧取决于块的 direction。例如,一个溢出隐藏的从右到左 (direction: rtl) 的块会截断 左侧 的内联内容,因此会将 text-overflow 省略号放置在 左侧 以表示该被截断的内容。

省略号与滚动界面的交互

本节适用于非 text-overflow:clip(非剪裁式 text-overflow)且具有 overflow:scroll 的元素。

当具有非剪裁式 text-overflow 的元素在文本的行内进阶维度上具有滚动溢出,并且浏览器提供了滚动机制(例如元素上的滚动条,或触控界面的滑动滚动等)时,存在一些提供更好用户体验的额外实现细节。

当元素被滚动时(例如由用户操作或 DOM 操作),会显示更多元素内容。text-overflow 的值不应影响是否显示更多元素内容。如果设置了非剪裁式 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 很棒,尤其是当你可以通过滚动查看额外文本,而不是默认让它们与其它文本重叠时。

在滚动内容时,实现者可能会调整其省略号的渲染(例如,与盒边缘对齐,而不是与行边缘对齐)。

6. 指针设备与键盘

6.1. 指针交互

6.1.1. 设置光标样式:cursor 属性

名称cursor
[<cursor-image>,]* <cursor-predefined>
初始值 auto
应用于 所有元素
可继承
百分比 不适用
计算值 如所指定,只是将任何相对 URL 转换为绝对 URL
规范顺序 按语法
动画类型 离散 (discrete)

此属性指定当光标热点位于元素的 边框边缘 内时,指针设备要显示的光标类型。

注意:根据 CSS 背景 3 § 4.1 曲线半径:border-radius 属性边框边缘border-radius 影响。

在元素重叠的情况下,哪个元素确定光标类型基于点击测试:确定光标的元素是如果在此位置启动点击将会接收点击的那个元素。

注意:点击测试的具体细节超出本规范的范围。希望点击测试能在 CSS 或 HTML 的未来版本中定义。

用户代理可以在原生用户代理控件(例如滚动条、调整大小器或其他原生 UI 小部件,例如可能在某些用户代理特定的表单元素实现中使用的那些)上忽略 cursor 属性。用户代理也可以忽略 cursor 属性并显示其选择的光标,以指示用户代理用户界面的各种状态,例如页面无响应时的忙碌光标,或用户执行文本选择时的文本光标。

注意:[HTML]cursor 属性定义了 图像映射的特殊处理

值的含义如下:

<cursor-image>
cursor 属性的第一个(可选)组件是基于图像的光标列表。如果用户代理无法处理光标列表中的第一个光标,则必须尝试处理第二个,依此类推。如果用户代理无法处理任何这些作者定义的光标,则必须使用列表末尾的基于关键字的光标。

一个 <cursor-image> 具有以下语法

<cursor-image> = <url> <number>{2}?

用户代理从 URL 指定的资源检索光标。合规的用户代理可以不支持 <url>,而支持作为超集的 <image>

用户代理必须支持以下图像文件格式

此外,用户代理应支持以下图像文件格式

用户代理也可以支持其他文件格式,包括 SVG(如 [SVG11] 中定义,以安全静态模式或安全动画模式 [SVG2]),即使它没有 自然大小

注意:CSS 工作组最初打算支持所有 SVG,无论是否具有自然大小。由于缺乏实现,对非自然大小 SVG 的支持已从强制降级为可选。

注意:在编写本规范时(2015 年春季),普通桌面浏览器中唯一支持的光标文件格式是 Microsoft 设计的 .ico 和 .cur 文件格式。为了与旧内容兼容,鼓励用户代理支持这些格式,尽管由于缺乏开放规范,无法对这些格式提出规范性要求。有关这些格式的一些信息可以在 Wikipedia 上找到。

光标图像的 默认对象大小 是用户代理定义的大小,应基于用户代理操作系统上典型光标的大小。

具体对象大小 使用 默认调整大小算法 确定。如果操作系统 无法 渲染大于给定大小的光标,则必须将大于该大小的光标缩小到 OS 支持的大小范围内,同时保持光标图像的 自然纵横比(如有)。

可选的一对 <number> 值给出了图像内确切位置(即热点)的 X 和 Y 坐标,作为图像左侧/顶部的偏移量。

注意:本规范未定义各种 <image> 类型的坐标系是如何建立的,并将这些定义推迟到 [CSS4-IMAGES]

如果省略这些值,则使用图像资源内部定义的自然热点。如果它没有自然热点,则使用图像的左上角,就像提供了 0 0 一样。

如果热点的 X 或 Y 坐标(无论是显式指定还是从图像中获取)落在光标图像之外,则必须(独立地)夹紧它们以使其适应。

<cursor-predefined>
强制性的 <cursor-predefined> 关键字指定要使用的预定义光标,或者如果提供了 <url> 且均无法成功使用时要使用的 回退 光标。

请参阅 § 6.1.1.1 预定义光标 以获取 <cursor-predefined> 关键字的全集及其含义。

示例:光标回退

这是一个使用多个光标值的示例。

:link,:visited {
    cursor: url(example.svg#linkcursor),
            url(hyper.cur),
            url(hyper.png) 2 3,
            pointer;
}

此示例将所有超链接(无论是否已访问)的光标设置为外部 SVG 光标 ([SVG11],第 16.8.3 节)。不支持 SVG 光标的用户代理将直接跳至下一个值,并尝试使用 "hyper.cur" 光标。如果该光标格式也不受支持,用户代理可以尝试使用带有显式热点的 "hyper.png" 光标。最后,如果用户代理不支持上述任何图像光标格式,用户代理将跳至最后一个值并渲染 pointer 光标。

6.1.1.1. 预定义光标

<cursor-predefined> 生成包含大多数操作系统上存在的大量预定义光标。其语法为

<cursor-predefined> = auto | default | none |
  context-menu | help | pointer | progress | wait |
  cell | crosshair | text | vertical-text |
  alias | copy | move | no-drop | not-allowed | grab | grabbing |
  e-resize | n-resize | ne-resize | nw-resize | s-resize | se-resize | sw-resize | w-resize |
  ew-resize | ns-resize | nesw-resize | nwse-resize |
  col-resize | row-resize |
  all-scroll |
  zoom-in | zoom-out

<cursor-predefined> 关键字具有以下含义和可能的渲染

通用光标
auto
用户代理根据当前上下文确定要显示的光标:auto 在可选择文本或可编辑元素上表现为 text,否则表现为 default
默认值
平台依赖的默认光标。通常显示为一个箭头。
none(无)
元素不渲染任何光标。
链接和状态光标
context-menu
光标下的对象可以使用上下文菜单。通常渲染为一个箭头,旁边带有一个小的类似菜单的图形。
help
表示光标下的对象有帮助信息。通常显示为问号或气泡。
指针 (pointer)
指示链接的指针光标。
progress
进度指示器。程序正在执行某些处理,但与 wait 不同,用户仍然可以与程序交互。通常渲染为一个旋转的海滩球,或者一个带有手表或沙漏的箭头。
wait
指示程序正忙,用户应等待。通常显示为表盘或沙漏。
选择光标
cell
指示可以选中一个单元格或一组单元格。通常渲染为一个中间带点的粗加号。
crosshair
简单的十字准线(例如类似于 "+" 号的短线段)。通常用于指示二维位图选择模式。
text
指示可以选中的文本。通常渲染为垂直 I 形光束。用户代理可能会自动为垂直文本显示水平 I 形光束/光标(例如与 vertical-text 关键字相同),或者为以任何特定角度渲染的文本显示任何角度的 I 形光束/光标。
vertical-text
指示可以选中的垂直文本。通常渲染为水平 I 形光束。
拖放光标
别名
指示将创建某物的别名/快捷方式。通常渲染为一个箭头,旁边带有一个小的弯曲箭头。
copy
指示将复制某物。通常渲染为一个箭头,旁边带有一个小的加号。
move
指示某物将被移动。
no-drop
指示拖动的项目无法放置在当前光标位置。通常渲染为一只手或指针,旁边带有一个中间带线的圆圈。
not-allowed
指示所请求的操作将不会被执行。通常渲染为一个中间带线的圆圈。
grab
指示某物可以被抓取(拖动以移动)。通常渲染为一只张开的手的背面。
grabbing
指示某物正在被抓取(拖动以移动)。通常渲染为一只手指闭合(大多不可见)的手的背面。
调整大小和滚动光标
e-resize
n-resize
ne-resize
nw-resize
s-resize
se-resize
sw-resize
w-resize
指示需要移动某个边缘。例如,当移动从盒子的东南角开始时,使用 se-resize 光标。
ew-resize
ns-resize
nesw-resize
nwse-resize
指示双向调整大小光标。
col-resize
指示该项目/列可以水平调整大小。通常渲染为指向左右两侧并由垂直条分隔的箭头。
row-resize
指示该项目/行可以垂直调整大小。通常渲染为指向上下两侧并由水平条分隔的箭头。
all-scroll
指示某物可以在任何方向上滚动。通常渲染为指向上下左右并中间带点的箭头。
缩放光标
zoom-in
zoom-out
指示某物可以被放大(放大)或缩小,通常分别渲染为中心带 "+" 或 "-" 的放大镜,用于 zoom-inzoom-out
6.1.1.2. 画布光标

文档 画布 是渲染文档的无限表面 [CSS2]。由于没有任何元素对应于画布,为了允许在不处于任何元素上时设置光标样式,画布光标重用根元素的光标。但是,如果根元素没有生成盒子(例如,如果根元素具有 display: none),则画布光标是平台相关的默认光标。

注意:一个元素可能是不可见的,但仍然生成盒子。例如,如果元素具有 visibility: hidden 但没有 display: none,则会为其生成盒子,并且其光标用于画布。

6.2. 插入符

6.2.1. 为插入符着色:caret-color 属性

名称caret-color
auto | <color>
初始值 auto
应用于 所有元素
可继承
百分比 不适用
计算值 auto 的计算值为 autocurrentColor 的计算值为 currentColor(参见 currentcolor);对于其他 <color> 值,请参阅 color 属性。
规范顺序 按语法
动画类型 颜色 按计算值
auto
用户代理应使用 currentColor。用户代理可能会自动调整插入符的颜色,以确保与周围内容有良好的可见性和对比度,可能基于 currentColor、背景、阴影等。
<color>(颜色)
插入符使用指定的颜色进行着色。

插入符是用户插入文本(以及可能的其他内容)的元素中插入点的可见指示器。此属性控制该可见指示器的颜色。

注意:插入符的形状和闪烁超出本特性的范围,因此未指定。

注意:用户代理可能有其他被视为“插入符”的事物。例如,一些用户代理可以显示“导航插入符”,它类似于插入符,但可以在不可编辑的文本中移动,并且在功能上是一个插入符。另一方面,当 cursor 属性为 auto,或者悬停在 cursor 属性为 textvertical-text 的元素上时,悬停在文本上方显示的光标图像,虽然有时类似于插入符,但不是插入符(它是光标)。

示例:一个具有 caret-color:#00aacc; 的 textarea

6.3. 键盘控制

6.3.1. 已作废:ime-mode 属性

"ime-mode" 是某些浏览器中有所实现的属性,它是有问题的,并已被本规范正式废弃。

用户代理不应支持 ime-mode 属性。

作者不得使用 ime-mode 属性。

用户仅可以将 ime-mode 属性用于修复用例,他们必须在这些用例中处理不良网站和遗留实现,例如使用如下的用户样式表规则

示例:用户首选项

input[type=password] {
  ime-mode: auto !important;
}

此示例 CSS 可以放入用户样式表文件中,以强制密码输入字段以默认方式表现。

本规范特意不尝试记录遗留 ime-mode 实现的功能或它们具体支持的内容,因为追求或推荐任何此类路径都没有意义。

注意:有几个 [HTML] 特性作者应该使用,以便向用户代理提供信息,允许它们提供更好的输入用户体验
  • 全局 lang 属性
  • input 元素的 inputmodepatterntype 属性

附录 A:致谢

本附录是信息性的

本规范大部分内容由 Tantek Çelik 从 1999 年至今编辑和撰写,最初代表微软,然后作为受邀专家,最近代表 Mozilla。

感谢代表 Bloomberg 致力于本规范的 Florian Rivoal,感谢他最近记录来自 www-style 电子邮件的议题、提出解决方案和变更的工作,特别是感谢他研究并撰写了针对 box-sizing 属性的大幅改进细节。

感谢来自以下人士的反馈和贡献:Rossen AtanassovTab AtkinsL. David BaronBert BosMatthew BrealeyRick ByersAda ChanJames CraigMichael CooperAxel DahmenMichael DayMicah DubinkoElika E.Steve FalkenburgAndrew FedonioukAl GilmanIan HicksonBjoern HoehrmannAlan HoganDavid HyattRichard IshidaSho KuwamotoYves LafonStuart LangridgeSusan LeschPeter LinssKang-Hao LuMasayuki NakanoMats PalmgrenBrad PettitChris RebertFrançois RemyAndrey RybkaSimon SapinAlexander SavenkovSebastian SchnitzenbaumerLea VerouEtan WexlerDavid WoolleyFrank YanBoris ZbarskyDomel

附录 B:变更

本附录是信息性的

相比 2018年6月21日推荐标准 (REC) 的变更

距离 2017 年 3 月 2 日候选推荐标准 (CR) 的变更

附录 C:隐私注意事项

W3C TAG 正在制定 自评问卷:安全与隐私,供规范编辑者参考性作答。

参照 需要考虑的问题

  1. 本规范是否处理个人身份信息?

    不。

  2. 本规范是否处理高价值数据?

    不。

  3. 本规范是否为跨浏览会话持久化的源引入了新状态?

    不。

  4. 本规范是否向 Web 暴露了持久的、跨源的状态?

    不。

  5. 本规范是否向一个源暴露了它目前无法访问的其他数据?

    不。

  6. 本规范是否允许源访问用户位置?

    不。

  7. 本规范是否允许源访问用户设备上的传感器?

    不。

  8. 本规范是否允许源访问用户本地计算环境的各个方面?

    不。

  9. 本规范是否允许源访问其他设备?

    不。

  10. 本规范是否向 Web 暴露临时标识符?

    不。

  11. 本规范是否区分第一方和第三方上下文中的行为?

    不。

  12. 本规范应如何在用户代理的“隐身”模式上下文中工作?

    没有区别。

  13. 本规范是否将数据持久化到用户的本地设备?

    不。

附录 D:安全注意事项

本附录是信息性的

W3C TAG 正在制定 自评问卷:安全与隐私,供规范编辑者参考性作答。

参照 需要考虑的问题

  1. 本规范是否启用了新的脚本执行/加载机制?

    支持加载,但不支持执行。cursor 属性接受可能包含待加载 URL 的 <image> 值。这些可能是包含脚本的 SVG 文档,但本规范要求不得运行脚本。

  2. 本规范是否允许源对用户代理的原生 UI 有一定程度的控制?

    是。cursorcaret-color 属性允许页面更改用户代理原生 UI 的光标和文本插入符显示。此外,outline-style 属性的 auto 值(以及由此产生的 outline 简写)允许页面潜在地在任何元素周围显示原生的聚焦元素轮廓表现。

  3. 本规范是否允许降低默认安全特性?

    不。

附录 E:HTML 默认样式表补充

本附录是信息性的

对基础样式表的潜在补充,以表达 HTML 表单控件和一些动态表现属性

:enabled:focus {
  outline: 2px inset;
}

button,
input[type=button],
input[type=reset],
input[type=submit],
input[type=checkbox],
input[type=radio],
textarea,
input,
input[type=text],
input[type=password],
input[type=image] {
  display: inline-block;
}

input[type=button],
input[type=reset],
input[type=submit],
input[type=checkbox],
input[type=radio],
input,
input[type=text],
input[type=password],
input[type=image] {
  white-space: nowrap;
}

button {
  /* white space handling of BUTTON tags in particular */
  white-space:normal;
}

input[type=reset]:lang(en) {
/* default content of HTML input type=reset button, per language */
  content: "Reset";
}

input[type=submit]:lang(en) {
/* default content of HTML input type=submit button, per language */
  content: "Submit";
}

/* UAs should use language-specific Reset/Submit rules for others. */

input[type=button],
input[type=reset][value],
input[type=submit][value] {
/* text content/labels of HTML "input" buttons */
  content: attr(value);
}

textarea {
/* white space handling of TEXTAREA tags in particular */
  white-space:pre-wrap;
  resize: both;
}

input[type=hidden] {
/* appearance of the HTML hidden text field in particular */
  display: none !important;
}

input[type=image] {
  content: attr(src,url);
  border: none;
}

select[size] {
/* HTML4/XHTML1 <select> w/ size more than 1 - appearance of list */
  display: inline-block;
  height: attr(size,em);
}

select, select[size=1] {
/* HTML4/XHTML1 <select> without size, or size=1 - popup-menu */
  display: inline-block;
  height: 1em;
  overflow: hidden;
}

select[size]:active {
/* active HTML <select> w/ size more than 1 - appearance of active list */
  display: inline-block;
}

optgroup, option {
  display: block;
  white-space: nowrap;
}

optgroup[label], option[label] {
  content: attr(label);
}

option[selected]::before {
  display: inline;
  content: check;
}

  /* Though FRAME resizing is not directly addressed by this specification,
     the following rules may provide an approximation of reasonable behavior. */

/*

frame {
  resize:both;
}
frame[noresize] {
  resize:none
}

*/

一致性

文档约定

一致性要求通过描述性断言和 RFC 2119 术语相结合来表达。本文档规范性部分中的关键词“MUST”(必须)、“MUST NOT”(不得)、“REQUIRED”(必需)、“SHALL”(应)、“SHALL NOT”(不应)、“SHOULD”(推荐)、“SHOULD NOT”(不推荐)、“RECOMMENDED”(建议)、“MAY”(可以)和“OPTIONAL”(可选)应按照 RFC 2119 中的描述进行解释。然而,为了可读性,这些词在本文档中不以全大写形式出现。

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

本规范中的示例均以“例如”一词引入,或者通过 class="example" 与规范性文本隔开,如下所示

这是一个说明性示例。

说明性注释以“Note”一词开头,并使用 class="note" 与规范性文本隔开,如下所示

注意,这是一个说明性注释。

建议(Advisements)是规范性章节,旨在引起特别注意,并使用 <strong class="advisement"> 与其他规范性文本区分开来,如下所示: 用户代理必须提供可访问的替代方案。

一致性类别

本规范为三类一致性定义了一致性要求。

样式表
一份 CSS 样式表
渲染器
一种 用户代理 (UA),它解释样式表的语义并渲染使用它们的文档。
创作工具
一种 用户代理 (UA),用于编写样式表。

如果样式表包含的所有使用本模块定义语法的语句,根据通用 CSS 语法及本模块定义的各功能语法均有效,则该样式表符合本规范。

如果渲染器除了按相应规范解释样式表外,还通过正确解析本规范定义的所有功能并相应地渲染文档来支持这些功能,则该渲染器符合本规范。然而,由于设备限制导致 UA 无法正确渲染文档,并不意味着该 UA 不符合规范。(例如,UA 无需在单色显示器上渲染颜色。)

如果创作工具编写的样式表根据通用 CSS 语法及本模块中各功能的语法是句法正确的,并符合本模块中描述的所有其他样式表一致性要求,则该创作工具符合本规范。

部分实现

为了使作者能够利用前向兼容的解析规则来指定后备值,CSS 渲染器 **必须** 将其无法使用支持级别的任何 @规则、属性、属性值、关键字和其他语法结构视为无效(并 适当忽略)。特别地,用户代理 **不得** 在单一多值属性声明中选择性地忽略不支持的组件值而保留支持的值:如果任何值被视为无效(因为不支持的值必须如此),CSS 要求忽略整个声明。

不稳定和专有特性的实现

为了避免与未来稳定的 CSS 功能发生冲突,CSS 工作组建议在实施不稳定功能和私有扩展遵循最佳实践

非实验性实现

一旦规范达到候选推荐阶段,非实验性实现即可成为可能,实现者应发布他们能够证明根据规范正确实现的任何 CR 级别特性的无前缀实现。

为建立并保持 CSS 在不同实现间的互操作性,CSS 工作组请求非实验性的 CSS 渲染器在发布任何 CSS 功能的无前缀实现之前,向 W3C 提交一份实现报告(并在必要时提交用于该实现报告的测试用例)。提交给 W3C 的测试用例需经 CSS 工作组审阅和修正。

有关提交测试用例和实现报告的详细信息,请访问 CSS 工作组网站 https://w3org.cn/Style/CSS/Test/。问题可发送至 public-css-testsuite@w3.org 邮件列表。

索引

本规范定义的术语

通过引用定义的术语

引用

规范性引用

[CSS-BACKGROUNDS-3]
Elika Etemad; Brad Kemper. CSS 背景与边框模块 3 级 (CSS Backgrounds and Borders Module Level 3). 2024年3月11日. CRD. URL: https://w3org.cn/TR/css-backgrounds-3/
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. 2022年1月13日. CR. URL: https://w3org.cn/TR/css-cascade-5/
[CSS-COLOR-4]
Tab Atkins Jr.; Chris Lilley; Lea Verou. CSS 颜色模块第 4 级. 2026 年 3 月 31 日. CRD. URL: https://w3org.cn/TR/css-color-4/
[CSS-COLOR-5]
Chris Lilley; Una Kravets; Lea Verou. CSS 颜色模块第 5 级. 2026 年 3 月 25 日. WD. URL: https://w3org.cn/TR/css-color-5/
[CSS-IMAGES-3]
Tab Atkins Jr.; Elika Etemad; Lea Verou. CSS 图像模块第 3 级. 2023 年 12 月 18 日. CRD. URL: https://w3org.cn/TR/css-images-3/
[CSS-OVERFLOW-3]
Elika Etemad; Florian Rivoal. CSS 溢出模块 Level 3. 2025 年 10 月 7 日. WD. URL: https://w3org.cn/TR/css-overflow-3/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS 值与单位模块 3 级 (CSS Values and Units Module Level 3). 2024年3月22日. CRD. URL: https://w3org.cn/TR/css-values-3/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS 值与单位模块 4 级 (CSS Values and Units Module Level 4). 2024年3月12日. WD. URL: https://w3org.cn/TR/css-values-4/
[CSS-WRITING-MODES-4]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 4. 2019年7月30日. CR. URL: https://w3org.cn/TR/css-writing-modes-4/
[CSS2]
Bert Bos; et al. 层叠样式表 2 级修订版 1 (CSS 2.1) 规范 (Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification). 2011年6月7日. REC. URL: https://w3org.cn/TR/CSS2/
[HTML]
Anne van Kesteren; et al. HTML 标准. Living Standard. URL: https://html.whatwg.cn/multipage/
[PNG]
Chris Lilley; et al. 便携式网络图形 (PNG) 规范(第三版). 2025年6月24日. REC. URL: https://w3org.cn/TR/png-3/
[RFC2119]
S. Bradner. RFC 中用于指示要求级别的关键词. 1997年3月. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SVG11]
Erik Dahlström; et al. 可缩放矢量图形 (SVG) 1.1 (第二版). 2011 年 8 月 16 日. REC. URL: https://w3org.cn/TR/SVG11/
[SVG2]
Amelia Bellamy-Royds; et al. Scalable Vector Graphics (SVG) 2. 2018年10月4日. CR. URL: https://w3org.cn/TR/SVG2/
[UAX29]
Josh Hadley. Unicode Text Segmentation. 2025年8月17日. Unicode Standard Annex #29. URL: https://www.unicode.org/reports/tr29/tr29-47.html
[WEB-ANIMATIONS-1]
Brian Birtles; 等人. Web Animations. 2023年6月5日. WD. URL: https://w3org.cn/TR/web-animations-1/

参考资料

[CSS-CASCADE-4]
Elika Etemad; Tab Atkins Jr.. CSS 层叠与继承第 4 级. 2022年1月13日. CR. URL: https://w3org.cn/TR/css-cascade-4/
[CSS-GAPS-1]
Kevin Babbitt. CSS 间隙装饰模块第 1 级. 2026 年 2 月 27 日. WD. URL: https://w3org.cn/TR/css-gaps-1/
[CSS-PSEUDO-4]
Elika Etemad; Alan Stearns. CSS 伪元素模块 Level 4. 2025 年 6 月 27 日. WD. URL: https://w3org.cn/TR/css-pseudo-4/
[CSS-WRITING-MODES-3]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 3. 2019年12月10日. REC. URL: https://w3org.cn/TR/css-writing-modes-3/
[CSS1]
Håkon Wium Lie; Bert Bos. 层叠样式表,Level 1. 2018 年 9 月 13 日. REC. URL: https://w3org.cn/TR/CSS1/
[CSS4-IMAGES]
Elika Etemad; Tab Atkins Jr.; Lea Verou. CSS 图像模块 4 级 (CSS Images Module Level 4). 2025年9月30日. WD. URL: https://w3org.cn/TR/css-images-4/

属性索引

名称初始值应用于继承百分比动画类型 (Animation type)规范顺序计算值
box-sizing content-box | border-boxcontent-box所有接受 width 或 height 的元素不适用离散 (discrete)按语法指定的值
caret-color auto | <color>auto所有元素不适用按计算值着色按语法auto 的计算值为 auto;currentColor 的计算值为 currentColor(参见 currentcolor);其他 <color> 值请参见 color 属性。
cursor [<cursor-image>,]* <cursor-predefined>auto所有元素不适用离散 (discrete)按语法如所指定,只是将任何相对 URL 转换为绝对 URL
大纲 [ <'outline-color'> || <'outline-style'> || <'outline-width'> ]见各个属性所有元素不适用见各个属性按语法见各个属性
outline-color <color> | invertinvert所有元素不适用按计算值着色按语法invert 的计算值为 invert;currentColor 的计算值为 currentColor(参见 currentcolor);其他 <color> 值请参见 color 属性。
outline-offset <length>(长度)0 所有元素不适用按计算值计算长度按语法绝对单位(px 或物理单位)的 <length> 值。绝对长度
outline-style auto | <border-style>none(无)所有元素不适用离散 (discrete)按语法按指定值
outline-width <line-width>medium所有元素不适用按计算值计算长度按语法绝对长度,作为边框宽度吸附;如果 outline-style 为 none,则为 0。
resize none | both | horizontal | verticalnone(无)overflow 不为 visible 的元素,即滚动容器,以及可选的置换元素(如图像、视频和 iframe)不适用离散 (discrete)按语法作为指定的关键字
text-overflow clip | ellipsisclip块容器不适用离散 (discrete)按语法作为指定的关键字