@property

基线 2024

新可用

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

@property CSS at-规则 是 CSS Houdini API 集的一部分。它允许开发者显式定义其 CSS 自定义属性，从而进行属性类型检查和约束、设置默认值，以及定义自定义属性是否可以继承值。

@property 规则表示在样式表中直接注册自定义属性，无需运行任何 JS。有效的 @property 规则会导致注册自定义属性，就像使用等效参数调用了 registerProperty() 一样。

语法

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

描述符

语法

描述属性允许的语法。可以是 <length>、<number>、<percentage>、<length-percentage>、<color>、<image>、<url>、<integer>、<angle>、<time>、<resolution>、<transform-function> 或 <custom-ident>，或数据类型和关键字值的列表。

+（空格分隔）和 #（逗号分隔）乘数表示预期一个值列表，例如 <color># 表示预期语法的逗号分隔的 <color> 值列表。

竖线 (|) 可以为预期语法创建“或”条件，例如 <length> | auto 接受 <length> 或 auto，而 <color># | <integer># 预期逗号分隔的 <color> 值列表或逗号分隔的 <integer> 值列表。

继承

控制 @property 指定的自定义属性注册是否默认继承。

初始值

设置属性的初始值。

@property 规则必须同时包含 syntax 和 inherits 描述符；如果两者中任何一个缺失，则整个 @property 规则无效并被忽略。 initial-value 描述符也是必需的，除非语法是 * 通用语法定义（例如，syntax: "*"）。如果需要 initial-value 描述符但省略了，则整个 @property 规则无效并被忽略。

未知描述符无效并被忽略，但不会使 @property 规则无效。

正式语法

@property = 
  @property <custom-property-name> { <declaration-list> }

示例

在此示例中，我们定义了两个自定义属性 --item-size 和 --item-color，我们将使用它们来定义以下三个项目的尺寸（宽度和高度）和背景颜色。

html
<div class="container">
  <div class="item one">Item one</div>
  <div class="item two">Item two</div>
  <div class="item three">Item three</div>
</div>

以下代码使用 CSS 的 @property 规则定义了一个名为 --item-size 的自定义属性。该属性将初始值设置为 40%，并将有效值限制为仅 <percentage> 值。这意味着，当用作项目大小的值时，其大小始终相对于其父元素的大小。该属性是可继承的。

css
@property --item-size {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 40%;
}

我们使用 JavaScript 而不是 CSS 定义了第二个自定义属性 --item-color。JavaScript 的 registerProperty() 方法等效于 @property 规则。该属性被定义为具有 aqua 的初始值，仅接受 <color> 值，并且不可继承。

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

我们使用这两个自定义属性来设置项目的样式。

css
.container {
  display: flex;
  height: 200px;
  border: 1px dashed black;

  /* set custom property values on parent */
  --item-size: 20%;
  --item-color: orange;
}

/* use custom properties to set item size and background color */
.item {
  width: var(--item-size);
  height: var(--item-size);
  background-color: var(--item-color);
}

/* set custom property values on element itself */
.two {
  --item-size: initial;
  --item-color: inherit;
}

.three {
  /* invalid values */
  --item-size: 1000px;
  --item-color: xyz;
}

这两个自定义属性 --item-size: 20% 和 --item-color: orange; 设置在父元素 container 上，覆盖了定义这些自定义属性时设置的 40% 和 aqua 默认值。大小被设置为可继承；颜色不可继承。

对于第一个项目，没有设置任何这些自定义属性。--item-size 是可继承的，因此使用其父元素 container 上设置的 20% 值。另一方面，属性 --item-color 不可继承，因此不会考虑父元素上设置的 orange 值。而是使用默认初始值 aqua。

对于第二个项目，为两个自定义属性都设置了 CSS 全局关键字，这些关键字对于所有值类型都是有效值，因此无论 syntax 描述符的值如何，它们都是有效的。--item-size 设置为 initial 并使用 @property 声明中设置的 initial-value: 40%;。initial 值表示使用属性的 initialValue 值。--item-color 设置为 inherit，显式地从其父元素继承 orange 值，即使自定义属性设置为不可继承。这就是第二个项目为橙色的原因。

对于第三个项目，--item-size 值被设置为 1000px。虽然 1000px 是一个 <length> 值，但 @property 声明要求该值必须是 <percentage>，因此该声明无效且被忽略，这意味着使用父元素上设置的可继承的 20%。xyz 值也无效。由于 registerProperty() 将 --item-color 设置为不可继承，因此使用默认初始值 aqua，而不是父元素的 orange 值。

规范

规范
CSS 属性和值 API 第 1 级
# at-property-rule

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅