Blueprint 移动端体验优化：响应式布局 + 批注系统改进

[Camille1024]

问题描述

当前 blueprint 在手机上展示和批阅体验不好，主要表现在以下方面：

1. 字号过小、布局不响应

• plasTeX theme-white.css 仅有一个 1024px 断点，手机上正文字号 14px 偏小
• div.content-wrapper 的 max-width: 75ch 在窄屏上不合理
• 定理/引理块的左缩进在小屏上浪费空间

2. 数学公式溢出

• MathJax 渲染的长公式（交换图、长等式链）在小屏上横向撑破页面
• 缺少 overflow-x: auto 处理

3. TOC 侧边栏体验差

• nav.toc 在小屏下 display: none，toggle 后全屏覆盖但无触控优化
• TOC 链接的 padding 太小，手指难以准确点击

4. 底部导航遮挡内容

• nav.prev_up_next 使用 position: fixed; bottom: 0，遮挡正文
• 按钮可点击面积不满足 44px 最小触控标准

5. 批注面板不适合移动端

• annotation-panel 跟随文档流（无 position: fixed），双指放大页面后面板也被放大，按钮溢出
• 输入框 padding: 3px、字号 0.82rem，触控输入困难
• 软键盘弹出时面板位置无法自动调整

6. 批注系统依赖自建后端

• 当前 annotations.js 依赖 /api/review 后端服务
• GitHub Pages 静态部署下只能查看不能提交评论

方案调研

方案 A：移动端 CSS 修复 + 改进现有批注 UI

添加 mobile.css 响应式样式：

• @media (max-width: 768px) 下调整字号 (≥16px)、行高、缩进
• 数学公式容器添加 overflow-x: auto; -webkit-overflow-scrolling: touch
• TOC 改为侧边滑入覆盖层，增大链接 padding
• 底部导航增大触控面积，正文预留 padding-bottom
• 批注面板改为 position: fixed 底部 sheet 样式

优点： 无外部依赖，保留 status.yaml 工作流
缺点： 仍需自建后端才能写评论；position: fixed 在移动端有 visualViewport 兼容问题

方案 B：集成 Hypothes.is

在 blueprint HTML 中嵌入 Hypothes.is：

<script src="https://hypothes.is/embed.js" async></script>

优点：

• 一行代码集成，完全托管，无需自建后端
• 支持文本级批注（选中任意文本即可标注），比现有 node 级更细粒度
• 独立 iframe + position: fixed，放大页面后批注面板保持正常大小
• 支持 Group 隔离（可创建私有审阅组）
• 提供 REST API 可导出批注数据

缺点： 批注数据在第三方；和现有 node-level 审阅工作流是两套体系

方案 C：A + B 组合（推荐）

层面	方案 A 解决	方案 B 解决
字号/布局	✅ 响应式 CSS	❌
公式溢出	✅ overflow-x: auto	❌
TOC 导航	✅ 滑出式侧边栏	❌
放大后批注	⚠️ 需 visualViewport hack	✅ iframe 天然隔离
文本级批注	❌ 仅 node 级	✅ 选中即标注
无需后端	❌ 需 /api/review	✅ 完全托管

建议实施步骤

1. 新建 mobile.css (~150 行)，通过 plastex.cfg 的 extra-css 引入
2. 嵌入 Hypothes.is embed script，配置 showHighlights: "whenSidebarOpen"
3. 在 build.sh 构建流程中确保 mobile.css 被同步到 docs/blueprint/
4. 测试主要移动端浏览器（iOS Safari、Android Chrome）的表现