CSS 层叠变量模块一级的自定义属性

1. 引言

本节不具有规范性。

大型文档或应用程序 （甚至是小型的）可能包含相当多的CSS。 CSS文件中的许多值将是重复数据； 例如， 一个网站可能会建立一个颜色方案， 并在整个网站中重复使用三到四种颜色。 修改这些数据可能是困难且容易出错的， 因为它分散在CSS文件中 （并且可能跨多个文件）， 可能不适合查找和替换。

此模块引入了一组自定义的作者定义属性，统称为自定义属性， 允许作者为具有自定义名称的属性分配任意值， 以及var() 函数， 允许作者在文档中的其他属性中使用这些值。 这使得阅读大型文件更容易， 因为看似任意的值现在有了信息丰富的名称， 并且使编辑这些文件更容易且不易出错， 因为只需在 自定义属性中更改一次值， 更改将自动传播到该变量的所有使用位置。

1.1. 值定义

本规范遵循CSS属性定义惯例，来自[CSS2]，使用值定义语法，来自[CSS-VALUES-3]。 本规范未定义的值类型定义于CSS值与单位 [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;
}
/* 剩余的CSS文件 */
#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>我从根元素继承了蓝色！</p>
<div>我直接设置了绿色！</div>
<div id='alert'>
  我直接设置了红色！
  <p>我也是红色的, 因为继承了！</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； 也就是说，从第一个逗号到函数结束的内容都被视为回退值。

/* 在组件的样式中: */ 
.component .header { 
  color: var(--header-color, blue); 
} 
.component .text {
  color: var(--text-color, black); 
} 

/* 在大型应用程序的样式中: */ 
.component { 
  --text-color: #080; 
  /* header-color 没有设置， 
     因此仍然是蓝色， 
     即回退值 */ 
} 

如果某个属性包含一个或多个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. Invalid Variables

当 自定义属性 的值是 保证无效值 时， 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);
  /* 等 */
} 

为了避免此类攻击， 用户代理必须对 var() 函数展开的令牌流长度施加用户代理定义的限制。 如果 var() 展开到的令牌流超过此限制， 它会导致正在展开的属性在 计算值时间无效。

本规范未定义应施加的大小限制。 然而，考虑到自定义属性可能含有一千字节或更多文本的合法用例， 建议将限制设得相对较高。

注意：由于资源限制，用户代理可以违反标准的原则在此处依然适用； 用户代理可能分别对自定义属性的支持长度或标识符的支持长度有其他限制。 本节特别指出这种攻击， 因为其历史悠久， 并且在第一次检查时， 其组成部分似乎都不算太大。

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-wide关键字 （仅通过提供它作为回退时可能）。

• 澄清了注册自定义属性在计算值时无效时的行为类似于非自定义属性。

• 使具有var()的长属性也会触发其短属性不可序列化， 就像具有挂起替换值的长属性已经这样做了一样。

• 要求用户代理防御指数替换攻击。

• 定义了如何序列化自定义属性的值 （以前只规定了属性名称的序列化）。

5.3. 自2014年5月6日最后一次呼叫工作草案以来的变更

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

• 链接到DOM中“区分大小写”的定义。

• 添加了使用带有:lang()的变量进行简单国际化的示例。

• 澄清了自定义属性中使用var()必须符合var()语法规则。

6. 致谢

非常感谢CSS工作组的多位成员多年来对变量梦想的支持，特别是Daniel Glazman和David Hyatt。 感谢多个邮件列表成员为这一版本的变量开发做出的贡献，特别是 Brian Kardell， David Baron， François Remy， Roland Steiner， 和Shane Stephens。

7. 隐私考量

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

8. 安全考量

§ 3.3 安全处理过长变量提到了一个长期存在的 拒绝服务攻击，该攻击可以针对类似“宏展开”机制发起， 例如var()函数， 并要求采取防御措施。