使用 CSS 属性与值 API

Baseline 2024
新推出

自 ⁨2024 年 7 月⁩起,此功能可在最新的设备和浏览器版本上使用。此功能可能无法在较旧的设备或浏览器上使用。

CSS 属性和值 APICSS Houdini API 集合的一部分 — 允许注册 CSS 自定义属性,从而实现属性类型检查、默认值以及属性继承或不继承其值。

注册自定义属性

注册自定义属性可以告诉浏览器该自定义属性应如何表现;允许哪些类型,自定义属性是否继承其值,以及自定义属性的默认值是什么。有两种注册属性的方法:在 JavaScript 中或在 CSS 中。

CSS.registerProperty

以下代码使用 CSS.registerProperty 注册一个名为 --my-prop自定义属性--my-prop 将使用 CSS 颜色语法,其默认值为 #c0ffee,并且不会继承其值。

js
window.CSS.registerProperty({
  name: "--my-prop",
  syntax: "<color>",
  inherits: false,
  initialValue: "#c0ffee",
});

@property

可以在 CSS 中进行相同的注册。以下代码使用 @property at-rule 注册一个名为 --my-prop自定义属性--my-prop 将使用 CSS 颜色语法,其默认值为 #c0ffee,并且不会继承其值。

css
@property --my-prop {
  syntax: "<color>";
  inherits: false;
  initial-value: #c0ffee;
}

使用已注册的自定义属性

注册属性的一个优点是浏览器现在知道如何处理你的自定义属性,例如通过过渡!当一个属性未注册时,浏览器不知道如何处理它,因此它假设可以使用任何值,因此无法对其进行动画处理。然而,当一个属性具有已注册的语法时,浏览器可以围绕该语法进行优化,包括能够对其进行动画处理!

在此示例中,自定义属性 --registered 已使用 <color> 语法注册,然后用于线性渐变。当悬停或聚焦时,该属性将过渡到另一种颜色。请注意,过渡与已注册属性一起工作,而与未注册属性不工作!

HTML

html
<button class="registered">Background Registered</button>
<button class="unregistered">Background Not Registered</button>

CSS

css
.registered {
  --registered: #c0ffee;
  background-image: linear-gradient(to right, white, var(--registered));
  transition: --registered 1s ease-in-out;
}

.registered:hover,
.registered:focus {
  --registered: #b4d455;
}

.unregistered {
  --unregistered: #c0ffee;
  background-image: linear-gradient(to right, white, var(--unregistered));
  transition: --unregistered 1s ease-in-out;
}

.unregistered:hover,
.unregistered:focus {
  --unregistered: #b4d455;
}

button {
  height: 40vh;
  display: block;
  width: 100%;
  font-size: 3vw;
}

JavaScript

js
window.CSS.registerProperty({
  name: "--registered",
  syntax: "<color>",
  inherits: false,
  initialValue: "red",
});

结果

虽然在功能上不完全准确,但区分上面示例中未注册属性和已注册属性的一个好方法是,在尝试为 height 进行动画处理时,将 <custom-ident> 与数字进行比较。你无法从 auto 过渡或动画到数字,因为浏览器在计算之前不知道 auto 的值。对于未注册的属性,浏览器同样不知道该值可能是什么,直到计算完成,因此无法设置从一个值到另一个值的过渡。然而,当注册后,你已经告诉了浏览器它应该期望什么类型的值,因为它知道了这一点,就可以正确设置过渡。

注意事项

注册属性有两个注意事项。第一个是,一旦属性被注册,就无法更新它,尝试使用 JavaScript 重新注册它将抛出错误,指示它已被定义。

其次,与标准属性不同,已注册的属性在解析时不会进行验证。相反,它们在计算时进行验证。这意味着在检查元素的属性时,无效值不会显示为无效,并且在有效属性之后包含无效属性不会回退到有效属性。然而,无效属性会回退到其注册的默认值。

浏览器兼容性