容器查询应用

为什么媒体查询不够用：组件复用的困境

先看一个真实场景。你写了一个漂亮的 .product-card，包含缩略图、标题、描述和标签。在首页的主内容区它占据 700px 宽，横向排列很好看；可同一个组件被放进侧边栏，只有 280px 宽，横向排列立刻挤成一团，文字被压成竖条。

面对这个问题，传统的解法只有三种，而它们都不够好：

• 解法一：给组件加一个修饰类。例如 .product-card--compact。问题在于，谁来决定用哪个类？只能是使用它的页面，于是组件的“自适应”变成了“被安排”。
• 解法二：写一堆上下文选择器。例如 .sidebar .product-card { ... }。这会让组件与页面结构强耦合，一旦侧边栏换个位置，样式就失效。
• 解法三：用媒体查询模拟。例如 @media (max-width: 768px) { ... }。可这依然在盯视口：桌面端侧边栏只有 280px，但视口有 1440px，媒体查询完全不会触发。

这三种解法的共同病根是：媒体查询无法回答“我这个组件现在有多宽”这个问题。而容器查询正是为了回答它而诞生的。

一句话记住区别

媒体查询问的是“屏幕有多大”，容器查询问的是“我住在多大的房子里”。一个组件被放进任何容器，都能自己决定该怎么排布——这才是真正意义上的组件化响应式。

核心语法：三行代码建立第一个容器

容器查询的语法出奇地简单，核心只有两步：先声明谁是容器，再写条件。

这里有两个容易踩坑的细节：

• 容器不能查询自己。@container 只对“容器的后代元素”生效。如果你给 .product-card 自己加了 container-type，再写 @container 去改它自己的样式，是不会生效的。
• 命名不是可有可无的装饰。当页面里存在多个嵌套容器时，不命名会让浏览器采用“最近祖先”策略，结果往往出人意料。命名能让规则精确落位。

媒体查询与容器查询的语法对照

两者并不是非此即彼的关系。一个成熟的项目通常是这样分工的：页面骨架用媒体查询，组件内部用容器查询。前者决定“页面有几种宏观布局”，后者决定“组件在不同空间里怎么表现”。

container-type 三种取值：你在建立什么样的容器

container-type 决定了容器能响应哪种查询。它的选择不仅影响能不能查，还会影响元素的布局行为，这一点经常被忽略。

inline-size 的副作用：宽度不再被内容撑开

这是最容易让人困惑的一点。给一个元素设置 container-type: inline-size 后，它会应用 contain: inline-size，这意味着元素的宽度不再受内容影响。

举个例子：一个 display: inline-block 的标签，原本宽度由文字长度决定。一旦加上 container-type: inline-size，它的宽度就会变成由外部约束（通常是撑满父容器或收缩为 0）。如果你只是想让一个行内元素变成容器，记得额外给它一个明确的宽度或 display: block。

size 类型的适用场景

container-type: size 需要容器在两个方向上都有明确尺寸，因此它适合那些尺寸已经由外部完全确定的场景，例如：

• 固定高度的图表容器，内部图例要根据高度决定横排还是竖排；
• 画布类组件（地图、可视化面板），需要同时感知宽高；
• 全屏转场中的媒体容器，需要按宽高比决定裁切方式。

对于普通的响应式卡片，inline-size 几乎总是更安全、更合适的选择。因为它的约束更弱，不会让元素意外塌陷。

交互实验室：亲手拖一拖容器宽度

下面这个实验台把容器宽度暴露成一个滑块。拖动滑块，你会看到同一份 HTML 结构在窄容器里是纵向布局，宽过 340px 后切换成横向，再宽过 520px 后缩略图放大、标题字号提升。这就是容器查询的全部魔力——它不关心你的屏幕有多大，只关心自己住在多大的盒子里。

观察要点：

• 容器宽度在 0～339px 时，卡片是纵向布局，缩略图占满整行；
• 跨过 340px，卡片变成横向，缩略图固定为 80×80；
• 跨过 520px，缩略图放大到 112×112，标题与正文同步放大；
• 整个过程没有任何 JS 参与布局计算——JS 只负责改变容器宽度，其余全部由 CSS 完成。

容器查询单位：让尺寸随容器缩放

除了条件判断，容器查询还带来了一整套新的长度单位。它们以容器尺寸为基准，而不是视口尺寸——这意味着一个组件内部的字号、间距、圆角都可以随容器等比缩放。

拖动滑块，你会看到标题字号、进度条宽度、说明文字同步缩放。这种效果如果用 vw 实现，就会跟着视口变化——而视口没变的时候，组件就不会有任何响应。容器单位让“缩放”第一次成为组件自己的行为。

容器单位 vs 视口单位：一次直观对照

双容器对比：同一组件，两种命运

下面这份对比图把完全相同的 HTML 结构分别放进 280px 和 600px 的容器里。请横向滚动查看：窄容器里它是纵向卡片，宽容器里它自动变成横向布局。整个过程没有任何额外类名、没有任何媒体查询。

这个能力为什么重要

在组件库、设计系统、微前端的语境下，组件会被放进无数种容器里。如果组件只能靠外部传类名来适配，那它就不是真正可复用的组件，只是一个“半成品”。容器查询把适配逻辑收回到组件内部，让组件真正具备了自包含的响应能力。

实战一：打造一个自包含的卡片组件

让我们把前面的知识整合成一个完整的、可以直接放进项目的卡片组件。它需要满足：在任何容器里都能自适应、层级清晰、字号可读、动效自然。

三个设计要点

• 基础样式面向最窄场景。默认就是纵向、紧凑、字号偏小；容器变宽时才逐步“解锁”更多布局可能。这与移动优先的思路一致，只是判断依据从视口变成了容器。
• 用 clamp() 兜住字号。容器单位负责缩放，clamp() 负责保证可读性。只写 5cqi 在极窄容器里会小到看不清，在极宽容器里又可能大得离谱。
• 条件性显示信息。容器窄的时候隐藏次要描述，宽的时候再展示——这是容器查询相对于媒体查询的独特优势，因为同一个页面里不同位置的组件状态可以完全不同。

实战二：自适应侧边栏与主内容布局

页面级的双栏布局也可以从容器查询中获益。设想一个仪表盘：左侧是筛选面板，右侧是数据区。当筛选面板本身被折叠得很窄时，它内部的表单应该自动变成图标模式或纵向堆叠——而这取决于它自己的宽度，不是视口。

为什么这在仪表盘里特别有价值

仪表盘的特点是布局状态多变：用户可以折叠侧边栏、可以拖拽分栏、可以全屏某个面板。这些变化都不改变视口宽度，但都会改变组件的可用空间。用媒体查询处理这些场景，你几乎必然要写一堆状态类；用容器查询，组件自己就能感知空间变化，代码量反而更少。

实战三：从数据表到卡片列表的无缝切换

数据表格是响应式设计里最头疼的组件之一。传统做法是：视口小于 768px 时把表格转成卡片。但如果这个表格被放在一个窄的面板里呢？视口很宽，表格依然会被挤爆。

容器查询让表格可以真正按“自己有多宽”来决定形态。

这个方案的三个优势

• 一份 HTML，两种形态。不需要为移动端单独渲染一套 DOM，也就不存在“两套结构不同步”的维护噩梦。
• 无障碍友好。表头用视觉隐藏而非 display: none，屏幕阅读器依然能正确读出表格语义；data-label 让卡片态的每个单元格都有明确的字段名。
• 位置无关。表格放进主内容区就显示为表，放进窄侧栏就变成卡片列表——不需要任何外部干预。

命名容器与嵌套：当页面里有多个容器

真实项目里，容器往往不止一层。一个卡片放在列表里，列表放在侧边栏里，侧边栏又放在页面栅格里——每一层都可能成为容器。这时候命名就成了精确控制的关键。

容器名称的命名规范建议

• 按语义命名，不按尺寸：用 card、sidebar、main，而不是 narrow、wide。因为容器的宽度是变化的，语义是不变的。
• 避免与元素类名冲突：容器名有独立的命名空间，与类名互不干扰，但为了避免阅读混乱，建议加一个统一前缀，如 cq-card。
• 在组件根节点声明容器：让组件的“容器身份”一目了然，而不是藏在某个中间层。
• 不要给所有元素都加容器类型：每个 container-type 都会引入 containment 约束，可能改变布局行为，也会带来额外开销。

style() 查询：不止尺寸，还能查询样式状态

容器查询的能力不止于尺寸。通过 @container style()，你可以查询容器上的自定义属性值，从而实现主题切换、状态驱动的样式变化。这是容器查询里最被低估的能力。

style() 查询的典型用途

• 主题注入：外层容器设置 --theme: dark，内部所有组件自动切换暗色样式，无需给每个组件传参。
• 密度控制：表格容器设置 --dense，内部的单元格、按钮自动收紧内边距。
• 状态驱动：容器设置 --state: loading，内部自动显示骨架屏、禁用交互。
• 布局变体：同一个组件在 --layout: compact 的容器里显示精简版，在默认容器里显示完整版。

需要注意：style() 查询目前主要用于自定义属性，不能查询任意 CSS 属性值（例如查询 display 或 color 是不行的）。它的设计意图就是让开发者通过自定义属性传递语义状态，因此使用时也要遵循这个约定。

scroll-state() 查询：感知滚动与吸附状态

容器查询家族还在持续扩展。@container scroll-state() 让元素可以感知自己是否被吸附（stuck）、是否可滚动、是否滚动到了边缘——这些过去只能靠 JS 监听 scroll 事件才能实现的能力，现在直接写进 CSS。

能力边界与使用建议

• 目前支持度较低：scroll-state() 在 Chrome 133+ 才逐步可用，生产环境务必配合 @supports 与 JS 退化方案。
• 适合纯视觉反馈：吸附阴影、渐隐遮罩、回到顶部按钮显隐——这些“有更好，没有也能用”的效果最适合用它。
• 不适合承载关键逻辑：不要用它来控制业务数据的加载或权限判断，那不是 CSS 的职责。

与 Grid、Flex 的配合：让布局引擎先干活

容器查询不是万能的，它擅长的是“在给定空间里做取舍”。而很多自适应问题，其实布局引擎自己就能解决——用容器查询之前，先确认是不是在重复造轮子。

决策流程：什么时候该用容器查询

一个实用的经验：先让布局引擎做它能做的事，再用容器查询处理它做不到的事。很多开发者一上来就写一堆 @container，结果发现代码量大、断点难维护，反而不如 repeat(auto-fit, minmax()) 来得干净。

性能考量与常见陷阱

容器查询本身不会让页面变慢——它读取的是浏览器已有的布局信息，判断成本极低。但使用不当仍然会踩坑，尤其是对 containment 约束理解不足的时候。

关于性能的三个事实

• 容器查询的判断本身几乎不花钱。浏览器在布局阶段就已经知道每个容器的尺寸，查询只是读取并比较，不产生额外的重排。
• 代价在于 containment 约束。当元素声明了 container-type，它内部的变化不会再影响外部布局，这通常减少计算量；但如果因此需要额外的显式尺寸，可能引入新的布局约束。
• 真正需要警惕的是过渡动画。容器宽度变化时，如果内部有大量基于容器查询的样式切换，并且都带 transition，可能会同时触发多组布局计算。建议只给必要属性加过渡，并且时长控制在 300ms 以内。

调试容器查询的实用技巧

兼容性与渐进增强策略

容器查询的浏览器支持已经相当不错。尺寸查询（inline-size）在主流浏览器中都可用，而较新的 style()、scroll-state() 则还需要时间。

退化策略的选择

• 纯视觉增强：例如吸附阴影、渐隐遮罩。不支持时效果消失，但功能完全正常——最省事的退化方式。
• 布局切换：例如卡片横排。退化时保持纵向布局，虽然不够好看，但依然可读可用。
• 关键信息隐藏：如果某个信息只在宽容器里显示，请确保它在窄容器里不是必需的，否则退化后用户会丢失信息。
• 需要精确控制时：用 ResizeObserver 做 JS 退化，代价是要维护两套逻辑，仅在必要时使用。

容器查询最佳实践清单

把全文的要点浓缩成一份可以直接贴在工位上的清单。

容器查询真正改变的，不是某一行 CSS 的写法，而是我们思考响应式的起点。过去我们习惯从“屏幕有多大”出发，把页面切成几档；现在我们可以从“组件住在哪里”出发，让每个组件自己决定该如何呈现。当组件库里的每一个成员都具备这种能力时，页面级的响应式设计就会变得前所未有的轻松——因为你不再需要为每一种使用场景准备一个变体。

建议你在下一个项目里，挑一个最常被复用的组件（卡片、列表项、表单项都行），把它改成容器查询驱动。改完之后，试着把它放进最窄和最宽的两个位置，看看它是否都能自然成立。那一刻你大概会意识到：原来响应式设计可以这么省心。