vscode-workbench/.trae/documents/qrcode-generator-mobile.md

二维码生成器移动端适配计划

Why

当前二维码生成器（/qrcode-generator）仅通过 CSS 媒体查询实现基础响应式布局，在移动端存在以下问题：

• 两栏布局在小屏幕上操作不便
• 高级设置区域拥挤，难以操作
• 触摸体验未针对移动设备优化
• 缺少独立的移动端组件，与其他工具（Base64Tool、JsonFormatter 等）的适配模式不一致

What Changes

创建独立的移动端组件 QRCodeGeneratorMobile，为移动设备提供优化的用户体验。

Impact

• New files:
  • chunyu_project_react/src/pages/QRCodeGenerator/QRCodeGeneratorMobile.tsx - 移动端组件
  • chunyu_project_react/src/pages/QRCodeGenerator/QRCodeGeneratorMobile.css - 移动端样式
• Modified files:
  • chunyu_project_react/src/App.tsx - 更新路由，支持移动端检测

设计方案

移动端组件结构

参考 Base64ToolMobile 的设计模式：

┌─────────────────────────────────┐
│  ← 返回    二维码生成器    [收藏] │
├─────────────────────────────────┤
│                                 │
│         二维码预览区域           │
│      （生成后显示二维码）         │
│                                 │
├─────────────────────────────────┤
│  [下载二维码]  [清空]            │
├─────────────────────────────────┤
│  文本输入区域                    │
│  ┌─────────────────────────┐    │
│  │                         │    │
│  │   请输入文本或URL...     │    │
│  │                         │    │
│  └─────────────────────────┘    │
│  [生成二维码]                    │
├─────────────────────────────────┤
│  高级设置（可折叠）              │
│  ▼ 容错率 / 版本 / 尺寸         │
│  ▼ 颜色设置（预设色板）          │
│  ▼ 形状设置（点阵/定位样式）     │
│  ▼ Logo 上传                    │
└─────────────────────────────────┘

核心功能保留

• 文本/URL 输入
• 二维码实时生成预览
• 下载 PNG 功能
• 容错率设置（L/M/Q/H）
• 尺寸预设（300/400/500/1000px）
• 颜色预设（12种配色方案）
• 形状设置（点阵样式 + 定位图案）
• Logo 上传

移动端优化点

1. 单列布局：从上到下依次排列，避免左右分栏
2. 可折叠设置区：高级设置默认折叠，点击展开
3. 触摸友好：增大按钮和输入区域
4. 预设色板：使用色块网格展示，便于触摸选择
5. 简化操作：减少层级，常用功能直接展示

具体修改

1. 创建 QRCodeGeneratorMobile.tsx

路径: chunyu_project_react/src/pages/QRCodeGenerator/QRCodeGeneratorMobile.tsx

核心结构：

const QRCodeGeneratorMobile: React.FC = () => {
  // 状态管理（与桌面端共享 qrRenderer 工具）
  const [text, setText] = useState("");
  const [qrValue, setQrValue] = useState("");
  const [fgColor, setFgColor] = useState("#000000");
  const [bgColor, setBgColor] = useState("#ffffff");
  const [errorLevel, setErrorLevel] = useState<ErrorLevel>("M");
  const [sizePreset, setSizePreset] = useState<number>(400);
  const [dotStyle, setDotStyle] = useState<DotStyle>("square");
  const [finderStyle, setFinderStyle] = useState<FinderStyle>("square");
  const [logo, setLogo] = useState<QRCodeLogo | null>(null);
  const [logoSizePercent, setLogoSizePercent] = useState<number>(20);
  const [settingsOpen, setSettingsOpen] = useState(false);
  const [colorOpen, setColorOpen] = useState(false);
  const [shapeOpen, setShapeOpen] = useState(false);
  const [logoOpen, setLogoOpen] = useState(false);

  // 使用共享的 drawQRCode 函数
  // 使用 useRecordHistory 记录历史
  // 使用 useNavigate 导航
  // 使用 useTranslation 国际化
};

2. 创建 QRCodeGeneratorMobile.css

路径: chunyu_project_react/src/pages/QRCodeGenerator/QRCodeGeneratorMobile.css

样式特点：

• 单列布局
• 大按钮设计（最小 44px 触摸目标）
• 可折叠面板动画
• 预设色板网格（3列或4列）
• 暗色模式支持

3. 更新 App.tsx 路由

路径: chunyu_project_react/src/App.tsx

修改前：

<Route path="/qrcode-generator" element={<QRCodeGenerator />} />

修改后：

<Route path="/qrcode-generator" element={isMobile ? <QRCodeGeneratorMobile /> : <QRCodeGenerator />} />

Assumptions & Decisions

• 复用桌面端的 drawQRCode 工具函数，保持生成逻辑一致
• 移动端不显示粒子动画效果，提升性能
• 高级设置默认折叠，减少初始界面复杂度
• 预设色板使用网格布局，便于触摸选择
• 二维码预览区域保持固定比例，确保扫描可靠性

Verification

1. 在移动端访问 /qrcode-generator，确认显示移动端组件
2. 在桌面端访问 /qrcode-generator，确认显示桌面端组件
3. 测试文本输入和二维码生成功能
4. 测试下载功能
5. 测试高级设置（容错率、尺寸、颜色、形状）
6. 测试 Logo 上传功能
7. 测试暗色模式切换
8. 测试浏览器窗口缩放时的响应