Skip to content
FEE
Frontend Engineering Essentials
Senior Level

[FEE-11002] Container Queries — 尺寸與樣式查詢 ​

INFO

透過查詢元件實際佔用的空間(而非視口),讓任何元件真正具備響應式能力;並透過查詢祖先元素的自訂屬性,以宣告式方式進行佈景主題設定,不需要 JavaScript。

Baseline Newly Available

Size queries supported in Chrome 105+, Firefox 110+, Safari 16+. Style queries supported in Chrome 111+, Firefox 127+, Safari 18+. Use progressive enhancement for older browsers.

背景 ​

Media queries 是 CSS 響應式設計的第一套機制,但它們對元件而言回答了錯誤的問題。Media query 問的是「視口有多寬?」——然而,位於 300 px 側邊欄中的卡片元件,與橫跨 800 px 主內容區的同一張卡片,兩者所在的視口是相同的。視口寬度一致;元件的可用空間卻截然不同。

業界採用了各種變通方式:

  1. JavaScript ResizeObserver — 對元件附加觀察器,在 JS 中計算尺寸類別,將 data attribute 或 class 寫入 DOM,再以 CSS 目標該 class。雖然有效,但會造成版面抖動(layout thrashing)、耗費執行時間,且在 SSR 環境中需要水合(hydration)才能讓樣式正確套用。
  2. CSS Grid auto-fit / auto-fill — 讓欄位在空間不足時自動收合,但無法觸發元件內部的版面切換,例如將圖片從水平排列改為垂直排列。
  3. 由父層傳遞尺寸 props — 在元件化框架中,傳入明確的 size="compact" prop。雖然有效,但會將版面知識洩漏至父層,並將父子元件的實作細節耦合在一起。

Container Queries 將這個決策移入 CSS。元件宣告自己參與 containment;瀏覽器在版面計算中追蹤其尺寸;元件本身的樣式規則對該尺寸做出回應——不需要 JavaScript、不需要觀察器、不需要切換 class。

樣式查詢(style queries)進一步延伸這個概念:查詢的不是數字(尺寸),而是值(自訂屬性)。父層在包裝元素上設定 --variant: featured;子元素使用 @container style(--variant: featured) 查詢,套用對應的變體樣式。這將由 props 驅動的樣式設定帶入純 CSS 中。

情境 ​

你正在建立一個設計系統中的卡片元件,它會被用於三種情境:

  • 窄側邊欄(約 280 px 可用空間)
  • 雙欄文章格線(約 420 px 可用空間)
  • 全寬主視覺區塊(約 900 px 可用空間)

在側邊欄中,卡片必須垂直堆疊(縮圖在上、文字在下)。在文章格線與主視覺區塊中,應切換為水平版面。在主視覺區塊中,還應增大字體尺寸並顯示「精選」標籤。

使用 media queries 無法表達這一點——無論卡片放在哪個位置,視口都是相同的。使用 Container Queries,你可以為每個插槽設定包含上下文(containment context),讓卡片對實際可用寬度與主視覺包裝元素上設定的 --variant 自訂屬性做出回應。

最佳實踐 ​

  • MUST 在存在多個巢狀容器時,以 container-name 為容器命名。未命名的 @container 規則會匹配最近的具有 containment context 的祖先——在深度巢狀的版面中,這可能靜默地解析到錯誤的容器。
  • SHOULD 對大多數元件版面使用 container-type: inline-size。它只追蹤行內(水平)維度,這正是大多數版面切換所需的,且比 container-type: size 消耗更少資源。
  • MUST NOT 對仰賴內容決定塊軸(垂直)高度的元素套用 container-type。inline-size 和 size 都會在塊方向套用版面包含(layout containment),使元素的高度與其內容脫鉤——若未設定明確高度,元素將塌陷為零高度。
  • SHOULD 使用 container 簡寫(container: card / inline-size)一次宣告名稱與類型。
  • SHOULD 使用樣式查詢處理佈景主題變體(--variant: compact、--theme: dark),而非透過 JavaScript 切換 CSS class。父層設定一個自訂屬性;所有關心此屬性的子元素可各自獨立查詢。
  • MUST 採用漸進增強。將 @container 規則包在 @supports (container-type: inline-size) 區塊中,使舊版瀏覽器顯示預設(通常是堆疊式)版面,而非破損的版面。
  • SHOULD NOT 將容器名稱命名為與該容器樣式查詢所用的自訂屬性相同——兩者命名空間不同,但名稱相同會造成程式碼混亂。

設計思維 ​

Media queries 為何在元件層級失效 ​

Media query 回報的是視口的幾何資訊。嵌入版面中的元件無法控制——且通常無法預測——它將佔用視口的多少空間。同一組 .card 標記可能在側邊欄以 280 px 渲染,也可能以 840 px 作為主視覺;這兩種情況的視口都是例如 1280 px。min-width: 600px 的 media query 對兩者都會觸發,但側邊欄的卡片根本沒有空間進行水平排版。

根本矛盾在於:media queries 用頁面層級的答案回答了元件層級的問題。

JavaScript 如何填補這個空缺 ​

ResizeObserver API(2020 年,已廣泛支援)讓開發者得以觀察元素本身的尺寸並做出回應。典型模式如下:

  1. 觀察 .card 的尺寸變化。
  2. 在回呼函式中讀取 contentRect.width。
  3. 切換 class(例如 card--horizontal)。
  4. CSS 以 .card--horizontal 為目標套用版面。

雖然有效,但存在幾個脆弱之處:觀察器在版面計算之後才觸發(導致第二次版面計算),必須等 JavaScript 設定完成才有效果(破壞伺服器渲染的 HTML),且每個元件實例都需要自己的觀察器。在一個有 50 張卡片的列表中,就是 50 個活躍的觀察器。

Container Queries 作為 CSS 的解答 ​

container-type 告訴瀏覽器,此元素的後代樣式可能依賴該元素的尺寸。瀏覽器隨即將該元素的尺寸納為一級版面基本單位(first-class layout primitive)——就像追蹤視口尺寸以供 media queries 使用一樣。@container 規則在與其他所有規則相同的版面計算過程中被評估,在繪製之前執行。不需要第二次版面計算,不需要觀察器回呼,不需要切換 class。

樣式查詢將同樣的模型延伸至自訂屬性。父層宣告一個自訂屬性;瀏覽器使該值在容器上可被查詢。子元素透過 @container style(--prop: value) 選擇加入。這等同於向下傳遞 prop——但不需要任何 JavaScript 框架,且任意深度的後代都可以獨立查詢。

關鍵的概念轉變:元件自己宣告自己的響應式行為。它不依賴父層了解其內部實作,也不依賴 JavaScript 設置尺寸 class。元件是自包含且可移植的。

範例 ​

範例一 — 尺寸查詢:水平 / 垂直卡片版面切換 ​

當容器達到 400 px 時,.card 元件從垂直排版(預設,圖片在上)切換為水平排版(圖片在左、內容在右)。

html
<!DOCTYPE html>
<html lang="zh-TW">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Container Query — 卡片</title>
  <style>
    /* ── 版面 ─────────────────────────────────────────────── */
    .layout {
      display: grid;
      grid-template-columns: 280px 1fr;
      gap: 24px;
      padding: 24px;
      font-family: system-ui, sans-serif;
    }

    /* ── 包含上下文 ──────────────────────────────────────── */
    .sidebar,
    .main {
      container-type: inline-size;
    }

    .sidebar { background: #f5f5f5; padding: 16px; }
    .main    { background: #fafafa; padding: 16px; }

    /* ── 卡片 — 預設(垂直 / 窄版) ──────────────────────── */
    .card {
      border: 1px solid #ddd;
      border-radius: 8px;
      overflow: hidden;
      background: #fff;
    }

    .card__image {
      width: 100%;
      aspect-ratio: 16 / 9;
      object-fit: cover;
      display: block;
      background: #c9d6e3; /* 佔位顏色 */
    }

    .card__body {
      padding: 12px;
    }

    .card__title {
      margin: 0 0 8px;
      font-size: 1rem;
    }

    .card__desc {
      margin: 0;
      font-size: 0.875rem;
      color: #555;
    }

    /* ── 卡片 — 容器 >= 400 px 時切換為水平版面 ─────────── */
    @container (min-width: 400px) {
      .card {
        display: grid;
        grid-template-columns: 160px 1fr;
      }

      .card__image {
        aspect-ratio: unset;
        height: 100%;
      }
    }
  </style>
</head>
<body>
  <div class="layout">

    <!-- 窄容器:卡片維持垂直 -->
    <aside class="sidebar">
      <article class="card">
        <div class="card__image" role="img" aria-label="佔位圖片"></div>
        <div class="card__body">
          <h2 class="card__title">側邊欄卡片</h2>
          <p class="card__desc">此容器寬 280 px — 卡片維持垂直排版。</p>
        </div>
      </article>
    </aside>

    <!-- 寬容器:卡片切換為水平 -->
    <main class="main">
      <article class="card">
        <div class="card__image" role="img" aria-label="佔位圖片"></div>
        <div class="card__body">
          <h2 class="card__title">主內容卡片</h2>
          <p class="card__desc">此容器寬度超過 400 px — 卡片切換為水平排版。</p>
        </div>
      </article>
    </main>

  </div>
</body>
</html>

.sidebar 和 .main 包裝元素都宣告了 container-type: inline-size。.card 本身不包含任何頁面版面知識——它只是回應被給予的空間。

範例二 — 樣式查詢:不需要 JavaScript 的佈景主題變體 ​

包裝元素上的 --theme: dark 自訂屬性以宣告式方式驅動卡片顏色。不需要切換 class,不需要 JS。

html
<!DOCTYPE html>
<html lang="zh-TW">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>樣式查詢 — 佈景主題變體</title>
  <style>
    body {
      font-family: system-ui, sans-serif;
      padding: 24px;
      display: flex;
      gap: 24px;
    }

    /* ── 包裝元素透過自訂屬性設定變體 ──────────────────── */
    /* 樣式查詢不需要 container-type */
    .wrapper-light { --theme: light; }
    .wrapper-dark  { --theme: dark;  background: #1a1a2e; padding: 16px; border-radius: 8px; }

    /* ── 卡片預設值(淺色佈景主題)──────────────────────── */
    .card {
      border: 1px solid #ddd;
      border-radius: 8px;
      padding: 16px;
      background: #ffffff;
      color: #111;
      width: 220px;
    }

    .card__title {
      margin: 0 0 8px;
      font-size: 1rem;
    }

    .card__desc {
      margin: 0;
      font-size: 0.875rem;
      color: #555;
    }

    /* ── 透過樣式查詢套用深色變體 ──────────────────────── */
    @container style(--theme: dark) {
      .card {
        background: #16213e;
        border-color: #0f3460;
        color: #e0e0e0;
      }

      .card__desc {
        color: #9e9e9e;
      }
    }
  </style>
</head>
<body>

  <div class="wrapper-light">
    <article class="card">
      <h2 class="card__title">淺色卡片</h2>
      <p class="card__desc">渲染於 .wrapper-light — 套用預設顏色。</p>
    </article>
  </div>

  <div class="wrapper-dark">
    <article class="card">
      <h2 class="card__title">深色卡片</h2>
      <p class="card__desc">渲染於 .wrapper-dark — 樣式查詢套用深色顏色。</p>
    </article>
  </div>

</body>
</html>

注意 .wrapper-dark 並未宣告 container-type。樣式查詢對任何具有自訂屬性的元素均有效——不需要 containment context。

深入探討 ​

容器查詢單位 ​

Container Queries 引入了一組相對於查詢容器(而非視口)解析的單位:

單位解析為
cqw容器行內尺寸的 1%
cqh容器塊軸尺寸的 1%
cqi容器行內尺寸的 1%(別名)
cqb容器塊軸尺寸的 1%(別名)
cqmincqi 與 cqb 中較小者
cqmaxcqi 與 cqb 中較大者

可用於隨元件可用空間縮放的字體大小與間距:

css
.card__title {
  /* 字體大小隨容器增大,在 14px 至 22px 之間縮放 */
  font-size: clamp(0.875rem, 4cqi, 1.375rem);
}

容器巢狀 ​

當一個容器置於另一個容器內部時,它對其後代而言成為獨立的 containment context:

css
.page-layout {
  container: page / inline-size;
}

.sidebar {
  container: sidebar / inline-size;
}

.widget {
  /* 此 @container 規則解析至 .sidebar,而非 .page-layout */
  /* 因為 .sidebar 是最近的具有 containment 的祖先 */
}

未命名的 @container 規則永遠解析至最近任何設有 container-type 的祖先。精確命名容器可避免意外解析至錯誤的祖先。

樣式查詢目前的限制 ​

截至 2026 年,樣式查詢只能查詢自訂屬性(CSS 變數),無法查詢計算值:

css
/* 有效 — 自訂屬性查詢 */
@container style(--variant: featured) { ... }

/* 無效 — 計算值查詢(目前無任何瀏覽器支援) */
@container style(color: red) { ... }
@container style(width: 300px) { ... }

CSS 工作小組已討論將樣式查詢擴展至計算值,但瀏覽器實作尚未出貨。目前撰寫的程式碼只能查詢自訂屬性。

效能:版面包含的影響 ​

container-type: inline-size 會在塊方向套用版面包含(layout containment)。這有兩個值得注意的副作用:

  1. 塊軸高度與內容脫鉤 — 容器的塊軸尺寸由其本身的 sizing context 決定,而非其內容。若未指定高度,容器將塌陷為零。這是刻意設計:它讓瀏覽器在只有容器行內尺寸改變時,略過容器子樹的版面計算。
  2. 堆疊上下文(stacking context) — 版面包含會建立新的堆疊上下文(類似具有 z-index 的 position: relative)。這可能影響容器內部絕對定位子元素的 z-index 行為。

container-type: size 在兩個維度都套用包含,消耗更多資源。僅在 @container 規則需要查詢塊軸維度(例如 min-height)時才使用它。

container 簡寫 ​

css
/* 完整寫法 */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

/* 等效簡寫 */
.card-wrapper {
  container: card / inline-size;
}

簡寫語法為 container: <name> / <type>,必須使用斜線分隔。若要宣告類型而不命名,寫法為 container: none / inline-size。

瀏覽器支援 ​

瀏覽器首次支援版本備註
Chrome105尺寸查詢
Firefox110尺寸查詢
Safari16尺寸查詢
Edge105基於 Chromium

樣式查詢(@container style())較晚出貨:

瀏覽器首次支援版本備註
Chrome111自訂屬性樣式查詢
Firefox127自訂屬性樣式查詢
Safari18自訂屬性樣式查詢

漸進增強模式:

css
/* 此處的樣式套用至所有瀏覽器 */
.card {
  /* 預設(窄版 / 垂直)版面 */
}

@supports (container-type: inline-size) {
  .card-wrapper {
    container-type: inline-size;
  }

  @container (min-width: 400px) {
    .card {
      /* 水平版面 */
    }
  }
}

JavaScript 功能偵測:

js
const supportsContainerQueries =
  CSS.supports('container-type', 'inline-size');

內部參考 ​

  • FEE-11001 CSS Anchor Positioning — 錨點定位與容器查詢都使用包含(containment)概念:錨點定位透過 anchor-scope 將名稱解析限定在子樹中,而容器查詢則將樣式計算限定在容器子樹中。
  • FEE-11201 @property — 樣式查詢查詢的是自訂屬性;@property 讓你宣告自訂屬性的語法、初始值與繼承行為。在樣式查詢中被查詢的具型別自訂屬性更可預測,因為其值永遠是宣告的型別,而非未設定變數時的空字串。

參考資料 ​