[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 主內容區的同一張卡片,兩者所在的視口是相同的。視口寬度一致;元件的可用空間卻截然不同。
業界採用了各種變通方式:
- JavaScript ResizeObserver — 對元件附加觀察器,在 JS 中計算尺寸類別,將 data attribute 或 class 寫入 DOM,再以 CSS 目標該 class。雖然有效,但會造成版面抖動(layout thrashing)、耗費執行時間,且在 SSR 環境中需要水合(hydration)才能讓樣式正確套用。
- CSS Grid
auto-fit/auto-fill— 讓欄位在空間不足時自動收合,但無法觸發元件內部的版面切換,例如將圖片從水平排列改為垂直排列。 - 由父層傳遞尺寸 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 年,已廣泛支援)讓開發者得以觀察元素本身的尺寸並做出回應。典型模式如下:
- 觀察
.card的尺寸變化。 - 在回呼函式中讀取
contentRect.width。 - 切換 class(例如
card--horizontal)。 - 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 元件從垂直排版(預設,圖片在上)切換為水平排版(圖片在左、內容在右)。
<!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。
<!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%(別名) |
cqmin | cqi 與 cqb 中較小者 |
cqmax | cqi 與 cqb 中較大者 |
可用於隨元件可用空間縮放的字體大小與間距:
.card__title {
/* 字體大小隨容器增大,在 14px 至 22px 之間縮放 */
font-size: clamp(0.875rem, 4cqi, 1.375rem);
}容器巢狀
當一個容器置於另一個容器內部時,它對其後代而言成為獨立的 containment context:
.page-layout {
container: page / inline-size;
}
.sidebar {
container: sidebar / inline-size;
}
.widget {
/* 此 @container 規則解析至 .sidebar,而非 .page-layout */
/* 因為 .sidebar 是最近的具有 containment 的祖先 */
}未命名的 @container 規則永遠解析至最近任何設有 container-type 的祖先。精確命名容器可避免意外解析至錯誤的祖先。
樣式查詢目前的限制
截至 2026 年,樣式查詢只能查詢自訂屬性(CSS 變數),無法查詢計算值:
/* 有效 — 自訂屬性查詢 */
@container style(--variant: featured) { ... }
/* 無效 — 計算值查詢(目前無任何瀏覽器支援) */
@container style(color: red) { ... }
@container style(width: 300px) { ... }CSS 工作小組已討論將樣式查詢擴展至計算值,但瀏覽器實作尚未出貨。目前撰寫的程式碼只能查詢自訂屬性。
效能:版面包含的影響
container-type: inline-size 會在塊方向套用版面包含(layout containment)。這有兩個值得注意的副作用:
- 塊軸高度與內容脫鉤 — 容器的塊軸尺寸由其本身的 sizing context 決定,而非其內容。若未指定高度,容器將塌陷為零。這是刻意設計:它讓瀏覽器在只有容器行內尺寸改變時,略過容器子樹的版面計算。
- 堆疊上下文(stacking context) — 版面包含會建立新的堆疊上下文(類似具有
z-index的position: relative)。這可能影響容器內部絕對定位子元素的z-index行為。
container-type: size 在兩個維度都套用包含,消耗更多資源。僅在 @container 規則需要查詢塊軸維度(例如 min-height)時才使用它。
container 簡寫
/* 完整寫法 */
.card-wrapper {
container-type: inline-size;
container-name: card;
}
/* 等效簡寫 */
.card-wrapper {
container: card / inline-size;
}簡寫語法為 container: <name> / <type>,必須使用斜線分隔。若要宣告類型而不命名,寫法為 container: none / inline-size。
瀏覽器支援
| 瀏覽器 | 首次支援版本 | 備註 |
|---|---|---|
| Chrome | 105 | 尺寸查詢 |
| Firefox | 110 | 尺寸查詢 |
| Safari | 16 | 尺寸查詢 |
| Edge | 105 | 基於 Chromium |
樣式查詢(@container style())較晚出貨:
| 瀏覽器 | 首次支援版本 | 備註 |
|---|---|---|
| Chrome | 111 | 自訂屬性樣式查詢 |
| Firefox | 127 | 自訂屬性樣式查詢 |
| Safari | 18 | 自訂屬性樣式查詢 |
漸進增強模式:
/* 此處的樣式套用至所有瀏覽器 */
.card {
/* 預設(窄版 / 垂直)版面 */
}
@supports (container-type: inline-size) {
.card-wrapper {
container-type: inline-size;
}
@container (min-width: 400px) {
.card {
/* 水平版面 */
}
}
}JavaScript 功能偵測:
const supportsContainerQueries =
CSS.supports('container-type', 'inline-size');內部參考
- FEE-11001 CSS Anchor Positioning — 錨點定位與容器查詢都使用包含(containment)概念:錨點定位透過
anchor-scope將名稱解析限定在子樹中,而容器查詢則將樣式計算限定在容器子樹中。 - FEE-11201 @property — 樣式查詢查詢的是自訂屬性;
@property讓你宣告自訂屬性的語法、初始值與繼承行為。在樣式查詢中被查詢的具型別自訂屬性更可預測,因為其值永遠是宣告的型別,而非未設定變數時的空字串。