Skip to content
FEE
Frontend Engineering Essentials
Senior Level
Hardened· 2026-07

[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>,平滑地過渡。

html
<!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 登錄變數可防止它洩漏到巢狀元件中。外層卡片的間距變數保持在本地;內層卡片獨立使用自己的值。

html
<!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 在每一幀更新值,因為漸層函式呼叫本身是單一的不透明字串,兩個不同的角度值會產生兩個不同的字串,彼此之間沒有東西可以插值。

html
<!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 優先使用 @property at-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)、算術驗證等具型別的操作。

漸層動畫問題 ​

這是自訂屬性最常見的意外。開發者寫道:

css
.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
// 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 宣告是權威的回退。

css
@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 檢查來保護:

css
@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 的瀏覽器接收靜態的回退顏色。支援的瀏覽器接收動畫版本。

瀏覽器支援 ​

瀏覽器首次支援版本備註
Chrome85透過 CSS Properties and Values API
Firefox128@property 與 CSS.registerProperty() 同時出貨
Safari16.4at-rule 與 JS 形式均支援
Edge85基於 Chromium

CSS 功能偵測:

css
@supports (syntax: '<angle>') {
  /* 支援 @property at-rule */
}

JavaScript 功能偵測:

js
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 登錄這些屬性可確保型別安全和樣式查詢條件中可預測的回退行為。

參考資料 ​