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