CSS 层叠变量自定义属性模块第 1 级

1. 简介

本节不具有规范性。

大型文档或应用程序（甚至小型项目）可能包含相当多的 CSS。CSS 文件中的许多值通常是重复数据；例如，一个网站可能建立了一种配色方案，并在全站范围内重复使用三到四种颜色。修改这些数据可能既困难又容易出错，因为它们分散在 CSS 文件中（甚至可能分布在多个文件中），且可能无法通过“查找与替换”轻松处理。

本模块引入了一系列由作者定义的自定义属性，统称为自定义属性，允许作者为自定义名称的属性分配任意值；同时引入了 var() 函数，允许作者在文档其他地方的属性中使用这些值。这使得阅读大型文件变得更加容易，因为看似随意的值现在有了信息丰富的名称；同时也使得编辑此类文件变得更加简单且不易出错，因为只需在自定义属性中修改一次值，更改就会自动传播到该变量的所有使用处。

1.1. 值定义

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

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

2. 定义自定义属性：--* 属性家族

本规范定义了一组开放式的属性，称为自定义属性，除其他用途外，它们还用于定义 var() 函数的替代值。

用户代理应在所有介质（包括非可视介质）上支持此属性。

任何名称以两个连字符（U+002D HYPHEN-MINUS）开头的属性都是自定义属性，例如 --foo。<custom-property-name> 产生式对应于此：它定义为任何 <dashed-ident>（以两个连字符开头的有效标识符），但 -- 本身除外，它是保留给 CSS 未来使用的。自定义属性仅供作者和用户使用；CSS 永远不会赋予它们超出本文所述的含义。

:root {
  --main-color: #06c;
  --accent-color: #006;
}
/* The rest of the CSS file */
#foo h1 {
  color: var(--main-color);
}

与其他 CSS 属性不同，自定义属性名称不是 ASCII 大小写不敏感的。相反，自定义属性名称仅在彼此完全相同时才相等。

操作系统、键盘或输入法有时会使用不同的码点序列对视觉上相同的文本进行编码。建议作者选择能避免潜在混淆的变量名称，或使用转义等手段来确保外观相似的序列是相同的。示例见 [CHARMOD-NORM] 第 2.3 节。

--fijord: red;
--fijord: green;
--fijord: blue;

.test {
  background-color: var(--fijord);
}

自定义属性不会被 all 属性重置。我们将来可能会定义一个重置所有变量的属性。

CSS 宽关键词可在自定义属性中使用，其含义与在任何其他属性中相同。

注意：也就是说，它们在层叠值时正常解释，并没有作为自定义属性的值被保留，因此不会被相应的变量替换。

注意：虽然本模块重点在于使用自定义属性和 var() 函数来创建“变量”，但它们也可以作为实际的自定义属性使用，由脚本解析并操作。预计 CSS 扩展规范 [CSS-EXTENSIONS] 将扩展这些用例并使其更易于实现。

自定义属性是普通属性，因此它们可以声明在任何元素上，通过正常的继承和层叠规则解析，可以使用 @media 和其他条件规则进行条件化，可以在 HTML 的 style 属性中使用，可以通过 CSSOM 读取或设置等。

值得注意的是，它们甚至可以过渡或动画化，但由于 UA 无法解释其内容，它们始终使用任何其他无法智能插值的成对值所采用的“在 50% 处翻转”的行为。然而，任何在 @keyframes 规则中使用的自定义属性都会变得受动画影响，这会影响在动画属性中通过 var() 函数引用它时的处理方式。

受动画影响是“传染性的”：引用了受动画影响属性的自定义属性也会变得受动画影响。

:root {
  --header-color: #06c;
}

h1 { background-color: var(--header-color); }

:root { --color: blue; }
div { --color: green; }
#alert { --color: red; }
* { color: var(--color); }

<p>I inherited blue from the root element!</p>
<div>I got green set directly on me!</div>
<div id='alert'>
  While I got red set directly on me!
  <p>I’m red too, because of inheritance!</p>
</div>

:root,
:root:lang(en) {--external-link: "external link";}
:root:lang(el) {--external-link: "εξωτερικός σύνδεσμος";}

a[href^="http"]::after {content: " (" var(--external-link) ")"}

2.1. 自定义属性值语法

允许的自定义属性语法极其宽松。<declaration-value> 产生式匹配任何一个或多个令牌序列，只要该序列不包含 <bad-string-token>、<bad-url-token>、不匹配的 <)-token>、<]-token> 或 <}-token>，或者顶层的 <semicolon-token> 令牌或值为“!”的 <delim-token> 令牌。

此外，如果自定义属性的值包含 var() 引用，该 var() 引用必须根据指定的 var() 语法有效。否则，该自定义属性无效，必须忽略。

注意：此定义连同通用 CSS 语法规则，暗示自定义属性值从不包含不匹配的引号或括号，因此在重新序列化时，对较大的语法结构（如封闭的样式规则）没有任何影响。

注意：自定义属性可以包含尾随的 !important，但这会被 CSS 解析器自动从属性值中移除，并使该自定义属性在 CSS 层叠中变得“重要”。换句话说，对顶层“!”字符的禁止并不妨碍 !important 的使用，因为 !important 在语法检查发生前已被移除。

--foo: if(x > 5) this.width = 10;

自定义属性的值，以及代入自定义属性中的 var() 函数的值，是大小写敏感的，且必须保留其作者给定的原始大小写。（许多 CSS 值是 ASCII 大小写不敏感的，用户代理可以通过将它们“规范化”为单一大小写来利用这一点，但自定义属性不允许这样做。）

2.2. 保证无效值

自定义属性的初始值是一个保证无效值。正如 § 3 使用层叠变量：var() 标记法中所定义，使用 var() 来代入以其为值的自定义属性，会使引用它的属性变得在计算值时无效。

此值序列化为空字符串，但实际上将空值写入自定义属性（如 --foo: ;）是一个有效的（空）值，而非保证无效值。如果由于某种原因想要手动将变量重置为保证无效值，可以使用关键字 initial 来实现。

2.3. 解决依赖循环

自定义属性几乎完全保持未求值状态，除了它们允许并求值其值中的 var() 函数。这可能会产生循环依赖，其中自定义属性使用引用自身的 var()，或者两个或多个自定义属性各自尝试引用对方。

对于每个元素，创建一个有向依赖图，包含每个自定义属性的节点。如果自定义属性 prop 的值包含一个引用属性 var 的 var() 函数（包括在 var() 的回退参数中），则在 prop 和 var 之间添加一条边。边可能从自定义属性指向其自身。

如果依赖图中存在循环，则循环中的所有自定义属性都是在计算值时无效的。

注意：参与依赖循环的已定义属性，要么其值中最终包含无效变量（从而变得在计算值时无效），要么定义了它们自己的循环处理方式（如 font-size 使用 em 值）。它们不会像自定义属性那样计算为保证无效值。

:root {
  --main-color: #c06;
  --accent-background: linear-gradient(to top, var(--main-color), white);
}

:root {
  --one: calc(var(--two) + 20px);
  --two: calc(var(--one) - 20px);
}

需要特别注意的是，自定义属性在计算值时解析其值中的任何 var() 函数，这发生在继承值之前。通常，循环依赖仅在同一元素上的多个自定义属性相互引用时发生；在元素树中较高位置的元素上定义的自定义属性永远不会导致与元素树中较低位置的元素上定义的属性产生循环引用。

<one><two><three /></two></one>
<style>
one   { --foo: 10px; }
two   { --bar: calc(var(--foo) + 10px); }
three { --foo: calc(var(--bar) + 10px); }
</style>

3. 使用层叠变量：var() 标记法

自定义属性的值可以通过 var() 函数代入另一个属性的值中。var() 的语法为

var() = var( <custom-property-name> , <declaration-value>? )

作为通常 逗号省略规则 的一个例外，该规则要求在不分隔值时省略逗号，在 var() 中，必须将一个后面没有任何内容的裸逗号视为有效，表示一个空的回退值。

注意：也就是说，var(--a,) 是一个有效的函数，它指定如果 --a 自定义属性无效或缺失，则应将 var() 替换为空。

var() 函数可用于元素中任何属性的值的任何部分。 var() 函数不能用作属性名称、选择器，或除属性值之外的任何其他内容。（这样做通常会产生无效语法，或者产生一个其含义与变量无关的值。）

.foo {
  --side: margin-top;
  var(--side): 20px;
}

函数的第一个参数是要替换的 自定义属性 的名称。函数的第二个参数（如果提供）是一个回退值，当所引用的 自定义属性 的值为 保证无效值 时，该回退值将作为替换值使用。

注意：回退值的语法与 自定义属性 一样，允许使用逗号。例如，var(--foo, red, blue) 定义了一个 red, blue 的回退值；也就是说，第一个逗号和函数末尾之间的任何内容都被视为回退值。

/* In the component’s style: */
.component .header {
  color: var(--header-color, blue);
}
.component .text {
  color: var(--text-color, black);
}

/* In the larger application’s style: */
.component {
  --text-color: #080;
  /* header-color isn’t set,
     and so remains blue,
     the fallback value */
}

如果一个属性包含一个或多个 var() 函数，且这些函数在语法上是有效的，则必须假定整个属性的语法在解析时是有效的。只有在计算值时，即在 var() 函数被 替换 之后，才会进行语法检查。

要在属性值中 替换 var()

1. 如果 var() 函数的第一个参数所命名的 自定义属性 是 动画污染的，并且 var() 函数被用于一个 不可动画的 属性中，则在算法的剩余部分中将该 自定义属性 视为具有其初始值。
2. 如果 var() 函数的第一个参数所命名的 自定义属性 的值不是初始值，则用相应 自定义属性 的值替换 var() 函数。
3. 否则，如果 var() 函数具有作为其第二个参数的回退值，则用回退值替换 var() 函数。如果回退中存在任何 var() 引用，也请对它们进行 替换。
4. 否则，包含 var() 函数的属性在 计算值时无效。

   注意：其他事项也可能使属性在 计算值时无效。

.foo {
  --gap: 20;
  margin-top: var(--gap)px;
}

.foo {
  --gap: 20;
  margin-top: calc(var(--gap) * 1px);
}

var() 函数在计算值时进行 替换。如果一个声明在所有 var() 函数被替换后不符合其声明的语法，则该声明在 计算值时无效。

如果一个声明在所有 var() 函数被替换后，仅包含一个 CSS 范围内的关键字（以及可能的空白字符），则其值确定方式就像该关键字一直作为其 指定值 一样。

:root { --looks-valid: 20px; }
p { background-color: var(--looks-valid); }

p { color: var(--does-not-exist, initial); }

3.1. 无效变量

当 自定义属性 的值为 保证无效值 时，var() 函数不能将其用于替换。尝试这样做会使声明在 计算值时无效，除非指定了有效的回退。

如果声明包含一个引用 自定义属性 且值为 保证无效值 的 var()（如上所述），或者它使用有效的 自定义属性，但属性值在替换其 var() 函数后无效，则该声明可能 在计算值时无效。发生这种情况时，计算值是以下之一，具体取决于属性的类型

属性是一个非注册的 自定义属性

属性是一个具有 通用语法 的 注册自定义属性

计算值为 保证无效值。

否则

属性的继承值或其初始值，取决于属性是否被继承，就好像属性的值已被指定为 unset 关键字一样。

:root { --not-a-color: 20px; }
p { background-color: red; }
p { background-color: var(--not-a-color); }

注意：存在 在计算值时无效 的概念，是因为变量不能像其他语法错误那样“尽早失败”，所以当用户代理意识到属性值无效时，它已经丢弃了其他级联值。

3.2. 简写属性中的变量

在将 简写属性 解析为其组件长属性，以及从其组件长属性序列化 简写属性 时，var() 函数会产生一些复杂性。

如果 简写属性 的值中包含 var() 函数，则与其关联的 长属性 必须填充一个特殊的、对作者不可见的 待替换值，该值指示简写包含一个变量，因此在变量被 替换 之前，无法确定长属性的值。

然后，该值必须正常级联。在计算值时，即在 var() 函数最终被替换后，必须解析简写，并在此点赋予长属性适当的值。

注意：当简写属性在没有 var() 的情况下编写时，它会在解析时被解析并分离为其组件 长属性；然后长属性参与 级联，而 简写属性 则或多或少被丢弃。然而，当简写包含 var() 时，则无法做到这一点，因为 var() 可以被任何内容替换。

待替换值 必须序列化为空字符串（如果 API 允许观察它们）。

简写属性 通过收集其组件 长属性 的值并合成为一个能解析为同一组值的字符串来序列化。

如果给定 简写 的所有组件 长属性 都是来自同一原始简写值的 待替换值，则 简写属性 必须序列化为该原始（包含 var()）值。

否则，如果给定 简写 的任何组件 长属性 是 待替换值，或者其自身包含尚未替换的 var() 函数，则 简写属性 必须序列化为空字符串。

3.3. 安全处理过长的变量

如果实现不当，var() 函数可用于“十亿笑话攻击”的变体

.foo {
  --prop1: lol;
  --prop2: var(--prop1) var(--prop1);
  --prop3: var(--prop2) var(--prop2);
  --prop4: var(--prop3) var(--prop3);
  /* etc */
}

为了避免此类攻击，UA 必须对 var() 函数展开成的标记流的允许长度实施 UA 定义的限制。如果 var() 展开后的标记流超过此限制，它反而会使它正在展开的属性在 计算值时无效。

本规范未定义应实施何种长度限制。然而，由于自定义属性存在包含一千字节或更多文本的有效用例，因此建议将限制设置得相对较高。

注意：UA 因资源限制而允许违反标准的一般原则在这里仍然普遍适用；UA 可能单独对它们能支持的自定义属性的长度或能支持的标识符的大小有限制。本节特别指出此攻击是因为其由来已久，并且它可以在所有片段初看时都似乎不大，但仍能被执行。

4. API

所有 自定义属性 声明 都设置了 大小写敏感标志。

注意：自定义属性不会以驼峰命名形式出现在 CSSStyleDeclaration 对象上，因为它们的名称可能同时包含大写和小写字母，这表示不同的自定义属性。自动驼峰转换所执行的那种文本转换与此不兼容。它们仍然可以通过 getPropertyValue() 等通过其正确名称进行访问。

4.1. 序列化自定义属性

自定义属性名称必须序列化为作者提供的确切代码点序列，包括不改变大小写。

注意：对于非自定义属性，属性名称限制在 ASCII 范围内并且是 ASCII 大小写不敏感的，因此实现通常将名称小写化进行序列化。

自定义属性 的指定值必须序列化为 作者指定的确切值。其他属性中可能发生的简化，例如删除注释、规范化空格、从其值重新序列化数值标记等，不得发生。

自定义属性 的计算值也必须序列化为 作者指定的确切值，除了替换任何 var() 函数外。

--y: /* baz */;
--x: /* foo */ var(--y) /* bar */;

5. 变更

5.1. 自 2021 年 11 月 11 日 CR 草案以来的变更

• 明确了自定义属性适用于所有伪元素（包括那些具有限制属性列表的伪元素）

• 添加了示例以说明结合字符、连字等带来的问题

• 加强了关于使用不同代码点序列但外观相似的变量名称的措辞

• 通过使用视觉上更具区分度的语言（英语和希腊语）作为示例来阐明一个示例

• 将安全与隐私拆分为独立的章节

5.2. 自 2015 年 12 月 3 日 CR 以来的变更

• 既然 [css-syntax-3] 会自动从声明值中修剪空白字符，那么使 <declaration-value> 在自定义属性语法中变为可选，以便仍然允许空变量。（问题 774）

• 同样，使 var() 中的空回退变为有效。

• '-' 属性保留供 CSS 将来使用。

• 添加了“动画污染”概念，以防止不可动画属性使用变量来引入动画能力。

• 定义了 保证无效值，使自定义属性的初始值以及循环或替换失败的结果更直观，并允许失败在替换过程中传播，直到最终被回退捕获。

• 定义了循环触发 计算值时无效 的行为。

• 允许变量解析为 CSS 范围内的关键字（仅通过作为回退提供才有可能）。

• 明确了 注册自定义属性 在 计算值时无效 时表现得像非自定义属性。

• 使带有 var() 的长属性也会触发其简写变为不可序列化，就像带有待替换值的长属性一样。

• 要求 UA 防御指数级替换攻击。

• 定义了如何序列化自定义属性的 值（之前仅指定了属性名称的序列化）。

5.3. 自 2014 年 5 月 6 日末次呼吁工作草案以来的变更

• 定义了当简写使用变量时长属性的序列化。

• 添加了对 DOM 的“大小写敏感”定义的链接。

• 添加了将变量与 :lang() 一起使用以进行简单 i18n 的示例。

• 明确了在自定义属性中使用 var() 必须符合 var() 语法。

6. 致谢

衷心感谢 CSS 工作组的几位成员多年来保持变量梦想的延续，特别是 Daniel Glazman 和 David Hyatt。感谢邮件列表上的多位人士帮助促成了这一变量实现的开发，特别是 Brian Kardell、David Baron、François Remy、Roland Steiner 和 Shane Stephens。

7. 隐私考量

本规范定义了一种纯粹作者级别的机制，用于在他们控制的页面内传递样式信息。因此，没有新的隐私注意事项。

8. 安全考量

§ 3.3 安全处理过长的变量 提到了一个可以针对“宏扩展”类机制（例如 var() 函数）进行的长期存在的拒绝服务攻击，并强制要求对此类攻击进行防御。