技能｜巨石SPA移动端响应式适配法
> 来源：<知识库系统>（FastAPI + 内联 HTML 巨石 SPA）经内网穿透在手机浏览器访问的适配实战（2026-10-03）。
> 起因：工作台原只有 1100/900/700px 窄窗降级，无真正手机视口（≤600px）适配 ⇒ 手机上侧栏 + 桌面壳标题条挤占空间、网格溢出。
适用场景
内联/单文件巨石 Web 应用（HTML/CSS/JS 全在一个字符串常量里）需要补手机视口（≤600px）响应式适配，且不能引入任何前端框架或构建工具（纯手写 CSS 断点）。
不适用：已用 Tailwind/Bootstrap 等响应式框架的项目、需独立移动 App 的场景。
触发词
移动端适配、手机访问、响应式、viewport、@media max-width、侧栏横排、网格单列、触摸目标、窄屏、手机上挤
操作步骤
-
先确认已有基础：
viewportmeta 是否设置；是否已有桌面窄窗断点（1100/900/700px）。手机适配是在其下的新增最小断点，不是推倒重来。 -
加手机断点：在 SPA 的
</style>前（注意：不要命中代码里字面量的"</style>"正则/字符串，要从 HTML 常量块内定位）追加@media(max-width:600px){...}。 -
布局重构（核心三招）：
- 隐藏桌面壳控制条：#titlebar{display:none}（手机没有无边框壳，那是 PC 专属）。
- 侧栏转顶部横排导航：#app{flex-direction:column}+#side变横向滚动条（overflow-x:auto;flex-direction:row），并强制展开折叠组（手机没空间做折叠，把navsub默认display打开）。
- 网格单列：所有grid-template-columns:repeat(N,...)改为1fr；行高仍用minmax(0,1fr)占位，但手机通常内容少、可改为auto。 -
阅读面板全屏：
#panel{position:fixed;inset:0;...}近满屏，关闭按钮加大。 -
触摸目标：按钮/可点项
min-height:42px;min-width:42px，列表项padding加大，避免误触。 -
登录/改密等独立页面：各自
</style>前加手机微调——隐藏右上角 ✕（#win-x{display:none}）、缩小卡片内边距。这些是居中卡片自适应，基本可用，只补细节。 -
回归断言：在测试脚本里加用例，断言三份页面（主 SPA / 登录 / 改密）都含
@media(max-width:600px)块；py_compile后跑全量回归。
注意边界
- 巨石 SPA 里
</style>可能多次出现（主 SPA 块 + 独立页面 + 代码里字面量正则）——注入 CSS 必须从 HTML 常量内定位，用全局首个</style>会误命中代码字符串、破坏语法。 - 手机适配不影响桌面：600px 断点只作用于窄屏，PC 宽屏走原布局。
- 不要为手机重打包 exe（桌面壳是 PC 宽屏，移动端 CSS 对其无影响，且重打包有沙箱删除风险）。
反例避雷
| 反例 | 为什么错 | 正确做法 |
|---|---|---|
CSS 注入用全局首个 </style> |
误命中代码里 re.sub 的字面量 "</style>"，语法破坏 |
从 HTML = r""" 常量内定位 </style> |
| 只做单列不改侧栏 | 侧栏 200px 仍挤占，手机第一屏看不到内容 | 侧栏转顶部横排 + 强制展开折叠组 |
| 保留桌面壳标题条 | 手机无壳，标题条占一行且点击无效 | #titlebar{display:none} |
| 触摸目标不放大 | 42px 以下手机难点中 | 按钮/列表项 min 42px |
