CSS 属性和值 API

CSS 属性与值 API 模块定义了一种注册新 CSS 属性的方法，可以定义属性的数据类型、继承行为以及可选的初始值。此 API 扩展了用于层叠变量的 CSS 自定义属性模块，该模块允许作者使用双破折号语法（--）在 CSS 中定义自定义属性。CSS 属性与值 API 是CSS Houdini API 家族的一部分。

自定义属性允许你在整个项目中重用值，以简化复杂或重复的样式表。基本的自定义属性在用于层叠变量的 CSS 自定义属性模块中定义。CSS 属性与值 API 扩展了该模块，可以通过 CSS 中的@property at-rule，或者通过 JavaScript 的CSS.registerProperty 方法，为自定义属性添加元数据。

无论是在 CSS 还是 JavaScript 中注册，为自定义属性设置元数据都提供了一个预期的、浏览器可以根据上下文使用的，定义了初始值，并允许你控制继承的数据类型。

CSS 属性与值 API 的自定义属性注册比更基本的 CSS 层叠变量自定义属性声明更健壮，尤其是在过渡和动画值方面，因为浏览器可以内插此类自定义值，而使用双破折号语法（--）的属性更像字符串替换。

属性与值 API 实战

要查看如何通过 API 使用自定义属性和值，请将鼠标悬停在下面的框上。

CSS.registerProperty({
  name: "--stop-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "cornflowerblue",
});

.box {
  padding: 1rem;
  width: 90%;
  height: 4rem;
  font-family: sans-serif;
  font-size: large;
  color: white;
  border-radius: 0.5rem;
}

.box {
  background: linear-gradient(to right, var(--stop-color), lavenderblush);
  transition: --stop-color 2s;
}

.box:hover {
  --stop-color: aquamarine;
}

<div class="box"><p>Linear gradient with transition</p></div>

此框有一个背景，由从--stop-color（自定义属性）到lavenderblush的线性渐变组成。--stop-color 的值最初设置为cornflowerblue，但是当你将鼠标悬停在框上时，--stop-color会在两秒内过渡到aquamarine（linear-gradient(to right, aquamarine, lavenderblush)）。

参考

@ 规则

@property
- 语法描述符
  - + 和 # 乘数
  - | 组合符
- inherits 描述符
- initial-value 描述符

接口和 API

指南

使用 CSS 属性与值 API: 解释如何在 CSS 和 JavaScript 中注册自定义属性，并提供处理未定义和无效值、回退和继承的提示。
CSS Houdini: Houdini 资源参考指南，包括 CSS 模块、API 指南和外部资源。
Houdini APIs: 解释 CSS Houdini 是什么及其优点，以及可用 API 及其状态列表。

规范

规范
CSS 属性和值 API Level 1

另见

帮助改进 MDN

了解如何贡献

此页面最后由MDN 贡献者于 2025 年 7 月 14 日修改。

在 GitHub 上查看此页面 • 报告此内容的问题