使用 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 重新註冊它將丟擲錯誤,指示它已被定義。

其次,與標準屬性不同,已註冊的屬性在解析時不會進行驗證。相反,它們在計算時進行驗證。這意味著在檢查元素的屬性時,無效值不會顯示為無效,並且在有效屬性之後包含無效屬性不會回退到有效屬性。然而,無效屬性會回退到其註冊的預設值。

瀏覽器相容性