把断点关进组件：设计系统迁移 Container Queries 的实战框架

从页面断点到空间契约：Container Queries 的设计系统迁移法

响应式布局失控时，问题往往不在于断点数量不够，而在于组件把页面视口误当成了自己的运行上下文。

一个商品卡片在主内容区是横向图文结构，放进侧栏后却仍坚持横向；一个筛选工具栏在弹窗里比在页面上更窄，却因为视口足够宽而不肯折行；一个信息摘要模块必须由父页面追加 is-sidebar、is-compact 之类的 class 才能正常显示。这些现象说明：组件的样式决策仍被绑在“用户正在使用多宽的屏幕”上，而不是“组件此刻实际获得了多少空间”。

CSS Container Queries 提供的不是又一套断点语法，而是一种更适合设计系统的责任划分：

• 媒体查询处理页面骨架、设备能力和全局导航策略；
• Grid 与 Flexbox处理空间如何分配；
• Container Queries处理组件获得不同可用空间后，内部应切换到哪种呈现状态。

MDN 与 web.dev 都将这一能力定位为基于祖先容器特征应用样式：同一个组件进入主栏、侧栏或网格单元时，可以根据所在容器的空间变化，而页面整体布局仍可继续使用媒体查询。MDN · web.dev

先改定义：响应式不等于“适配设备宽度”

传统做法通常从视口断点出发：

@media (min-width: 1024px) {
  .product-card {
    grid-template-columns: 10rem 1fr;
  }
}

这段代码隐含了一个未经验证的前提：只要视口超过 1024px，卡片就一定拿得到足以横向排列的空间。

现实项目里，这个前提经常不成立。桌面端页面可能同时有侧栏、抽屉、分屏面板、浮层、嵌套网格和可伸缩工作区。视口很宽，不代表组件宽；移动端横屏、嵌入式 WebView 或可折叠面板中，也可能出现反过来的情况。

Container Queries 的重构目标因此不是“把 @media 全部替换为 @container”，而是把每个组件的布局规则改写为一个更清晰的契约：

当可用内联尺寸不足以同时容纳缩略图、标题、元信息与操作区时，组件切换为纵向；当空间重新充足时，再恢复横向。

这里的断点表达的是组件的布局能力，不是 iPad、桌面端或某个页面栏目。

哪些地方值得迁移，哪些地方应保留媒体查询

优先迁移的不是“所有响应式代码”，而是具有多个宿主场景、需要独立复用的组件：

• 商品卡片、文章卡片、人员卡片等信息密度会变化的卡片；
• 列表项、搜索结果条目、通知摘要；
• 可出现在主栏、侧栏和弹窗中的表单区块；
• 筛选器、操作工具栏、局部导航；
• 业务模块、微前端挂件或嵌入式组件。

反过来，下列职责通常仍属于视口媒体查询：

• 页面从双栏切换为单栏；
• 全局导航从完整菜单切换为抽屉入口；
• 与设备能力直接相关的规则，例如 hover、pointer、打印模式或减少动态效果；
• 整个应用的安全边距、全局字号策略与页面级排版节奏。

这是一条重要边界：页面决定给组件多少空间；组件决定如何使用这些空间。

迁移前先做诊断，而不是搜索替换 @media

一个组件出现以下信号时，通常值得纳入改造候选：

1. 组件内部已经有多条 viewport breakpoint。
2. 同一组件在主栏、侧栏、弹窗或不同网格列数下表现不同。
3. 父页面通过 modifier class 强行影响组件内部排版，例如 .page--narrow .card。
4. 组件的样式依赖它处于第几列、哪种页面模板或哪个业务页面。
5. 新增一个宿主场景时，开发者首先想到的是“再加一个页面特例”。

建议为候选组件建立一张迁移卡片，而不是直接开始改 CSS：

这张卡片的目的，是把“页面断点”翻译为“组件状态”。如果团队无法说清一个断点为什么存在，就不应把它原样搬进容器查询。

最小机制：先理解容器，再写查询

尺寸型 Container Query 需要先建立查询容器。常用写法如下：

.card-shell {
  container: ds-card / inline-size;
}

@container ds-card (width >= 36rem) {
  .product-card {
    grid-template-columns: 9rem minmax(0, 1fr);
    align-items: start;
  }
}

这里有三个工程含义。

1. 默认优先使用 inline-size

container-type: inline-size 允许后代依据容器的内联轴尺寸进行查询，适合绝大多数“宽度变化导致排版切换”的组件。size 则同时对内联轴和块轴启用尺寸包含；它不应被当作没有额外代价的加强版。

尺寸包含的存在，是为了避免查询规则改变内容尺寸、内容尺寸又反过来改变查询结果的循环。代价是：元素尺寸可能无法再完全由子元素自然推导。特别是 size 容器，如果没有来自外部布局上下文或显式尺寸的支撑，可能发生收缩或高度计算异常。MDN · W3C CSS Containment Level 3

因此，卡片、表单、列表项这类“高度应由内容撑开”的组件，通常先选 inline-size；只有确实需要根据宽高、纵横比或容器高度切换状态时，才审慎使用 size。

2. 查询的是后代，不是容器自身

@container 中的规则依据祖先查询容器判断。因此，如果需要改变组件根节点本身，通常要让一个外层 wrapper 成为容器：

<div class="product-card-shell">
  <article class="product-card">...</article>
</div>

这不是多余包装，而是明确表达了“宿主空间”和“组件内容”之间的关系。对于设计系统组件，它也能避免组件根节点同时承担布局分配、查询上下文和视觉呈现三种职责。

3. 最近容器是默认值，命名容器是例外工具

未指定名称时，查询会匹配最近的、满足条件的祖先查询容器。嵌套组件很多时，这种默认行为通常最符合局部封装：评论卡片响应评论列表的宽度，按钮组响应卡片操作区的宽度。

只有当组件明确需要跳过最近容器、响应某个更外层的布局上下文时，才使用命名容器。container-name 会过滤可选查询容器；这适合处理嵌套容器下的明确依赖。W3C CSS Containment Level 3 · MDN

命名建议使用设计系统前缀，例如 ds-card、billing-summary，避免 card、layout 这类过于泛化的名称。命名不是为了让查询“更高级”，而是为了让依赖关系可读、可审查。

用一个卡片组件完成迁移，而不是复制旧断点

假设现有卡片被多个页面复用：主栏显示横向卡片，侧栏显示纵向卡片，弹窗里又需要紧凑版本。旧实现很容易变成这样：

.product-card {
  display: grid;
  gap: 1rem;
}

.page--sidebar .product-card,
.modal .product-card {
  grid-template-columns: 1fr;
}

@media (min-width: 1024px) {
  .product-card {
    grid-template-columns: 9rem minmax(0, 1fr);
  }
}

它的核心问题不是选择器丑，而是页面在替组件做决定。迁移时可按下面的顺序进行。

第一步：划出组件真正的状态

不要先问“原来有 768、1024、1280 三个断点，容器查询也要几个？”

先问：卡片究竟有几种视觉状态？例如：

• 紧凑：图片在上，元信息压缩，操作按钮可换行；
• 常规：图片与正文并排，标题最多两行；
• 宽松：操作区与元信息可在同一行分布。

状态数量应由信息结构决定，而不是由历史断点数量决定。

第二步：让宿主暴露空间，而不是注入页面语义

.product-card-shell {
  container: ds-product-card / inline-size;
}

.product-card {
  display: grid;
  grid-template-columns: 1fr;
  gap: var(--space-4);
}

.product-card__actions {
  display: flex;
  flex-wrap: wrap;
  gap: var(--space-2);
}

@container ds-product-card (width >= 34rem) {
  .product-card {
    grid-template-columns: 8.5rem minmax(0, 1fr);
  }
}

@container ds-product-card (width >= 52rem) {
  .product-card__meta-and-actions {
    display: flex;
    justify-content: space-between;
    gap: var(--space-4);
  }
}

父页面现在只需要决定 .product-card-shell 被放在什么布局里；它不再需要传递“你在侧栏”这样的样式指令。组件根据实际空间选择状态，契约从“页面位置”变成“可用宽度”。

第三步：删除不能证明必要性的页面特例

迁移完成后，检查以下代码是否还存在：

• .dashboard .product-card 之类按页面耦合的覆盖；
• .is-sidebar、.is-modal、.is-compact 等只为排版存在的 modifier；
• 仅因组件所在栏目不同而写的重复媒体查询；
• 通过提高选择器权重压住设计系统默认样式的规则。

这并不是要求消灭所有 modifier。业务语义仍然可以通过 modifier 表达，例如风险状态、选中状态、营销样式或可编辑状态。但“因为父页面比较窄，所以组件必须纵向”不应再是页面级语义。

Container Queries 与现有工具如何分工

把 Container Queries 引入项目，不意味着推翻已有响应式体系。更稳妥的组合是：

容器查询单位包括 cqw、cqh、cqi、cqb、cqmin 与 cqmax；例如 1cqi 表示查询容器内联尺寸的 1%。如果找不到合适的查询容器，这些单位会回退到对应的小视口单位，因此不应在缺少明确容器上下文时把它们当作全局尺寸单位使用。MDN · W3C CSS Containment Level 3

实践上，优先用 @container 解决离散布局状态；只有在设计确实需要连续缩放时，再谨慎结合 clamp() 与 cqi：

.product-card__title {
  font-size: 1rem;
}

@container ds-product-card (width >= 28rem) {
  .product-card__title {
    font-size: clamp(1rem, 0.9rem + 0.5cqi, 1.25rem);
  }
}

嵌套容器最常见的两个误区

误区一：到处声明容器

每一层都写 container-type: inline-size，看似给了组件更多能力，实际会制造更多“最近容器”，导致内部组件意外响应到错误的祖先。

更好的原则是：只有某层确实需要向后代提供尺寸上下文时，才建立容器。

例如，页面主栏可以是容器；卡片内部的操作区若需要独立折行，也可以是容器；但单纯的装饰 wrapper、图标容器和文本分组通常不需要。

误区二：用命名容器逃避边界设计

当一个组件频繁查询很远的外层容器，往往意味着它并不真正独立，或者当前的组件拆分层级有问题。

命名容器适合表达少量、明确的跨层关系，例如组件需要知道自己是否位于某个固定宽度的工作区。它不适合成为“穿透所有嵌套层级读取页面状态”的通道。否则，原本从 CSS 选择器泄漏出去的耦合，只是换了一种语法继续存在。

迁移不是一次性重写：采用双轨试点

对于仍需支持旧浏览器或嵌入式运行环境的项目，建议把 Container Queries 当作渐进增强，而不是发布阻塞条件。尺寸型 Container Queries 已被主流现代浏览器支持，但旧版浏览器和部分特殊环境仍可能缺失支持；是否需要降级，应以真实用户浏览器分布为准。Can I use

一个可执行的迁移路径是：

1. 选一个高复用、低业务风险组件试点：卡片、工具栏或表单分组通常比整页重构更合适。
2. 保留基础布局：先让不支持容器查询的环境获得可读、可操作的单列或紧凑布局。
3. 以特性检测包裹增强规则：在支持环境启用组件级状态切换。
4. 沉淀断点语义：记录每个断点对应的是“操作区可并排”还是“图文可并排”，而不是只登记数值。
5. 补齐视觉回归矩阵：通过后再推广到更多设计系统组件。

.product-card {
  display: grid;
  grid-template-columns: 1fr;
}

@supports (container-type: inline-size) {
  .product-card-shell {
    container: ds-product-card / inline-size;
  }

  @container ds-product-card (width >= 34rem) {
    .product-card {
      grid-template-columns: 8.5rem minmax(0, 1fr);
    }
  }
}

web.dev 也建议，在无法完整覆盖所有容器查询能力的环境中，基于断点的基础方案与容器化增强可以并存；这使渐进迁移比全量替换更可控。web.dev

验收标准要从“设备截图”升级为“宿主矩阵”

只验证手机、平板、桌面三个视口宽度，无法证明组件已经完成解耦。Container Queries 的测试单位应该从设备变成组件宿主。

至少覆盖下面这组维度：

验收时最值得问的问题不是“它在 1440px 下是否好看”，而是：

把这个组件移动到一个此前未出现过的宽度和嵌套层级中，它是否仍能在不增加页面特例的前提下保持可读、可操作、可预测？

如果答案是肯定的，Container Queries 才真正完成了从语法升级到组件契约升级。

结语：迁移的产物不是更多断点，而是更少页面知识

一次成功的 Container Queries 迁移，最终不应以“项目里新增了多少 @container”衡量，而应以这些变化衡量：

• 组件是否减少了对页面模板和栏目位置的了解；
• 父页面是否不再通过样式特例操纵组件内部排版；
• 断点是否能被解释为组件状态的临界条件；
• 新宿主场景出现时，是否优先复用组件能力，而不是追加覆盖规则。

先从一个高复用组件开始，建立“空间等级—呈现状态—回归用例”的最小闭环。等团队能稳定回答“这个组件为什么在这里切换布局”之后，再把这套契约推广到设计系统。这样，响应式布局才会从依赖页面历史的补丁集合，变成可移动、可组合、可验证的组件能力。

参考资料

• MDN：Using container size and style queries
• MDN：CSS container queries
• MDN：container-type
• W3C：CSS Containment Module Level 3
• web.dev：The new responsive
• web.dev：How to use container queries now
• Can I use：CSS Container Queries（Size）