docs: 新增 CLI 使用手册 docs/CLI_USAGE.md
- 完整覆盖 7 种编码模式（text/url/wifi/vcard/email/phone/sms） - 批量生成（JSON/CSV）+ 解码 + 所有参数说明 - 格式对比表 + 纠错级别指南 + 常见问题 - README 社区区新增手册链接
This commit is contained in:
@@ -359,6 +359,7 @@ cargo add qr-core
|
||||
|
||||
## 社区
|
||||
|
||||
- [CLI 使用手册](docs/CLI_USAGE.md) — 命令行完整指南
|
||||
- [贡献指南](CONTRIBUTING.md) — 如何参与开发
|
||||
- [行为准则](CODE_OF_CONDUCT.md) — 社区规范
|
||||
- [安全策略](SECURITY.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 <FILE>
|
||||
|
||||
基础选项:
|
||||
-o, --output <FILE> 输出文件 (.png/.bmp/.jpg/.webp/.svg)
|
||||
-l, --level <L/M/Q/H> 纠错级别 [default: M]
|
||||
-v, --version <1-40> 手动指定版本 [default: auto]
|
||||
-s, --size <PIXELS> 模块像素大小 [default: 4]
|
||||
-m, --margin <MODULES> 白边模块数 [default: 4]
|
||||
-f, --format <FORMAT> 图像格式: png/bmp/jpeg/webp [default: 由扩展名推断]
|
||||
--fg <#RRGGBB> 前景色 [default: #000]
|
||||
--bg <#RRGGBB> 背景色 [default: #FFF]
|
||||
--logo <FILE> Logo 图片文件
|
||||
--invert 终端反色
|
||||
|
||||
模式选项:
|
||||
--mode <MODE> 编码模式: text/url/wifi/vcard/email/phone/sms/batch
|
||||
|
||||
WiFi 选项:
|
||||
--ssid <NAME> WiFi 名称
|
||||
--password <PWD> WiFi 密码
|
||||
--encryption <TYPE> 加密方式: WPA/WPA2/WEP/nopass [default: WPA]
|
||||
--hidden 隐藏网络
|
||||
|
||||
vCard 选项:
|
||||
--name <NAME> 姓名
|
||||
--phone <NUMBER> 电话
|
||||
--email <ADDR> 邮箱
|
||||
--company <NAME> 公司
|
||||
--title <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：简单表格，适合纯文本批量生成
|
||||
Reference in New Issue
Block a user