响应式 Web:移动优先、任意技术栈、自动验证
目标是布局能够在每种宽度下正常工作,而不是在有人挑选的五种设备宽度下工作。
Bug 往往存在于中间:412px、905px,以及 max-width: 767px 和 min-width: 769px 都停止生效的那一个像素。因此,本技能包含两个始终必须同时进行的内容:
- 构建移动优先:编写布局使其自适应并且只需少量断点。
- 验证它:运行
scripts/check_responsive.py,该脚本会渲染页面并在每种宽度下测量布局。仅凭一两个截图说“看起来没问题”不算验证。完成意味着检查器报告 0 个错误。
检查器仅查看渲染后的页面(DOM 框和计算后的样式),因此它不关心 CSS 是如何编写的。这正是它适用于任何技术的原因。
0. 首先阅读项目
在编写 CSS 之前,花一分钟找到:
- 这里的样式是如何编写的:Tailwind(
tailwind.config.*或 CSS 中的@theme)、Bootstrap/SCSS 变量、CSS Modules、styled-components/emotion、Vue/Svelte 作用域样式、纯 CSS 文件。用同样的系统和相同的 token 编写新代码。第二个样式系统是一个维护 bug。 - 现有的断点,并重用它们。除非内容需要,否则不要发明新的断点。
- 如何查看页面:一个静态的
.html文件,或者一个开发服务器(npm run dev、php artisan serve、python manage.py runserver、rails s、dotnet watch...)。你需要一个 URL 或文件路径供检查器使用。
references/stacks.md 展示了常见技术栈的移动优先语法和断点位置。
1. 构建移动优先
为最小屏幕编写基础样式,不使用媒体查询。随着空间增大添加布局,使用 min-width 查询。 手机上获得最简单的 CSS,内容自然堆叠,每个断点只添加内容。桌面优先的方式(先写桌面,然后用 max-width 打补丁)会在补丁之间留下空隙,这些空隙正是大多数响应式 Bug 的来源。
如果代码库已经是桌面优先,不要重写它。在其约定内以移动优先的方式编写你新增或修改的部分,并修复检查器发现的问题。
优先使用无需断点即可自适应的布局
- 网格:
grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr))。列会根据空间自动出现,无需断点,且在 320px 下不会溢出(min(100%, …)部分正是为了防止溢出)。 - 应该换行的行:使用
display: flex; flex-wrap: wrap; gap: …和合理的flex-basis。 - 尺寸:使用
width: 100%; max-width: 40rem而不是width: 640px。使用clamp(min, preferred, max)实现流体的字体和间距。 - 出现在不同宽度插槽(侧边栏 vs 主列)中的组件:使用容器查询(
container-type: inline-size+@container),使其响应其插槽而非窗口。 - 在内容破坏处添加断点(缩小窗口直到某些内容看起来有问题),而不是在设备宽度处添加。
已知布局破坏者。编写时逐一检查。
| 破坏者 | 为什么破坏 | 改用 |
|---|---|---|
容器上固定的 width/min-width(单位 px) | 宽于 320px 的手机 | max-width + width:100%、%、fr、minmax() |
| 包含长内容的 flex/grid 子项 | 子项默认 min-width: auto 且拒绝收缩 | 在子项上设置 min-width: 0(或 minmax(0,1fr)) |
| 长单词、URL、电子邮件、代码 | 没有断词机会 | 在文本容器上设置 overflow-wrap: anywhere |
按钮/标签/导航上的 white-space: nowrap | 文本无法换行,撑开宽度 | 允许换行,或使用省略号 + min-width:0 + title 属性 |
| 图片、视频、iframe、嵌入内容 | 固有宽度大于屏幕 | max-width:100%; height:auto;对嵌入内容使用 aspect-ratio |
| 表格 | 列无法收缩到内容以下 | 包裹在 overflow-x:auto 容器中,或在小屏上将行堆叠 |
pre/code 块 | 保留空白 | 在块上设置 overflow-x:auto |
100vw | 包含滚动条,因此在桌面上大约宽 15px | 100%(或仅在真正全宽血统且谨慎处理时使用 100dvw) |
带文本的盒子上固定 height | 文本在手机上换行更多,导致溢出/裁剪 | min-height,或不设置高度 |
| 内容的绝对定位 | 不占据空间;在其他宽度下会碰撞 | 使用正常流/网格;仅装饰用绝对定位 |
用于英雄区的 height: 100vh | 移动端浏览器工具栏和短横屏会裁剪它 | min-height: 100svh(在此之前使用 100vh 作为回退) |
切勿掩盖症状
- 不要在
html/body上使用overflow-x: hidden来阻止侧向滚动。它隐藏了 bug,而内容仍然被裁剪(并且会破坏position: sticky)。找到那个太宽的元素。检查器会将这种掩盖上报为clipped-offscreen。 - 不要使用
user-scalable=no或maximum-scale=1。阻止缩放是无障碍访问失败(WCAG 1.4.4)。 - 不要使用 JavaScript 宽度检查或用户代理嗅探进行布局。CSS 媒体/容器查询可以无闪烁地完成。JS 可以用于行为(
matchMedia),但不能用于布局。 - 不要修改测试来让它通过(提高
--min、添加忽略项来使错误消失)。
触摸、输入、视口
- 每个页面的
<head>中都有<meta name="viewport" content="width=device-width, initial-scale=1">。 - 触摸目标至少 24x24px(WCAG 2.2 AA)。对于触摸屏上的按钮和图标控件,目标应达到 44x44px,并保持相邻元素间的间距。
- 仅悬停的 UI(菜单、显示内容的工具提示)需要
@media (hover: hover)和一个触摸替代方案。 - 表单字段在手机上
font-size应为16px或更大,否则 iOS Safari 会在聚焦时放大。使用适当的type、inputmode和autocomplete。 - 短横屏手机(高 320–430px)是真实存在的。固定的页眉加上 Cookie 横幅不应该覆盖超过屏幕的大约三分之一。在短高度下折叠或缩小它们(
@media (max-height: 500px))。 - 异形屏设备:仅在使用
viewport-fit=cover时,结合env(safe-area-inset-*)内边距使用。
排版、媒体、导航、内容
- 字体使用
rem,标题使用clamp(),行长度有上限(max-width: 65ch左右),无单位行高。 - 图片:照片使用
srcset/sizes,使用width/height属性或aspect-ratio避免布局偏移,当盒子比例与图片不同时使用object-fit: cover(否则图片会被拉伸)。 - 导航:在小屏幕上使用一个真实的
<button>,配合aria-expanded/aria-controls打开菜单。在内容实际能容纳的宽度下才显示内联链接。 - 保持内容一致:不要因为难以容纳而在移动端丢弃内容。可以重新排序、精简或折叠它。
references/patterns.md 为以上每一项(网格、导航、表格、表单、英雄区、卡片、媒体)都提供了可直接复制的 CSS。
2. 验证:运行检查器
一次性设置(Python 3.9+):
pip install playwright
python -m playwright install chromium
针对渲染后的页面运行它。如果存在开发服务器,请先启动它。
python <skill-dir>/scripts/check_responsive.py http://localhost:5173/ --out responsive-report
python <skill-dir>/scripts/check_responsive.py site/index.html --out responsive-report # 静态文件
- 多个页面:传入多个 URL。检查你更改的每个页面或路由,再加上一个使用共享布局(页眉/页脚)的页面。
- 渲染较晚的 SPA:使用
--wait-for "#app main"。需要登录的页面:使用--storage-state state.json。 - 修复时的内循环:使用
--quick(大约 5–10 秒)。在你说完成之前,请运行一次完整运行(每个页面大约 20–40 秒)。 - 退出代码:0 = 无错误,1 = 发现错误(或使用
--strict时发现警告),2 = 无法运行。
它所做的工作:以 10px 为步长扫描 320→1920px,加上常见设备宽度,以及页面自身 CSS 中发现的每个断点的两侧。它会使用真实的移动端模拟(触摸、元视口)重新加载关键宽度,并检查四个短横屏手机。在每个宽度下,它测量:
| 错误(必须修复) | 含义 |
|---|---|
horizontal-overflow | 页面侧向滚动;指出是哪个元素突出以及是什么强制它变宽 |
clipped-offscreen | 内容在屏幕边缘被裁剪(通常被 body 上的 overflow-x:hidden 隐藏) |
occluded-target | 链接/按钮被另一个元素覆盖(或被每个滚动位置都存在的固定栏覆盖) |
small-target | 触摸目标小于 24px 且被邻居挤占 |
text-spill / text-clipped | 文本溢出其盒子 / 被固定尺寸 + overflow:hidden 裁剪 |
text-overlap | 两个不相关块的文本绘制在彼此之上 |
distorted-media | 图片/视频被拉伸(盒子比例 ≠ 自然比例,没有 object-fit) |
viewport-meta、layout-viewport | 缺少/阻止缩放的视口元标签;手机以桌面宽度渲染 |
警告(修复它们或说明为什么不修复):touch-target(触摸宽度下 <44px 的控件)、small-text(手机上 <12px)、input-zoom(<16px 的输入框)、fixed-coverage(固定/粘性栏超过短屏的 35%)。
报告(report.md、report.json)会像这样对发现结果进行分组:
1. **horizontal-overflow** 发生在 320-610px;568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
- 最严重:在 320px 时超出右边缘 296 px
- 线索:在每个失败的宽度下都保持精确的 600px 宽度:这是一个固定宽度 - 请改用 max-width/%/fr/minmax
- 特写:responsive-report/closeups/01-horizontal-overflow-320.png
线索行就是诊断结果。在打开 CSS 之前先阅读它。
3. 修复循环
- 首先修复最小的失败宽度。移动端是基础,修复它通常也能修复其他问题。
- 修复线索指向的根本原因,在项目使用的源代码中(Tailwind 类、SCSS 部分、styled component)修复,而不是用一次性的覆盖。
references/checks.md列出了每个检查的原因和修复方法。 - 重新运行(
--quick),重复,然后进行一次完整运行。当错误为 0 且每个警告要么已修复要么有理由时停止。 - 有某些内容故意违反规则(一个装饰性形状溢出屏幕、英雄区拼贴中的故意重叠)?将该元素标记为
data-responsive-ignore="text-overlap"(以空格分隔的检查名称),并在代码中添加注释说明原因。忽略真实内容以通过检查等同于不测试。
4. 查看它
检查器能找到可测量的损坏问题。有些问题是不可测量的:尴尬的换行(按钮上一个孤立的词)、孤独的最后一个网格项、1920px+ 时巨大的空白 gutter、裁剪掉主体的图像、一个技术上没问题但难以使用的菜单。打开运行保存的截图(screens/320.png、375、768、1024、1440 和 closeups/)并查看它们。如果你无法查看图片,请在报告中说明,而不是声称进行了视觉审查。
当向用户报告视觉问题时,通过元素的内容和位置来描述它们("产品照片上的价格标签"、"菜单网格中的第二张卡片"),而不是通过类名。用户不阅读 DOM 选择器。将选择器保留在你自己的笔记中以便查找代码。
5. 仅审计请求
如果用户要求检查或审计一个网站(而不是修复),先运行完整的检查器,并按照严重性和宽度范围分组报告发现结果,附上截图,然后再触碰代码。如果范围很大,请在修复前询问。
6. 告知用户已验证的内容
最后以一个简短、事实性的总结结束:
- 你更改了什么(文件、组件);
- 测试了什么:页面、
N widths 320–1920px、横屏手机;检查器结果(0 errors, 1 warning); - 每个剩余的警告以及它们为何保留;
- 截图在哪里;
- 什么没有被验证。检查器仅使用 Chromium,因此 Safari/Firefox 怪异行为、真实设备键盘、纯文本 200% 缩放、RTL 以及未提供存储状态的登录后页面不在覆盖范围内,除非你单独测试了它们。
参考文件
references/patterns.md:常见构建块的可直接复制使用的移动优先 CSS。在构建新布局或组件时阅读它。references/stacks.md:移动优先和断点在 Tailwind、Bootstrap、SCSS、CSS Modules、CSS-in-JS、MUI/Chakra、Vue/Svelte/Angular、服务端模板中是什么样子的,以及如何为检查器提供每个服务。references/checks.md:每个检查器发现结果,附带典型原因、修复方法和已知的误报。当发现结果的原因不明显时阅读它。scripts/selftest/run_selftest.py:证明检查器仍然能捕获每种 Bug 类型(14 个测试用例)。在编辑检查器后运行它。