把响应式做成可验证的状态切换：Container Queries 的组件级重构方法

把响应式做成可验证的状态切换：Container Queries 的组件级重构方法

同一张项目卡片放在内容主栏、侧边栏和弹窗里，常常会遇到一个反直觉的问题：页面视口已经足够宽，卡片却仍然拥挤。

这通常不是 Flexbox、Grid 或某个断点数值不够精确，而是判断对象错了。媒体查询回答的是"当前浏览器环境有多大"；组件真正需要回答的却是"我现在实际拿到了多少可用空间"。

CSS Container Queries 为这个问题提供了原生机制。但如果只是把 @media 批量替换成 @container，项目往往会得到另一套更难理解的规则：容器建错了、查询命中了意外祖先、嵌套条件互相叠加，最终仍然无法保证组件在未知宿主中的稳定性。

更可靠的重构方式，是把组件视为一个由空间驱动的布局状态机：空间变化触发状态切换；每个状态只描述布局、密度和视觉层级；业务交互状态仍由组件逻辑负责。

先换问题：不是"在哪个设备上"，而是"组件处于什么状态"

媒体查询以视口或设备环境为判断对象，适合页面级结构，例如全局导航是否展开、应用壳是否显示双栏，以及触控环境下是否需要更大的操作目标。

容器查询读取祖先容器的特征。尺寸查询可以根据容器的内联尺寸、块尺寸或宽高比应用规则；样式查询则可以根据容器的计算样式建立有限的外观变体。二者不是替代关系，而是分别服务于页面环境与组件局部空间。W3C CSS Containment Level 3 与 MDN Container Queries 指南 对此作了说明。

因此，迁移前不要先问"桌面端断点是多少"，而要为组件写出空间状态：

状态	可用空间特征	布局决策
compact	横向空间不足以同时承载图标、正文和操作区	信息纵向堆叠，保留关键操作
regular	可以容纳主信息与辅助操作	内容区与操作区横向排列
expanded	可以提供额外阅读宽度	展示辅助元数据，扩大标题与摘要的排版空间

状态名描述的是组件能力，而不是设备。不要使用 mobile、tablet、desktop 这类名称：同一个组件在桌面侧栏中可能处于 compact，在手机横屏弹窗中却可能进入 regular。

这一定义也划清了边界：

• 适合容器查询的决策：排列方向、网格列数、间距、辅助信息显隐、字号的有限缩放、操作区换行。
• 不应伪装成布局状态的决策：是否请求更多数据、是否改变权限、是否改变提交流程、是否执行复杂交互，以及多个独立组件如何共同协调。

后者需要产品策略、组件状态、数据层或脚本协作；Container Queries 只负责条件化 CSS 样式。

查询如何命中：先建立容器，再选择祖先

尺寸容器查询不会自动作用于任意元素。浏览器需要知道哪个祖先元素可以作为被查询的尺寸上下文。

.project-panel {
  container-type: inline-size;
}

container-type: inline-size 让元素成为可查询其内联轴尺寸的容器。在通常的横排书写模式中，内联轴接近宽度。卡片、工具栏和表单通常主要随横向空间改变布局，因此它是大多数组件的默认选择。

.project-panel {
  container: project-panel / inline-size;
}

container 简写可以同时声明名称与类型。名称不是装饰，而是查询时筛选祖先容器的条件：无名称查询通常使用最近的合格祖先；指定名称后，浏览器会在祖先链中寻找名称匹配、且可支持该查询条件的容器。若没有合格祖先，尺寸查询条件不会成立。W3C 规范中的查询容器选择规则 对此有更完整的定义。

一个实用原则是：容器应由拥有可用空间分配权的元素建立。

卡片本身可以作为其后代元素的查询容器，但查询规则不能根据卡片自身尺寸直接修改卡片自身。因此，当卡片需要依据自身获得的宽度切换网格结构时，通常应由卡片宿主建立容器。

<section class="project-panel">
  <article class="project-card">
    <div class="project-card__identity">
      <img class="project-card__avatar" src="avatar.png" alt="项目负责人头像">
      <div>
        <h2>容器查询迁移计划</h2>
        <p>重构组件级响应式规则与验证流程。</p>
      </div>
    </div>
    <div class="project-card__meta">进行中 · 8 个任务</div>
    <div class="project-card__actions">
      <button type="button">查看</button>
      <button type="button">更多</button>
    </div>
  </article>
</section>

.project-panel {
  container: project-panel / inline-size;
}

.project-card {
  display: grid;
  gap: 0.75rem;
  min-inline-size: 0;
  padding: 1rem;
  border: 1px solid #d9dde5;
  border-radius: 0.75rem;
}

.project-card__identity {
  display: grid;
  grid-template-columns: auto minmax(0, 1fr);
  gap: 0.75rem;
  align-items: start;
  min-inline-size: 0;
}

.project-card__identity h2,
.project-card__identity p {
  overflow-wrap: anywhere;
}

.project-card__meta {
  display: none;
}

.project-card__actions {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}

@container project-panel (inline-size > 36rem) {
  .project-card {
    grid-template-columns: minmax(0, 1fr) auto;
    align-items: center;
  }

  .project-card__actions {
    justify-content: end;
  }
}

@container project-panel (inline-size > 56rem) {
  .project-card {
    grid-template-columns: minmax(0, 1fr) auto auto;
  }

  .project-card__meta {
    display: block;
  }
}

这里默认样式就是 compact：即使浏览器不支持容器查询，内容依旧可读、操作依旧可达。容器变宽后，组件才逐步进入 regular 和 expanded。将元信息默认隐藏、仅在宽状态显示，也使示例与前述状态定义保持一致。

inline-size、size 与查询单位：只查询真正需要的维度

container-type 常用值有两种：

• inline-size：允许查询内联轴尺寸，并施加对应的内联尺寸包含；适合绝大多数横向响应式组件。
• size：允许同时查询内联轴和块轴尺寸，但会施加更强的尺寸包含；只有组件高度稳定、独立且确实需要作为条件时才应考虑。

不要因为"更全面"就默认使用 size。许多内容高度由子元素、文本换行和异步内容共同决定，把高度纳入查询会显著增加布局推理成本。

容器相对单位适合处理状态内部的连续缩放：

@container project-panel (inline-size > 36rem) {
  .project-card {
    padding-inline: clamp(1rem, 3cqi, 2rem);
  }

  .project-card__identity h2 {
    font-size: clamp(1.125rem, 2.2cqi, 1.75rem);
  }
}

cqi 表示查询容器内联尺寸的 1%；另有 cqw、cqh、cqb、cqmin 和 cqmax 等单位。它们适合在已确定的布局状态内做有限的比例调整，而不适合替代所有尺寸约束。字号、按钮尺寸和间距仍应通过 min()、max() 或 clamp() 保留可读性与可操作性的上下限。

容器单位找不到合格查询容器时，会使用对应的小视口尺寸作为回退。因此，关键布局不应只依赖容器单位。W3C 对容器相对长度单位的定义 提供了具体细节。

另一个容易忽略的细节是阈值单位。容器查询条件中的相对长度与媒体查询中的解析上下文不同。若使用 em 作为阈值，应确认是否有意让容器字体尺度影响切换点；否则应统一团队的断点 token 与单位规则。

嵌套容器不是层层加保险，而是多次祖先解析

复杂组件可能同时存在外层版面容器和内层局部容器：外层决定卡片所在区域是否进入宽版布局，内层决定操作组是否需要折行。这时最危险的误解，是以为所有 @container 都会查询同一个元素。

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

.project-card__actions-wrap {
  container: actions / inline-size;
}

@container workspace (inline-size > 70rem) {
  .project-card {
    border-inline-start-width: 4px;
  }

  @container actions (inline-size < 18rem) {
    .project-card__actions {
      inline-size: 100%;
    }
  }
}

这段规则表示：只有 workspace 足够宽，并且 目标元素能找到名为 actions、宽度不足的祖先容器时，内层规则才生效。嵌套查询可以针对不同容器，规则需要同时满足外层与内层条件；它不能简单理解成一个可随意合并的单一断点。MDN 的 @container 参考 说明了相关语法与逻辑条件。

建议只在两类场景中使用命名容器：

1. 组件内部存在多个明确的空间责任域，需要避开"最近祖先"歧义。
2. 某个后代必须跳过中间容器，稳定地查询特定布局宿主。

其余场景优先使用最近容器规则。命名越多，祖先解析路径越难在代码审查中看清。

级联仍然存在：状态规则不是独立运行的

@container 只决定其中的规则是否参与匹配，不会绕过 CSS 的级联、特异性和源码顺序。

下面的写法容易制造"断点已经命中但样式没变"的假象：

@container project-panel (inline-size > 36rem) {
  .project-card__meta {
    display: block;
  }
}

.project-card .project-card__meta {
  display: none;
}

最后一条规则的特异性更高且位置更靠后，会让元信息继续隐藏。解决办法不是无限提高容器查询选择器的特异性，而是建立可预测的层次：

• 默认状态放在组件基础规则中；
• 状态增量集中在相邻的 @container 区块中；
• 尽量使用低特异性选择器；
• 对复杂项目使用 Cascade Layers，把 reset、基础组件、容器状态和业务覆盖分层；
• 避免通过 !important 解决状态冲突，否则边界验证会失去意义。

样式查询也应保持克制。它可以把自定义属性作为组件的外观开关：

.project-panel {
  --density: compact;
}

@container style(--density: compact) {
  .project-card {
    gap: 0.5rem;
  }
}

但样式查询不是复制 JavaScript 状态管理的工具。它适合稳定、可继承且与视觉表现直接相关的 token；权限、加载过程、表单校验和复杂交互仍应保留在语义正确的状态模型中。当前实现支持范围和特性粒度仍应按目标浏览器矩阵核验，尤其不要假设所有普通 CSS 声明都能被 style() 查询。MDN 的 size 与 style queries 指南 对这一限制有说明。

与 Grid、Flexbox 一起用：让内容决定下限，让查询决定结构

Container Queries 最常见的失败表象是溢出。根因通常不是查询条件本身，而是组件在状态切换前后缺少内容约束。

.toolbar-host {
  container: toolbar-host / inline-size;
}

.data-toolbar {
  display: flex;
  flex-wrap: wrap;
  gap: 0.75rem;
}

.data-toolbar__search {
  flex: 1 1 16rem;
  min-inline-size: min(100%, 16rem);
}

.data-toolbar__filters {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 10rem), 1fr));
  gap: 0.5rem;
}

@container toolbar-host (inline-size > 48rem) {
  .data-toolbar {
    flex-wrap: nowrap;
  }
}

这里假定 .toolbar-host 是包裹工具栏、负责分配其可用宽度的宿主。职责可拆为：

• Flexbox 和 Grid 负责自然换行、可伸缩轨道与内容下限；
• minmax()、min()、min-inline-size: 0 负责避免长文本或长控件撑破轨道；
• 容器查询只在空间真正充足时切换到更高密度的结构；
• inline-size、padding-inline、margin-block 等逻辑属性让规则贴近书写方向，而非绑定物理宽高。

不要把每一个微小宽度变化都做成状态。若组件需要五六个以上纯布局断点，通常说明其中混入了连续缩放、内容裁剪策略或宿主级版面问题。先让 Grid/Flexbox 的 intrinsic sizing 解决自然弹性，再为真正的结构跃迁保留少量容器状态。

六种高频失败模式

1. 查询容器根本没有建立

只写 @container (inline-size > 36rem)，却没有任何祖先设置 container-type: inline-size，规则不会按预期命中。

检查方式 ：在浏览器开发者工具中定位目标元素，沿祖先链确认谁拥有 container-type。Chrome DevTools 可辅助查看容器查询相关标记与范围。Chrome DevTools 的容器查询调试指南 提供了具体入口。

2. 最近容器不是你以为的容器

组件迭代后，某个中间包装层新增了 container-type，未命名查询就可能改为读取它的尺寸。

处理方式 ：删除没有空间责任的中间容器，或对真正的布局宿主使用明确的 container-name。

3. 用自身尺寸决定自身布局

查询规则作用于查询容器的后代。若卡片希望依据自身获得的宽度修改卡片自身的 display 或网格轨道，通常需要在卡片外引入宿主容器。

处理方式：把"分配空间的元素"和"响应空间的组件"分开。

4. 尺寸形成循环依赖

如果容器尺寸依赖子内容，而子内容又通过查询规则大幅改变容器尺寸，布局推理会变得困难。尺寸包含的存在正是为了限制这类相互影响。

处理方式 ：优先查询外层稳定分配的空间；避免由容器查询控制决定容器主尺寸的关键内容；对高度敏感的设计先重新审视布局结构，而非立即使用 container-type: size。

5. 用视觉隐藏替代信息策略

在 compact 状态中隐藏元信息前，要确认信息是否可以安全省略。若该信息影响理解、操作结果或状态判断，应提供替代入口、摘要或可展开机制，而不是仅靠 display: none 把问题交给窄容器。

6. 只在一个页面宽度上验收

组件在开发页面正确，不代表它在抽屉、嵌套卡片、分栏面板或 iframe 中正确。Container Queries 的价值恰恰是支持多宿主复用，因此验证也必须摆脱单一视口。

渐进增强：先保证可用，再增加状态能力

生产环境不应把"支持容器查询"当作页面可用性的前提。稳妥的层次是：

1. 先写默认的窄空间、纵向流式布局；
2. 使用 Grid/Flexbox 的固有弹性保证基础体验；
3. 在特性可用时启用容器与状态增强；
4. 根据目标浏览器矩阵决定是否保留旧媒体查询作为局部兜底，而不是全局双写。

.project-card {
  display: grid;
  gap: 0.75rem;
}

@supports (container-type: inline-size) {
  .project-panel {
    container: project-panel / inline-size;
  }

  @container project-panel (inline-size > 36rem) {
    .project-card {
      grid-template-columns: minmax(0, 1fr) auto;
    }
  }
}

@supports 用于检测浏览器是否支持某项 CSS 能力，适合把增强规则与基础规则隔离。它检测的是特性支持，而不是设备大小。MDN 的 Feature Queries 指南 解释了这一用途。

对于长期维护的组件库，降级目标不必是"旧环境完全复刻现代布局"，而应是：内容可阅读、操作可完成、阅读顺序合理、不会横向溢出。把这一点写入验收标准，比维护一份不断膨胀的兼容分支更实际。

把"能适配"变成"已验证"：组件级测试矩阵

容器查询的测试对象不再只是 viewport。每个关键组件都应建立宿主尺寸矩阵：

维度	应验证的问题
宿主类型	主栏、侧栏、弹窗、抽屉、嵌套卡片是否得到合理状态
边界尺寸	每个阈值前 1px、阈值处、阈值后 1px 是否发生预期切换
内容压力	超长标题、多语言、动态标签、空状态、错误状态是否溢出
字体与缩放	文本放大后是否仍可阅读和操作，状态是否出现意外跳变
交互与语义	视觉重排后，DOM 阅读顺序、键盘顺序和焦点可达性是否保持正确
回归方式	截图测试是否覆盖 compact、regular、expanded 三类状态

一个可执行的验证闭环可以是：

1. 在组件演示环境中，为同一组件提供多个固定宽度的宿主。
2. 为每个容器阈值生成"阈值前、阈值处、阈值后"的截图。
3. 注入长文本、空值、异常标签和多语言内容，检查 scrollWidth > clientWidth 等溢出信号。
4. 在 DevTools 中确认目标查询实际绑定的容器，而非仅观察最终视觉结果。
5. 把关键状态组合纳入视觉回归；对隐藏与重排后的关键操作补充键盘测试。

这里最重要的不是测试工具，而是测试命名。测试用例应描述空间状态，例如"工具栏在 479px 宿主内换行""卡片在 896px 宿主内显示辅助元信息"，而不是"iPhone 截图"或"桌面端样式"。

一套可落地的重构流程

最后，把迁移收束为六步，而不是一次全量替换：

1. 盘点现有媒体查询：逐条标记它影响的是页面壳、区域布局还是独立组件。
2. 提取组件状态：把"宽度大于某值"翻译为明确的布局能力，例如"操作区可横向并列"。
3. 选择空间责任人 ：在真正分配可用空间的宿主上建立 inline-size 容器；只有跨越中间容器时才命名。
4. 迁移默认与增量样式 ：先实现最小可用的 compact，再用少量查询规则增加状态，而不是复制整份样式。
5. 验证边界与未知宿主：按容器尺寸矩阵测试临界点、长内容、缩放和嵌套环境。
6. 清理旧规则：确认组件规则不再依赖视口后，删除对应媒体查询，避免两个条件系统同时争夺同一属性。

Container Queries 最终带来的不是更多断点，而是一种更准确的责任划分：视口规则继续处理页面环境，组件规则则只响应自己得到的空间。这样，响应式布局才能从"某个页面恰好看起来正常"，变成"组件在可预期状态下经过验证地工作"。

参考资料

• CSS Containment Module Level 3（W3C）
• CSS Container Queries（MDN）
• Using Container Size and Style Queries（MDN）
• @container（MDN）
• Inspect and Debug CSS Container Queries（Chrome for Developers）
• Using Feature Queries（MDN）