[FEE-11201] @property — 具型別的自訂屬性
INFO
為 CSS 自訂屬性登錄型別,你就能解鎖動畫、安全的回退值和繼承控制。瀏覽器接著就知道這個值代表什麼,而不再把它當成不透明的字串。
Baseline Newly Available
Chrome 85+、Firefox 128+、Safari 16.4+ 支援。舊版瀏覽器請採漸進增強。
背景
CSS 自訂屬性(--color: red)是原始文字。瀏覽器儲存你指派的任何字串,並在計算值(computed value)時代換它。這個設計是刻意的:自訂屬性被構想為通用的變數系統,而非型別屬性系統。靈活性是目標。
但這種靈活性是有代價的:
- 無法動畫。 針對未登錄自訂屬性的
transition或@keyframes規則什麼都不做。瀏覽器無法在兩個不透明字串之間插值。它不知道--hue是角度、顏色,還是 "purple" 這個單詞,因此無法計算過渡到 37% 時的值。 - 沒有保證的初始值。 若規則參照
var(--spacing)而--spacing從未在當前作用域設定,其值是空字串。任何接收到這個代換的屬性在計算值時會變成無效值,而且是靜默發生的。版面破損,主控台沒有任何錯誤。 - 繼承永遠開啟。 每個自訂屬性預設都會繼承。設定在父元素上的
--card-padding會流入每個子元素,包括其他元件內部深層巢狀的子元素。除非手動重置,否則元件層級的變數會持續洩漏。
只要你嘗試透過自訂屬性做任何動畫,這些代價立刻就會浮現。建立一個背景色相應在懸停時變化的按鈕,transition: --hue 0.4s 什麼都不會發生:瀏覽器只有兩個不透明字串 "220deg" 和 "280deg",沒有辦法在它們之間插值。下方的範例一會完整走過修正方式。
@property 是 CSS Houdini Properties & Values API Level 1 中的 CSS at-rule,它解決了上述三個問題。宣告型別、初始值和繼承策略,之後瀏覽器就將該屬性視為第一級具型別的值來處理。
視覺對比
| 行為 | 未登錄的自訂屬性 | 透過 @property 登錄 |
|---|---|---|
| 儲存的值 | 原始 token 字串,無型別 | 符合 syntax 的具型別值 |
transition / @keyframes | 靜默忽略,無法插值 | 依宣告型別插值 |
| 空值或無效值 | 空字串;可能使整條宣告失效 | 回退到 initial-value,不會破損 |
| 繼承 | 永遠繼承到後代元素 | inherits: true | false,由你決定 |
範例
範例一 — 使用具型別角度屬性的漸層動畫
這是 @property 的標準示範。左側按鈕沒有登錄;它的懸停過渡什麼都不做。右側按鈕將 --hue 登錄為 <angle>,平滑地過渡。
<!DOCTYPE html>
<html lang="zh-TW">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@property — 漸層動畫</title>
<style>
body {
font-family: system-ui, sans-serif;
padding: 48px;
display: flex;
gap: 48px;
align-items: flex-start;
background: #f5f5f5;
}
.demo {
display: flex;
flex-direction: column;
align-items: center;
gap: 12px;
}
.label {
font-size: 0.875rem;
color: #555;
text-align: center;
}
/* 按鈕基底 */
.btn {
padding: 14px 28px;
border: none;
border-radius: 8px;
font-size: 1rem;
font-weight: 600;
color: #fff;
cursor: pointer;
}
/* 未登錄:過渡被忽略 */
.btn-unregistered {
--hue-start: 220;
background: hsl(220deg 80% 50%);
transition: --hue-start 0.4s ease; /* 什麼都不做 */
}
.btn-unregistered:hover {
background: hsl(280deg 80% 50%); /* 瞬間跳躍 */
}
/* 已登錄:過渡插值角度 */
@property --hue {
syntax: '<angle>';
inherits: false;
initial-value: 220deg;
}
.btn-registered {
--hue: 220deg;
background: hsl(var(--hue) 80% 50%);
transition: --hue 0.4s ease;
}
.btn-registered:hover {
--hue: 280deg;
}
</style>
</head>
<body>
<div class="demo">
<button class="btn btn-unregistered">懸停我</button>
<p class="label">無 @property<br>瞬間跳躍,無動畫</p>
</div>
<div class="demo">
<button class="btn btn-registered">懸停我</button>
<p class="label">有 @property<br>平滑動畫色相 220deg → 280deg</p>
</div>
</body>
</html>關鍵洞察:未登錄按鈕上的 transition: --hue 0.4s 語法有效,但瀏覽器沒有任何東西可以插值,因此什麼都不會發生。在登錄的按鈕上,瀏覽器知道 --hue 是 <angle>,因此它在每一幀生成中間值。
範例二 — 使用 inherits: false 進行元件隔離
用 inherits: false 登錄變數可防止它洩漏到巢狀元件中。外層卡片的間距變數保持在本地;內層卡片獨立使用自己的值。
<!DOCTYPE html>
<html lang="zh-TW">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@property — inherits: false</title>
<style>
body {
font-family: system-ui, sans-serif;
padding: 32px;
background: #f0f0f0;
}
/* 將 spacing 登錄為不繼承的 <length> */
@property --card-padding {
syntax: '<length>';
inherits: false;
initial-value: 16px;
}
/* 卡片元件 */
.card {
background: #fff;
border: 1px solid #ddd;
border-radius: 8px;
padding: var(--card-padding);
max-width: 400px;
}
.card .title {
font-size: 1rem;
font-weight: 700;
margin: 0 0 8px;
}
.card .body {
font-size: 0.875rem;
color: #555;
margin: 0;
}
/* 外層卡片:大內距 */
.card-outer {
--card-padding: 32px;
}
/* 內層卡片:小內距 */
.card-inner {
--card-padding: 12px;
margin-top: 16px;
background: #f9f9f9;
}
</style>
</head>
<body>
<div class="card card-outer">
<h2 class="title">外層卡片(padding: 32px)</h2>
<p class="body">
此卡片設定了 --card-padding: 32px。因為 --card-padding
以 inherits: false 登錄,內層卡片不會繼承這個值。
</p>
<div class="card card-inner">
<h2 class="title">內層卡片(padding: 12px)</h2>
<p class="body">
此卡片獨立設定 --card-padding: 12px。
若沒有 inherits: false,它會從外層卡片繼承 32px。
</p>
</div>
</div>
</body>
</html>沒有 @property 時,內層 .card-inner 需要明確地重置 --card-padding 以避免繼承外層的值。有了 inherits: false,內層卡片預設從 initial-value(16px)開始。它只顯示 --card-padding: 12px,是因為自己的宣告設定了那個值;外層卡片的 32px 從未傳到這裡。
範例三 — 動畫 conic-gradient 進度環
範例一登錄色相是示範;登錄角度來驅動 conic-gradient() 才是多數團隊實際會用到的模式:進度環、載入中的旋轉圖示,以及動畫漸層邊框。在 @property 之前,要動畫這些元件的漸層填色都需要用 JavaScript 在每一幀更新值,因為漸層函式呼叫本身是單一的不透明字串,兩個不同的角度值會產生兩個不同的字串,彼此之間沒有東西可以插值。
<!DOCTYPE html>
<html lang="zh-TW">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@property — 圓錐漸層進度環</title>
<style>
body {
font-family: system-ui, sans-serif;
padding: 48px;
background: #f5f5f5;
}
@property --angle {
syntax: '<angle>';
inherits: false;
initial-value: 0deg;
}
.ring {
width: 160px;
height: 160px;
border-radius: 50%;
background: conic-gradient(#4f46e5 var(--angle), #e5e7eb 0deg);
transition: --angle 1.2s ease;
}
.ring.loaded {
--angle: 270deg;
}
</style>
</head>
<body>
<div class="ring" id="progress"></div>
<script>
// 在第一次繪製後才觸發過渡,確保瀏覽器
// 有一個已提交的「起始」值(0deg)可以插值。
requestAnimationFrame(() => {
document.getElementById('progress').classList.add('loaded');
});
</script>
</body>
</html>將 --angle 登錄為 <angle>,並過渡 --angle,conic-gradient() 的色標就會在每一幀重新計算,因為瀏覽器是在動畫餵給它的具型別值,而不是漸層字串本身。Temani Afif 對動畫化 CSS 漸層的文章讓這個技巧廣為流傳。
最佳實踐
- MUST 登錄任何將使用
transition或@keyframes進行動畫的自訂屬性。未登錄的屬性無法插值;動畫靜默地什麼都不做。 - MUST 在
inherits: false時提供initial-value。規格書要求如此:若沒有回退值,當屬性未設定時瀏覽器沒有安全的值可以使用。 - SHOULD 對元件作用域的主題變數設定
inherits: false,確保這些變數 MUST NOT 傳播到後代元件。明確的非繼承性可防止共享相同變數名稱的元件之間發生靜默洩漏。 - SHOULD 優先使用
@propertyat-rule 形式而非CSS.registerProperty(),用於不在執行時期變動的靜態宣告。at-rule 與其他 CSS 放在一起,不需要執行 script,也更容易審查。 - SHOULD 在 CSS 數學中使用具型別的自訂屬性。將
--spacing登錄為<length>能讓你得到經過計算、具型別檢查的長度,並保證有initial-value可回退。未登錄的--spacing只要值本身是合法的長度,仍能在calc()中正常運作;但值若格式錯誤或未設定,整條宣告會在沒有回退值的情況下靜默失效。 - SHOULD NOT 在有更具體型別可用時使用
syntax: '*'。萬用字元型別在動畫和型別安全方面等同於未登錄屬性;你只獲得了initial-value保證。
設計思維
為何自訂屬性是字串
CSS 自訂屬性於 2012–2015 年在 CSS Custom Properties for Cascading Variables Module Level 1 中被引入。設計目標是一個與現有級聯相容的輕量變數機制。瀏覽器逐字儲存原始 token 序列,並在 var(--name) 出現的地方代換它,不解析值。這允許一個自訂屬性在任何宣告上下文中使用。你可以在一條規則中將長度指派給 --x,在另一條規則中指派顏色給 --x。
缺點:瀏覽器無法對值進行推理。它不知道持有的是什麼型別,因此無法執行動畫、夾值(clamping)、算術驗證等具型別的操作。
漸層動畫問題
這是自訂屬性最常見的意外。開發者寫道:
.button {
background: linear-gradient(var(--from-color), var(--to-color));
transition: background 0.4s;
}background 的過渡效果不起作用。linear-gradient(red, blue) 和 linear-gradient(blue, red) 是不同的字串值,瀏覽器將它們視為離散值,無法插值。漸層無法透過過渡 background 來動畫。
修正方式是動畫漸層內部的具型別屬性,而非漸層本身。範例一登錄了 --hue 並過渡它,而非 hsl() 的輸出;範例三對 conic-gradient() 色標做了同樣的事。兩種情況下,色彩函式都會在每一幀根據插值後的具型別值重新計算。
Houdini 的淵源
@property 源自 CSS Houdini 工作組,一個旨在向 JavaScript 開放瀏覽器渲染內部機制的 W3C 聯合計劃。Properties & Values API Level 1 最初將 CSS.registerProperty() 指定為 JavaScript 方法;@property at-rule 後來作為語意相同的純 CSS 宣告形式被加入。Firefox 在 128 版(2024 年 7 月發布)同時出貨了 CSS.registerProperty() 和 @property at-rule。Chrome 在 78 版出貨了 CSS.registerProperty(),在 85 版出貨了 @property at-rule;Safari 在 16.4 版同時出貨了兩種形式。
型別檢查與靜默回退
當登錄的屬性接收到不符合其宣告 syntax 的值時,瀏覽器回退到 initial-value,不會拋出任何錯誤。例如,若 --brand-hue 登錄為 <angle>,而某條規則設定了 --brand-hue: potato,瀏覽器靜默地使用 220deg(或任何 initial-value 的值)。這是刻意設計的結果:遇到型別不符時,級聯會優雅地降級到已知的值,而不會整個中斷。
深入探討
完整的語法值型別
@property 支援以下 syntax 描述符:
| 型別 | 範例值 |
|---|---|
<color> | red、#ff0、hsl(200 80% 50%) |
<length> | 16px、1rem |
<length-percentage> | 50%、calc(100% - 16px) |
<number> | 0、1.5、-3 |
<percentage> | 50%、100% |
<angle> | 90deg、1rad、0.5turn |
<time> | 200ms、1s |
<resolution> | 96dpi、2dppx |
<transform-function> | rotate(45deg)、scale(1.5) |
<transform-list> | rotate(45deg) scale(1.5) |
<image> | url(...)、漸層函式 |
<url> | url(image.png) |
<integer> | 0、42、-1 |
<custom-ident> | 任何有效的 CSS 識別符 |
<string> | "hello" |
* | 任意值(與未登錄相同) |
請注意,單獨的 <length> 會拒絕百分比:以 syntax: '<length>' 登錄的屬性會將 50% 視為無效值並回退到 initial-value。當值可能是長度也可能是百分比時,請使用 <length-percentage>。
也支援列表語法變體:<color>+ 表示一個或多個以空格分隔的顏色;<length># 表示一個或多個以逗號分隔的長度。
@property vs CSS.registerProperty()
兩種形式在語意上完全相同。at-rule 形式適合靜態宣告,因為它與其他 CSS 放在一起,不需要 script,也不受 JavaScript 執行順序影響。當需要動態登錄屬性時使用 CSS.registerProperty(),例如元件框架在執行時期生成變數名稱的情況。
// JS 形式,與 @property at-rule 語意相同
CSS.registerProperty({
name: '--brand-hue',
syntax: '<angle>',
inherits: false,
initialValue: '220deg'
});注意 JS API 中的駝峰式 initialValue,對比 at-rule 中的連字號 initial-value。
@property 是全域的,不受 layer 限制
登錄的屬性是全域的。將 @property 放在 @layer 區塊內並不會將它限制在那個 layer 的作用域內:登錄仍適用於整個文件。這與 @keyframes 和 @font-face 在 layer 內的行為一致。請相應地規劃你的屬性名稱,以避免跨元件衝突。
型別檢查行為
當具型別屬性接收到無效值時,它靜默地回退到 initial-value。這與一般無效的 CSS 值不同:一般無效值會回退到繼承值,或屬性自身的初始值。對於登錄的屬性,明確的 initial-value 宣告是權威的回退。
@property --opacity-level {
syntax: '<number>';
inherits: false;
initial-value: 1;
}
.element {
--opacity-level: not-a-number; /* 對 <number> 無效 */
opacity: var(--opacity-level); /* 解析為 1,即 initial-value */
}漸進增強
CSS.registerProperty() 和 @property at-rule 在所有現代瀏覽器中均受支援。對於必須支援舊版環境的專案,at-rule 可以用 @supports 檢查來保護:
@supports (syntax: '<angle>') {
@property --hue {
syntax: '<angle>';
inherits: false;
initial-value: 220deg;
}
.btn {
--hue: 220deg;
background: hsl(var(--hue) 80% 50%);
transition: --hue 0.4s ease;
}
}
/* 不支援 @property 的瀏覽器的回退 */
.btn {
background: hsl(220deg 80% 50%);
}
.btn:hover {
background: hsl(280deg 80% 50%);
}不支援 @property 的瀏覽器接收靜態的回退顏色。支援的瀏覽器接收動畫版本。
瀏覽器支援
| 瀏覽器 | 首次支援版本 | 備註 |
|---|---|---|
| Chrome | 85 | 透過 CSS Properties and Values API |
| Firefox | 128 | @property 與 CSS.registerProperty() 同時出貨 |
| Safari | 16.4 | at-rule 與 JS 形式均支援 |
| Edge | 85 | 基於 Chromium |
CSS 功能偵測:
@supports (syntax: '<angle>') {
/* 支援 @property at-rule */
}JavaScript 功能偵測:
const supportsRegisterProperty = 'registerProperty' in CSS;截至 2026 年,@property 在所有主流瀏覽器中已是 Baseline Newly Available。最後跟上的是 Firefox,它在 128 版(2024 年 7 月發布)同時出貨了 @property at-rule 和 CSS.registerProperty();沒有任何 Firefox 版本是其中一種形式可用、另一種不可用的。對於必須支援 128 版之前 Firefox 的專案,請用上方展示的 @supports (syntax: '<angle>') 檢查來保護 at-rule,並提供靜態回退,因為兩種登錄形式在 128 版之前都不可用。
延伸閱讀
- FEE-11200 CSS @scope:
@scope與@property在元件主題設定上互補。使用@property登錄具型別、不繼承的自訂屬性,再使用@scope透過:scope限制哪些元素接收初始值。兩者結合讓你不需要 Shadow DOM 就能實現完全具型別的元件本地主題變數。 - FEE-11002 Container Queries:CSS 樣式查詢(
@container style(--variant: featured))查詢容器上自訂屬性的值。透過@property登錄這些屬性可確保型別安全和樣式查詢條件中可預測的回退行為。
參考資料
- MDN contributors, "@property," MDN Web Docs (2024). https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@property
- Una Kravets, "@property: giving superpowers to CSS variables," web.dev (2020). https://web.dev/articles/at-property
- Una Kravets, "@property: Next-gen CSS variables now with universal browser support," web.dev (2024). https://web.dev/blog/at-property-baseline
- Tab Atkins-Bittner, Alan Stearns, and Greg Whitworth (eds.), "CSS Properties and Values API Level 1," W3C Houdini Task Force, Editor's Draft. https://drafts.css-houdini.org/css-properties-values-api/
- Temani Afif, "We Can Finally Animate CSS Gradient," DEV Community (2021, updated 2024). https://dev.to/afif/we-can-finally-animate-css-gradient-kdk