SuperAPI AI 工具集

migrate-container-queries

前端与建站

查看项目

更新于 10-16 05:48

技能介绍

用途:把 Sentry 前端中基于视口的响应式逻辑迁移为容器查询,使组件响应自身可用空间而非原始视口。

主要能力与迁移阶梯(取最低可行层级):

  1. 原始属性:当 @media 仅切换布局(flex-direction、display、grid-template、gap、visibility、width)时,删除 styled 组件,改用 Container/Flex/Grid/Stack 的响应式属性,如 direction={{xs: 'column', md: 'row'}}。
  2. @container 替换:CSS 无法作为属性时(后代选择器、伪元素、font-size、复杂 grid-template-areas),保留 styled 组件,把 @media 换成 @container,theme.breakpoints.* 换成 theme.container.*。
  3. 容器作用域 JS:JS 中读取宽度分支渲染时,用 useResponsivePropValue({...}) 得到阈值布尔,或用 useContainerBreakpoint() 按活动键分支。
  4. 保留 useMedia:仅用于非宽度的真实媒体特性(prefers-color-scheme、prefers-reduced-motion、hover、pointer、max-height/高度、resolution、print)。

关键规则:断点与容器刻度键名和像素值都不同,必须按像素值映射,不能按同名键。例如 breakpoints.sm 是 800px,应映射到 container.xl(768px),而非 container.sm(512px)。同名键复用是头号迁移 bug。

真实视口宽度:当布局确实跟随窗口时,不要保留 useMedia,改用 screen: 前缀响应式属性,如 direction={{zero: 'column', 'screen:lg': 'row'}},裸键与 screen: 键可混用。已有 screen: 属性也是迁移候选,若布局响应组件可用宽度,去掉 screen: 前缀改用裸容器键。

container-type:默认不加。裸键与 @container 已对最近祖先容器解析,产品视图已有容器(ContentStack 的 #main 设置 containerType="inline-size")。仅当子树需响应自身宽度时添加,使用 inline-size;可复用组件中可用 useHasContainerQuery() 条件设置以避免冗余。

限制与检查:@container 无查询容器祖先时会静默失效;每次迁移后必须调整元素(而非仅窗口)尺寸做视觉检查,确认布局一致并在预期宽度翻转。token 刻度不同,机械替换即使能编译也可能渲染错误。