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 上檢視此頁面 • 報告此內容的問題