docs: QRGen GUI 版设计文档
This commit is contained in:
@@ -0,0 +1,206 @@
|
||||
# QRGen GUI 版 — 设计文档
|
||||
|
||||
**日期**: 2026-06-17
|
||||
**作者**: 刘航宇
|
||||
**技术栈**: Tauri 2 + React 18 + TypeScript + TailwindCSS
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
为 QRGen 添加桌面 GUI，采用和 PathEditor 一致的 Tauri 2 + React 架构，
|
||||
复用已有 `qr-core` 库。支持 7 种编码模式、实时预览、多格式导出和历史记录。
|
||||
|
||||
## 2. 架构
|
||||
|
||||
```
|
||||
QRGen/
|
||||
├── Cargo.toml # workspace: core + cli + gui
|
||||
├── core/ # 已有 qr-core 库（不动）
|
||||
├── cli/ # 已有 CLI（不动）
|
||||
└── gui/ # ★ 新增 Tauri 桌面应用
|
||||
├── Cargo.toml
|
||||
├── tauri.conf.json
|
||||
├── src/ # Rust 后端
|
||||
│ ├── main.rs
|
||||
│ └── lib.rs # Tauri commands
|
||||
└── src-frontend/ # React 前端
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── tailwind.config.ts
|
||||
├── index.html
|
||||
└── src/
|
||||
├── main.tsx
|
||||
├── App.tsx
|
||||
├── components/
|
||||
│ ├── ModePanel.tsx
|
||||
│ ├── QrPreview.tsx
|
||||
│ ├── ControlBar.tsx
|
||||
│ └── ExportPanel.tsx
|
||||
├── modes/
|
||||
│ ├── TextMode.tsx
|
||||
│ ├── UrlMode.tsx
|
||||
│ ├── WifiMode.tsx
|
||||
│ ├── VCardMode.tsx
|
||||
│ ├── EmailMode.tsx
|
||||
│ ├── PhoneMode.tsx
|
||||
│ └── SmsMode.tsx
|
||||
├── hooks/
|
||||
│ └── useQrEncode.ts
|
||||
├── store/
|
||||
│ └── history.ts
|
||||
└── types/
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## 3. 技术栈
|
||||
|
||||
| 层 | 技术 | 说明 |
|
||||
|---|------|------|
|
||||
| 桌面框架 | Tauri 2.6 | Rust 后端 + WebView 前端 |
|
||||
| 前端 | React 18 + TypeScript | 组件化 UI |
|
||||
| 样式 | TailwindCSS 4 | 磨砂玻璃效果 (backdrop-blur) |
|
||||
| 状态管理 | React Context + useReducer | 全局 QR 状态 |
|
||||
| 历史存储 | Tauri Plugin Store | 本地 JSON 持久化 |
|
||||
| QR 编码 | qr-core | 已有 Rust 库 |
|
||||
| 包管理 | pnpm | 与 PathEditor 一致 |
|
||||
|
||||
## 4. 界面布局（三栏 + 底部输入）
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ 🀫 QRGen _ □ × │
|
||||
├──────────┬──────────────────┬───────────────────┤
|
||||
│ │ │ │
|
||||
│ 模式面板 │ 实时预览区 │ 导出选项 │
|
||||
│ │ │ │
|
||||
│ ● 文本 │ ┌───────────┐ │ 模块: ──○── │
|
||||
│ ○ URL │ │ │ │ 纠错: [M ▼] │
|
||||
│ ○ WiFi │ │ QR 码 │ │ 边距: ──○── │
|
||||
│ ○ vCard │ │ SVG │ │ │
|
||||
│ ○ Email │ │ 实时预览 │ │ [复制] [PNG] │
|
||||
│ ○ 电话 │ │ │ │ [SVG] │
|
||||
│ ○ SMS │ │ │ │ │
|
||||
│ │ └───────────┘ │ 📋 历史记录 │
|
||||
│ │ │ · item 1 │
|
||||
│ │ 版本:5 61×61 │ · item 2 │
|
||||
├──────────┴──────────────────┴───────────────────┤
|
||||
│ 输入区（根据模式切换表单） │
|
||||
│ ┌─────────────────────────────────────────────┐│
|
||||
│ │ [模式专用表单字段] ││
|
||||
│ └─────────────────────────────────────────────┘│
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 各区域说明
|
||||
|
||||
| 区域 | 宽度 | 内容 |
|
||||
|------|------|------|
|
||||
| 左侧模式面板 | ~200px | 7 个模式单选按钮、历史记录入口 |
|
||||
| 中间预览区 | 自适应 | SVG QR 码实时预览、虚线边框、元信息 |
|
||||
| 右侧导出面板 | ~220px | 模块大小滑块、纠错级别、边距、导出按钮组、历史列表 |
|
||||
| 底部输入区 | 全宽 | 根据选中模式动态渲染表单组件 |
|
||||
|
||||
## 5. 编码模式 & 表单字段
|
||||
|
||||
| 模式 | QR 内容格式 | 表单字段 |
|
||||
|------|-----------|---------|
|
||||
| 文本 | 直接编码 | 文本输入框 (textarea) |
|
||||
| URL | 直接编码 | URL 输入框 + 协议自动补全 (https://) |
|
||||
| WiFi | `WIFI:T:<auth>;S:<ssid>;P:<pwd>;;` | SSID、密码、加密方式(WPA/WEP/nopass)、隐藏网络开关 |
|
||||
| vCard | `BEGIN:VCARD\n...\nEND:VCARD` | 姓名、电话、邮箱、公司、地址 |
|
||||
| Email | `mailto:<addr>?subject=<s>&body=<b>` | 收件人、主题、正文 |
|
||||
| 电话 | `tel:<number>` | 电话号码输入框 |
|
||||
| SMS | `smsto:<number>:<message>` | 电话号码、消息内容 |
|
||||
|
||||
## 6. 数据流
|
||||
|
||||
```
|
||||
用户输入 (200ms 防抖)
|
||||
→ React useReducer (QrState)
|
||||
→ Tauri invoke("encode_qr", { text, level, margin })
|
||||
→ Rust: qr_core::QrCode::encode()
|
||||
→ 返回 { svg, version, size, mask }
|
||||
→ React 更新 preview 状态
|
||||
→ SVG 渲染到预览区
|
||||
```
|
||||
|
||||
## 7. Tauri Commands（Rust → Frontend API）
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn encode_qr(text: String, level: String, margin: u8)
|
||||
-> Result<QrResponse, String>;
|
||||
|
||||
#[tauri::command]
|
||||
fn export_png(text: String, level: String, margin: u8, module_size: u8)
|
||||
-> Result<Vec<u8>, String>;
|
||||
|
||||
#[tauri::command]
|
||||
fn save_history(entry: HistoryEntry) -> Result<(), String>;
|
||||
|
||||
#[tauri::command]
|
||||
fn load_history() -> Result<Vec<HistoryEntry>, String>;
|
||||
|
||||
#[tauri::command]
|
||||
fn clear_history() -> Result<(), String>;
|
||||
```
|
||||
|
||||
## 8. 状态结构（TypeScript）
|
||||
|
||||
```typescript
|
||||
interface QrState {
|
||||
mode: 'text' | 'url' | 'wifi' | 'vcard' | 'email' | 'phone' | 'sms';
|
||||
formData: Record<string, string>;
|
||||
config: {
|
||||
level: 'L' | 'M' | 'Q' | 'H';
|
||||
margin: number;
|
||||
moduleSize: number;
|
||||
};
|
||||
preview: {
|
||||
svg: string | null;
|
||||
version: number;
|
||||
size: number;
|
||||
mask: number;
|
||||
} | null;
|
||||
history: HistoryEntry[];
|
||||
}
|
||||
|
||||
interface HistoryEntry {
|
||||
id: string;
|
||||
mode: string;
|
||||
content: string;
|
||||
timestamp: number;
|
||||
}
|
||||
```
|
||||
|
||||
## 9. 历史记录
|
||||
|
||||
- 最近 50 条，FIFO
|
||||
- Tauri Plugin Store 持久化为本地 JSON
|
||||
- 右侧面板显示列表，点击回填
|
||||
- 支持逐条删除 + 一键清空
|
||||
|
||||
## 10. 视觉效果
|
||||
|
||||
- 磨砂玻璃效果：`backdrop-blur-xl bg-white/70 dark:bg-gray-900/70`
|
||||
- 圆角卡片：`rounded-2xl`
|
||||
- 柔和阴影：`shadow-lg shadow-black/5`
|
||||
- 预览区虚线边框：`border-2 border-dashed border-gray-300`
|
||||
- 模式选中态高亮：渐变蓝色 `bg-gradient-to-r from-blue-500 to-cyan-500`
|
||||
- 暗色模式支持（跟随系统）
|
||||
- 窗口最小尺寸：900×650
|
||||
|
||||
## 11. 不实现的范围
|
||||
|
||||
- QR 码解码/扫描
|
||||
- 批量生成
|
||||
- 自定义 Logo 嵌入（艺术 QR）
|
||||
- 打印功能
|
||||
- 自动更新
|
||||
|
||||
## 12. 里程碑
|
||||
|
||||
1. **M1**: Tauri 脚手架 + qr-core 集成 + 基础布局
|
||||
2. **M2**: 文本模式 + URL 模式 + 实时预览
|
||||
3. **M3**: WiFi + vCard + Email + 电话 + SMS 全模式
|
||||
4. **M4**: 导出功能 + 历史记录 + 暗色模式
|
||||
5. **M5**: 打包配置 + 图标 + 最终测试
|
||||
Reference in New Issue
Block a user