← 返回生成器

二维码工作室 - 使用指南

欢迎使用二维码工作室。本工具支持高自由度定制的单张及批量二维码生成，配备完善的输入校验系统，并开放 REST API 供外部系统调用。

1. 界面概览

主界面分为左右两栏：

  • 左侧 — 控制面板：「单张生成」和「批量生成」两个标签页切换，输入内容后可调节尺寸、颜色、上传 Logo。
  • 右侧 — 预览面板：实时显示生成结果，提供下载、复制图片等操作。

右上角有中英文切换按钮。点击顶部「📖 使用说明」可随时回到本页面。

2. 单张生成

  1. 选中 "单张生成" 标签页。
  2. 在文本框中输入需要编码的内容——网址、文本或任意数据。
  3. 按需调节尺寸、二维码颜色和背景颜色（详见第 5 节）。
  4. 可选：点击 Logo 区域「选择文件」上传一张图片作为中心 Logo。
  5. 点击 "生成二维码"。
  6. 右侧预览区显示结果。可执行：下载（保存 qrcode.png）或 复制图片（粘贴到文档/聊天中）。

2.1 单张模式的限制规则

限制项数值超限行为
文本长度≤ 100 个字符自动截断至 100 字符，弹出红色 toast：「单条内容长度不能超过 100 个字符」
图片尺寸100–1000 px输入 >1000 时弹窗「当前模式下尺寸不能超过 1000px」并自动修正为 1000；输入非数字（如字母）时弹窗「请输入有效的数字（100-1000）」并重置为 300
💡 实时计数：文本框右上方实时显示 N / 100 字符数。达到上限时数字变红。
💡 清空按钮：输入内容后，标签行右侧出现 × 清空 按钮。点击一键将文本框恢复为空白初始状态。

3. 批量生成

  1. 选中 "批量生成" 标签页。
  2. 选择输入方式：
    • 手动输入：在文本框中每行写一条内容（每行独立生成一个二维码）。
    • 上传 TXT 文件：点击「📄 上传 TXT 文件」，选择一个 .txt 文件，内容自动加载。
  3. 点击 "生成二维码"。生成过程中显示「生成中…」。
  4. 完成后，点击 "全部下载 (ZIP压缩包)" 一次性获取所有二维码。

3.1 批量模式的限制规则

限制项数值超限行为
批量条目数≤ 100 条弹窗「批量生成最多支持100条内容」，上传 TXT 文件时也会校验
单条文本长度≤ 100 字符/条逐条校验，超长行自动截断并弹窗提示
图片尺寸100–500 px输入 >500 时弹窗「当前模式下尺寸不能超过 500px」并自动修正为 500；非数字同理弹窗重置为 300
API 频率限制5 次/分钟/IP后端返回 429 错误
💡 实时计数：文本框右上方实时显示 N / 100 条数。超限时数字变红并弹窗。
💡 清空按钮与文件联动：点击 × 清空 不仅清空文本，同时移除已上传的 TXT 文件、恢复文本输入区域，方便重新开始。
⚠ 互斥机制：手动输入内容后，上传 TXT 按钮自动禁用（半透明），防止误操作覆盖已有数据。清空文本后恢复可用。

4. 输入校验系统 — 完整参考

以下是所有校验规则的完整技术说明，涵盖触发时机、提示方式和自动修正行为。

4.1 单条文本长度 — 100 字符上限

  • 适用范围：单张生成的内容框、批量生成的每一行内容。
  • 触发时机：实时检测。每输入一个字符，系统立即计算当前长度。一旦 length > 100，在同一输入事件中完成截断和弹窗。
  • 具体行为：
    1. 字符计数器变红。
    2. 文本框内容被截取前 100 个字符（substring(0, 100)）。
    3. 页面顶部弹出红色 toast 通知，文案为「单条内容长度不能超过 100 个字符」，4 秒后自动消失。
  • 后端二次校验：API 接口同样检查 text.length > 100，超限返回 400 错误。前后双重保障。
  • 批量模式特殊说明：批量文本框中每行独立校验，超长行截断该行（不影响其他行）。若多行同时超长，仅弹窗一次（防重复弹窗骚扰）。

4.2 图片尺寸校验

尺寸输入框为 type="number"，接受键盘输入和鼠标滚轮/箭头调节。系统在以下三个层面进行校验：

实时输入校验（input / keyup / change 事件）

  • 取当前模式的 max 值（单张 1000、批量 500）。
  • 用户输入的数字一旦超过 max，立即弹窗「当前模式下尺寸不能超过 {max}px」，并自动将输入框值修正为 max。
  • 如果是合法数字且在范围内，不做任何干预。

失焦校验（blur 事件）

  • 非数字输入：如果用户输入了字母、符号等无法解析为数字的内容（如 abc、300px），失去焦点时弹窗「请输入有效的数字（100-{max}）」，并将值重置为默认值 300。
  • 低于最小值：若值 < 100，静默修正为 100（不弹窗，仅做最小值兜底）。
  • 超过最大值：二次兜底，修正为 max（blur 时再做一次安全网检查）。

模式切换时的自动适配

  • 从单张切换到批量时，max 属性自动变为 500。若当前值 > 500，自动降为 500（不弹窗，因这是模式切换而非用户输入）。
  • 从批量切换回单张时，max 恢复为 1000，当前值保持不变（不会自动放大）。

后端兜底

  • 单张接口：if (options.size > 1000) options.size = 1000。
  • 批量接口：if (options.size > 500) options.size = 500。
  • 即使前端校验被绕过（如直接调 API），后端也会兜底修正。

4.3 批量数量限制

  • 上限：每批 100 条。
  • 计数方式：按换行符拆分后，过滤空行，计算非空行数。
  • 触发行为：
    • 手动输入超过 100 行：计数器变红，弹窗提示「批量生成最多支持100条内容」。注意：不会截断内容（与文本长度不同），仅弹窗提示。用户需手动删除多余行。
    • 上传 TXT 文件超过 100 行：文件加载时校验，超限则弹窗并拒绝加载。
  • 后端校验：if (texts.length > 100) 返回 400 错误。

4.4 Toast 通知系统

所有弹窗提示统一使用红色 toast（而非浏览器原生 alert() 对话框）：

  • 样式：红色背景 #ef4444，白色文字，页面顶部居中，带下滑动画。
  • 时长：显示 4 秒后淡出消失。
  • 可叠加：新 toast 出现时自动覆盖旧 toast（取消旧定时器，刷新内容和显示时长）。
  • 降级保障：同时输出到浏览器 Console（console.warn），开发者可在控制台查看所有校验记录。

5. 自定义外观

颜色设置

两个独立的 HTML5 色彩轮盘分别控制二维码颜色（默认 #000000）和背景颜色（默认 #ffffff）。选色器右侧实时显示当前 Hex 值。

中心 Logo

支持 PNG / JPG / GIF / WebP 等常见格式。上传后自动缩放至二维码宽度的 25%，保留透明通道。文件大小上限 500KB。

⚠ 系统使用最高纠错级别 H 级（可恢复约 30% 码字损坏），配合 25% Logo 尺寸约束，确保二维码在嵌入 Logo 后仍可正常扫描。

6. 实用技巧

WiFi 自动连接二维码

输入以下格式，手机原生相机扫描后自动连接 WiFi（无需手动输入密码）：

WIFI:S:WiFi名称;T:WPA;P:WiFi密码;;

结尾必须带 ;;。加密类型 T:WPA 适用于大多数家用路由器，开放网络用 T:nopass。

Excel 动态二维码

在 Office 365 / Excel 2024 中，用 IMAGE 公式从单元格取值生成二维码：

=IMAGE("http://localhost:3000/api/generate?text=" & ENCODEURL(A1))

自定义颜色时，# 需转义为 %23：

=IMAGE("http://localhost:3000/api/generate?size=200&colorDark=%230000FF&text=" & ENCODEURL(A1))

7. API 接口 (面向开发者)

后端基于 Express，参数详情和完整 cURL 示例见 README.md。

单张生成

curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"text": "https://example.com", "size": 300}' \
  --output qrcode.png

批量生成

curl -X POST http://localhost:3000/api/generate-batch \
  -H "Content-Type: application/json" \
  -d '{"texts": ["https://google.com", "Hello"]}' \
  --output batch.zip

QR Code Studio - User Guide

Welcome to QR Code Studio — a modern QR code generator with single & batch modes, comprehensive input validation, and a REST API for external integrations.

1. Interface Overview

  • Left — Control Panel: Switch between Single and Batch tabs. Input content, adjust size/colors, and upload logos.
  • Right — Preview Panel: Live preview of generated QR codes, with download and copy actions.

Use the language toggle (中文 / EN) in the top-right corner. Click «📖 Guide» in the header to return here.

2. Single Generation

  1. Select the "Single Generation" tab.
  2. Enter the content to encode — URL, text, or any data.
  3. Adjust size, colors, and optionally upload a logo (see section 5).
  4. Click "Generate QR Code".
  5. Use Download (saves qrcode.png) or Copy Image (pastes into documents/chats).

2.1 Single Mode Limits

ConstraintValueViolation Behavior
Text length≤ 100 charsAuto-truncate to 100, red toast: "Content length cannot exceed 100 characters per item"
Image size100–1000 px>1000: alert and cap to 1000. Non-numeric: alert and reset to 300
💡 Live counter: N / 100 shown above the text box. Turns red when over limit.
💡 Clear button: × 清空 appears next to the counter when content is present. One-click reset.

3. Batch Generation

  1. Select the "Batch Generation" tab.
  2. Input method:
    • Manual: One item per line (one QR code per line).
    • Upload TXT: Click «📄 Upload TXT File» and select a .txt file.
  3. Click "Generate QR Code".
  4. Click "Download All (ZIP)" to get a single archive of all QR codes.

3.1 Batch Mode Limits

ConstraintValueViolation Behavior
Item count≤ 100 itemsAlert: "Batch generation supports a maximum of 100 items"
Per-item length≤ 100 charsAuto-truncate per line with alert
Image size100–500 px>500: alert and cap to 500. Non-numeric: alert and reset to 300
API rate limit5 req/min/IPHTTP 429
💡 Live counter: N / 100 items shown in real time.
💡 Clear + File Reset: × 清空 clears text AND removes uploaded TXT file, restoring text input mode.
⚠ Mutual exclusion: Typing disables file upload (dimmed). Clear to re-enable.

4. Validation System — Full Reference

4.1 Text Length — 100-Character Cap

  • Scope: Single content box and every line in batch mode.
  • Trigger: Real-time on every keystroke. Once length > 100, truncation and alert happen in the same input event.
  • Behavior: Counter turns red → text truncated to 100 chars → red toast notification for 4 seconds.
  • Backend re-check: API returns 400 if text.length > 100.
  • Batch nuance: Each line validated independently. Only one alert fires even if multiple lines exceed limit.

4.2 Size Validation

The size input (type="number") is checked at three stages:

Real-time (input/keyup/change)

  • Compares against current mode's max (1000 single / 500 batch).
  • If exceeded: alert + auto-correct to max.

On blur

  • Non-numeric (e.g. "abc", "300px"): alert "Please enter a valid number (100-{max})" and reset to 300.
  • Below 100: silently correct to 100.
  • Above max: secondary safety cap to max.

Mode switch

  • Single → Batch: max becomes 500, value capped silently (mode change, not user input).
  • Batch → Single: max restored to 1000, value unchanged.

Backend fallback

  • Single: if (size > 1000) size = 1000.
  • Batch: if (size > 500) size = 500.

4.3 Batch Item Count

  • Cap: 100 items per batch.
  • Count method: Split by newline, filter empty lines.
  • Manual overflow: Counter turns red + alert. Content is NOT truncated — user must manually reduce lines.
  • File upload overflow: File rejected with alert.
  • Backend: 400 error if texts.length > 100.

4.4 Toast Notification System

  • Red (#ef4444) toast at top-center with slide-in animation.
  • 4-second display then fade-out.
  • New toast replaces previous (cancels old timer).
  • Also logged to browser console via console.warn for debugging.

5. Customization

Colors

Two native HTML5 color pickers for QR color (default #000000) and background (default #ffffff). Hex value shown beside each picker.

Center Logo

Supports PNG / JPG / GIF / WebP. Auto-resized to 25% of QR width, alpha channel preserved. File size limit: 500KB.

⚠ Uses error correction level H (~30% recovery) to maintain scannability with logo overlay.

6. Pro Tips

WiFi Auto-Connect QR

WIFI:S:NetworkName;T:WPA;P:Password;;

Must end with ;;. Use T:nopass for open networks.

Excel Dynamic QR

=IMAGE("http://localhost:3000/api/generate?text=" & ENCODEURL(A1))

Escape # as %23 for custom colors:

=IMAGE("http://localhost:3000/api/generate?size=200&colorDark=%230000FF&text=" & ENCODEURL(A1))

7. API (For Developers)

Express backend. Full parameter specs and cURL examples at README.md.

Single

curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"text": "https://example.com", "size": 300}' \
  --output qrcode.png

Batch

curl -X POST http://localhost:3000/api/generate-batch \
  -H "Content-Type: application/json" \
  -d '{"texts": ["https://google.com", "Hello"]}' \
  --output batch.zip