From 9a204d0312096607df79e50cb801d956fc980ffe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com> Date: Sat, 20 Jun 2026 17:29:46 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20CLI=20=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=E6=89=8B=E5=86=8C=20docs/CLI=5FUSAGE.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 完整覆盖 7 种编码模式（text/url/wifi/vcard/email/phone/sms） - 批量生成（JSON/CSV）+ 解码 + 所有参数说明 - 格式对比表 + 纠错级别指南 + 常见问题 - README 社区区新增手册链接 --- README.md | 1 + docs/CLI_USAGE.md | 375 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 376 insertions(+) create mode 100644 docs/CLI_USAGE.md diff --git a/README.md b/README.md index 07a4c1b..4d73237 100644 --- a/README.md +++ b/README.md @@ -359,6 +359,7 @@ cargo add qr-core ## 社区 +- [CLI 使用手册](docs/CLI_USAGE.md) — 命令行完整指南 - [贡献指南](CONTRIBUTING.md) — 如何参与开发 - [行为准则](CODE_OF_CONDUCT.md) — 社区规范 - [安全策略](SECURITY.md) — 漏洞报告流程 diff --git a/docs/CLI_USAGE.md b/docs/CLI_USAGE.md new file mode 100644 index 0000000..0c0d470 --- /dev/null +++ b/docs/CLI_USAGE.md @@ -0,0 +1,375 @@ +# QRGen CLI 使用手册 + +`qrgen` 是 QRGen 的命令行工具，支持 QR 码的**编码**（文本 → QR 图）和**解码**（QR 图 → 文本），输出 PNG/BMP/JPEG/WebP/SVG/终端 ASCII 六种格式。 + +## 快速开始 + +```bash +# 终端预览 QR 码 +qrgen "Hello World" + +# 生成 PNG +qrgen "https://example.com" -o qr.png + +# 生成 SVG +qrgen "重要数据" -o qr.svg -l H + +# 解码 QR 图片 +qrgen --decode qr.png +``` + +--- + +## 基础编码 + +### 语法 + +```bash +qrgen [内容] [选项] +``` + +### 选项 + +| 选项 | 说明 | 默认值 | +|------|------|--------| +| `-o, --output <文件>` | 输出文件路径（.png/.bmp/.jpg/.webp/.svg） | 终端 ASCII 输出 | +| `-l, --level <级别>` | 纠错级别：`L`(7%) `M`(15%) `Q`(25%) `H`(30%) | `M` | +| `-v, --version <1-40>` | 手动指定 QR 版本 | 自动选择 | +| `-s, --size <像素>` | 每个模块的像素大小（图像输出） | `4` | +| `-m, --margin <模块>` | 白边宽度（模块数） | `4` | +| `-f, --format <格式>` | 图像输出格式：`png` `bmp` `jpeg` `webp` | 从文件扩展名推断 | +| `--fg <颜色>` | 前景色 `#RRGGBB` 或 `#RGB` | `#000` | +| `--bg <颜色>` | 背景色 `#RRGGBB` 或 `#RGB` | `#FFF` | +| `--logo <文件>` | 在 QR 码中央叠加 Logo 图片 | 无 | +| `--invert` | 反色输出（终端 ASCII） | — | + +### 示例 + +```bash +# 基础生成 +qrgen "Hello World" -o hello.png + +# 高纠错 + 大尺寸 +qrgen "重要合同编号: ABC-12345678" -o contract.png -l H -s 8 -m 6 + +# 彩色 QR 码 +qrgen "My Brand" -o brand.png --fg "#FF5733" --bg "#FFF8E7" + +# 带 Logo +qrgen "https://mycompany.com" -o logo.png -l H --logo avatar.png + +# JPEG 输出 +qrgen "JPEG test" -o qr.jpg -f jpeg + +# WebP 输出 +qrgen "WebP test" -o qr.webp -f webp + +# 指定版本（强制版本 5） +qrgen "Fixed version" -o fixed.png -v 5 +``` + +--- + +## 编码模式 + +通过 `--mode` 参数可以使用 7 种编码模式，自动构造标准格式文本，无需手动拼接。 + +### 文本模式（默认） + +```bash +qrgen "任意文本内容" -o text.png +``` + +等同于： +```bash +qrgen --mode text "任意文本内容" -o text.png +``` + +### URL 模式 + +```bash +qrgen --mode url --url "https://github.com/LHY0125/QRGen" -o url.png +``` + +### WiFi 模式 + +```bash +# 基础 WiFi +qrgen --mode wifi --ssid MyWiFi --password pass123 -o wifi.png + +# 无密码 WiFi +qrgen --mode wifi --ssid FreeWiFi --encryption nopass -o free-wifi.png + +# 隐藏网络 + WPA2 +qrgen --mode wifi --ssid HiddenNet --password secret --encryption WPA2 --hidden -o hidden.png +``` + +生成的 QR 内容格式：`WIFI:T:WPA;S:MyWiFi;P:pass123;;` + +| 参数 | 说明 | 默认值 | +|------|------|--------| +| `--ssid` | WiFi 名称 | 必填 | +| `--password` | WiFi 密码 | 空 | +| `--encryption` | 加密方式：`WPA` `WPA2` `WEP` `nopass` | `WPA` | +| `--hidden` | 隐藏网络标志 | false | + +### vCard 模式（电子名片） + +```bash +# 基础名片 +qrgen --mode vcard \ + --name "张三" \ + --phone "13800138000" \ + --email "zhangsan@example.com" \ + -o card.png + +# 完整名片（10 字段） +qrgen --mode vcard \ + --name "张三" \ + --phone "13800138000" \ + --email "zhangsan@example.com" \ + --company "科技有限公司" \ + --title "高级工程师" \ + --address "北京市海淀区" \ + --vcard-url "https://zhangsan.com" \ + --birthday "1995-06-15" \ + --note "爱好: 编程, 摄影" \ + --photo "https://zhangsan.com/avatar.jpg" \ + -o full-card.png +``` + +| 参数 | 说明 | +|------|------| +| `--name` | 姓名 | +| `--phone` | 电话 | +| `--email` | 邮箱 | +| `--company` | 公司 | +| `--title` | 职位 | +| `--address` | 地址 | +| `--vcard-url` | 个人网址 | +| `--birthday` | 生日 `YYYY-MM-DD` | +| `--note` | 备注 | +| `--photo` | 照片 URL | + +### Email 模式 + +```bash +qrgen --mode email \ + --to "hello@example.com" \ + --subject "合作洽谈" \ + --body "您好，我对贵公司的产品很感兴趣。" \ + -o email.png +``` + +生成的 QR 内容格式：`mailto:hello@example.com?subject=...&body=...` + +### 电话模式 + +```bash +qrgen --mode phone --number "13800138000" -o phone.png +``` + +扫描后直接拨号。 + +### 短信模式 + +```bash +qrgen --mode sms \ + --number "13800138000" \ + --message "你好，方便电话吗？" \ + -o sms.png +``` + +--- + +## 批量生成 + +从 JSON 或 CSV 文件批量生成 QR 码。 + +### JSON 格式 + +```json +[ + {"content": "产品 A", "level": "H"}, + {"content": "产品 B", "level": "M"}, + {"content": "产品 C"} +] +``` + +```bash +qrgen --batch items.json --output-dir ./qr_output/ +# 输出: qr_output/qr_0001.png, qr_output/qr_0002.png, ... +``` + +### CSV 格式 + +```csv +content,level +"产品 A",H +"产品 B",M +"产品 C",M +``` + +```bash +qrgen --batch items.csv --output-dir ./qr_output/ -s 8 +``` + +### 批量 WiFi 名片 + +JSON 中可以用模式专用字段： + +```json +[ + {"ssid": "Office-1F", "password": "pass1", "encryption": "WPA2"}, + {"ssid": "Office-2F", "password": "pass2", "encryption": "WPA2"}, + {"ssid": "Guest", "encryption": "nopass"} +] +``` + +支持的批量字段：`content` `url` `ssid` `password` `encryption` `hidden` `name` `phone` `email` `company` `address` `to` `subject` `body` `number` `message` + +--- + +## 解码 + +从图片文件解码 QR 码内容。 + +```bash +qrgen --decode qr.png +qrgen -d qr.jpg +``` + +输出示例： +``` +解码成功: + 文本: https://example.com + 版本: 3 + 纠错级别: M + 掩码: 2 + 纠正错误: 0 码字 +``` + +支持格式：PNG、JPEG、WebP、BMP。 + +解码器会自动对倾斜图片做旋转矫正。 + +--- + +## 纠错级别说明 + +| 级别 | 纠错率 | 适用场景 | +|------|--------|----------| +| L | ~7% | 屏幕显示、数字传输 | +| M | ~15% | 日常打印（默认） | +| Q | ~25% | 可能被遮挡的场景 | +| H | ~30% | Logo 嵌入、户外使用 | + +**注意：** 纠错越高，相同尺寸下可存储的文本越少。H 级建议与 Logo 嵌入配合使用。 + +--- + +## 文件格式对比 + +| 格式 | 特点 | 适用场景 | +|------|------|----------| +| PNG | 无损压缩，支持透明 | 通用推荐 | +| SVG | 矢量，无限缩放 | 印刷、网页嵌入 | +| JPEG | 有损压缩，文件小 | 照片场景 | +| WebP | 现代格式，文件最小 | Web 优化 | +| BMP | 无压缩，文件大 | 嵌入式系统 | +| ASCII | 终端字符画 | 快速预览 | + +--- + +## 完整参数列表 + +``` +Usage: qrgen [OPTIONS] [CONTENT] + qrgen --decode + +基础选项: + -o, --output 输出文件 (.png/.bmp/.jpg/.webp/.svg) + -l, --level 纠错级别 [default: M] + -v, --version <1-40> 手动指定版本 [default: auto] + -s, --size 模块像素大小 [default: 4] + -m, --margin 白边模块数 [default: 4] + -f, --format 图像格式: png/bmp/jpeg/webp [default: 由扩展名推断] + --fg <#RRGGBB> 前景色 [default: #000] + --bg <#RRGGBB> 背景色 [default: #FFF] + --logo Logo 图片文件 + --invert 终端反色 + +模式选项: + --mode 编码模式: text/url/wifi/vcard/email/phone/sms/batch + +WiFi 选项: + --ssid WiFi 名称 + --password WiFi 密码 + --encryption 加密方式: WPA/WPA2/WEP/nopass [default: WPA] + --hidden 隐藏网络 + +vCard 选项: + --name 姓名 + --phone 电话 + --email 邮箱 + --company 公司 + --title 职位 + --address <ADDR> 地址 + --vcard-url <URL> 个人网址 + --birthday <DATE> 生日 (YYYY-MM-DD) + --note <TEXT> 备注 + --photo <URL> 照片 URL + +Email 选项: + --to <ADDR> 收件人 + --subject <TEXT> 主题 + --body <TEXT> 正文 + +电话/短信选项: + --number <NUMBER> 电话号码 + --message <TEXT> 短信内容 + +URL 选项: + --url <URL> URL 链接 + +批量选项: + --batch <FILE> 批量输入文件 (JSON/CSV) + --output-dir <DIR> 批量输出目录 + +解码选项: + -d, --decode <FILE> 解码 QR 图片 +``` + +--- + +## 常见问题 + +### Q: 生成的 QR 码扫不出来？ + +1. 确保静区足够：`-m 4` 或更大 +2. 提高纠错级别：`-l H` +3. 增大模块尺寸：`-s 8` 或更高 +4. 如果是彩色 QR，确保前景/背景对比度足够 + +### Q: 如何生成超大文本的 QR 码？ + +降低纠错级别（L 级容量最大），或让系统自动选择版本： + +```bash +qrgen "很长的文本..." -o big.png -l L +``` + +### Q: Logo 叠加后扫不出来？ + +1. 使用 H 级纠错（`-l H`） +2. Logo 尺寸占 QR 区域约 25%，系统会自动缩放 +3. 确保 Logo 图片是 PNG 格式 + +### Q: 批量生成时如何指定纠错级别？ + +JSON 中每个条目可以设置 `"level": "H"`，也可以在命令行用 `-l H` 统一设置。 + +### Q: CSV 和 JSON 格式如何选择？ + +- JSON：支持嵌套字段，推荐用于 WiFi/vCard 等复杂模式 +- CSV：简单表格，适合纯文本批量生成