二维码批量生成工具 · 开发者手册

1项目概览

这是一个把「一张两列表格」批量转成「一堆带样式二维码图片」的纯前端工具。打包成单个 HTML 文件，双击即用，无需服务器、无需联网、无需安装任何依赖。

能力边界

代码规模

2设计原则与约束

1. 零依赖 —— 不引任何 CDN、npm 包。SheetJS、qrcode.js 这类常见库全部自研替代。
2. 单文件 —— 一个 .html 即完整产品，方便通过邮件/U 盘分发，双击即用。
3. 纯离线 —— 不发起任何网络请求，数据不离开本机。可断网验证。
4. IIFE + 严格模式 —— 全部逻辑包在一个立即执行函数里，避免污染全局；"use strict" 强制显式声明。
5. 渐进增强 —— CompressionStream 缺失时 ZIP 回退「存储模式」，功能不中断（仅体积变大）。
6. 能力透明 —— UI 文案与代码行为严格一致；不支持的组合（如 SVG 不含 LOGO）要在界面上明说。

3文件结构与代码分区

文件自上而下分为：<head> 内的样式 → <body> 的 DOM 骨架 → 单个 <script> 内的五个 PART。

<!DOCTYPE html>
<html>
  <head>
    <style>  ... 全部 CSS（约 440 行）  </style>
  </head>
  <body>
    <!-- 左栏：4 个步骤卡片；右栏：预览 + 文件清单 -->
    <script>
      "use strict";
      (function(){                      // 唯一入口 IIFE
        /* PART 1  QR 生成内核   */
        /* PART 2  xlsx 解析     */
        /* PART 3  渲染          */
        /* PART 4  ZIP 打包      */
        /* PART 5  界面逻辑      */
        (function init(){ ... })();       // 自检 + 首次渲染
      })();
    </script>
  </body>
</html>

4状态模型 state

const state = {
  data: [],          // [{ name, content }]  ← 双列模型，核心数据结构
  current: 0,        // 预览中的下标
  logoImg: null,     // 已加载的 LOGO Image 对象
  nameMode: "index", // 名称为空时的命名策略：index | content | custom
  textPos: "none",   // 展示文字位置：none | top | bottom
  fmt: "png"         // 输出格式：png | jpg | svg
};

两列数据模型（架构要点）

state.data 是 {name, content} 对象数组，而非字符串数组。这一点贯穿所有模块：

• parseTextRows / parseCsvRows / readXlsxRows → 产出 {name, content}[]
• fileNameFor(row, idx) → 依 row.name 或命名策略生成文件名
• getTextFor(row, st) → 依文字来源返回展示文字
• renderCanvas(row, st, scale) / renderSVG(row, st) → 接收 row 而非纯字符串

数据流（单向）

textarea.value
   │  parseTextRows()          // 唯一解析入口
   ▼
state.data ──┬─→ renderList()    // 文件清单
             ├─→ updateStats()   // 统计（重复/超长/缺内容）
             ├─→ updatePreview() // 预览单条
             └─→ exportZip()     // 批量导出

样式控件 ── readStyle() ──→ st（传给所有渲染函数）

5QR 生成内核

PART 1 是一个完整的 QR Code 生成器，思路参考 Nayuki 的算法结构，用纯 JS 重写。

5.1 GF(256) 有限域运算

// 预计算 exp/log 表，把乘法转成加法（查表）
const GF_EXP = new Uint8Array(512), GF_LOG = new Uint8Array(256);
(function(){
  let x = 1;
  for(let i = 0; i < 255; i++){
    GF_EXP[i] = x; GF_LOG[x] = i;
    x <<= 1; if(x & 0x100) x ^= 0x11D;   // 本原多项式 x^8+x^4+x^3+x^2+1
  }
  for(let i = 255; i < 512; i++) GF_EXP[i] = GF_EXP[i - 255];
})();

5.2 容量表（关键数据）

两张 41×4 的常量表，取自 ISO/IEC 18004 官方数据：

• ECC_CODEWORDS_PER_BLOCK[ver][eclIdx] —— 每块的纠错码字数
• NUM_ERROR_CORRECTION_BLOCKS[ver][eclIdx] —— 纠错块数

function getNumDataCodewords(ver, ecl){
  return Math.floor(getNumRawDataModules(ver) / 8)
    - ECC_CODEWORDS_PER_BLOCK[ver][idx] * NUM_ERROR_CORRECTION_BLOCKS[ver][idx];
}

5.3 分段编码

按内容自动选择最省的模式：

关键函数：isNumeric / isAlnum / makeSegments / getTotalBits / numCharCountBits。

5.4 纠错与交织

addEccAndInterleave 对每块数据计算 Reed-Solomon 纠错码，然后按列交织（interleave）成最终码字序列。配套函数：rsGenPoly、rsComputeDivisor、rsComputeRemainder。

5.5 矩阵构建与掩码

依次放置：定位图案（三个角）→ 校正图案 → 时序图案 → 格式信息 → 版本信息 → 数据。生成 8 种掩码各算惩罚分（PENALTY_*），选最低分的那个。

5.6 对外接口

function generateQR(text, ecl) → {
  version,          // 1–40
  size,             // 模块边长 = version*4 + 17
  mask,             // 选中的掩码 0–7
  getModule(x, y)   // → true(黑) / false(白)
};

6数据解析与 CSV 往返

6.1 解析入口 parseTextRows

把 textarea 的纯文本转成 {name, content}[]。分隔符优先级：Tab > 逗号 > 整行即内容。

function parseTextRows(text){
  const lines = splitCsvLines(text);   // ← 引号感知的行切分
  for(const line of lines){
    if(line.indexOf("\t") >= 0){      // Tab 优先
      const p = line.split("\t");
      name = p[0].trim(); content = p.slice(1).join("\t").trim();
    }else if(line.indexOf(",") >= 0){ // 逗号次之
      const cells = splitCsvLine(line);
      name = cells[0].trim(); content = cells.slice(1).join(",").trim();
    }else{ content = line.trim(); }   // 单列 → 全部当内容
  }
}

6.2 两个 CSV 工具函数

function splitCsvLines(text){
  const out = []; let cur = "", inQ = false;
  for(let i = 0; i < text.length; i++){
    const c = text[i];
    if(c === '"'){ inQ = !inQ; cur += c; }
    else if((c === "\n" || c === "\r") && !inQ){
      out.push(cur); cur = "";
      if(c === "\r" && text[i+1] === "\n") i++;  // 吃掉 \r\n
    }else cur += c;
  }
  out.push(cur); return out;
}

6.3 往返对称性（不变量）

必须满足：parseTextRows(setRowsToText(rows)) === rows。setRowsToText 要给名称和内容都做引号转义（早期只转义了内容，导致名称含逗号时结构被破坏）。

7xlsx 轻量解析

.xlsx 本质是个 ZIP。解析流程不依赖 SheetJS：

file.arrayBuffer()
   ▼  unzip()              // 解析 ZIP 中央目录，取所需条目
   ▼  inflateRaw()         // 用原生 DecompressionStream('deflate-raw') 解压
   ├─ xl/sharedStrings.xml → parseSharedStrings()  // 共享字符串表
   └─ xl/worksheets/sheet1.xml → parseSheet()      // 单元格
   ▼  readXlsxRows()       // → [{name, content}]，跳表头

关键点

• 中央目录解析：readU16 / readU32 按 PKZIP 结构定位每个条目的本地头与数据段
• 解压：inflateRaw 用浏览器原生 DecompressionStream('deflate-raw')；method=0 时直接用原始字节
• 单元格类型：s（共享字符串）、inlineStr（内联）、b（布尔）、其他按数字处理
• 列号换算：colToIndex("AB12") → {col, row}
• XML 反转义：unescapeXml 处理 < / & / & 等
• 自动跳表头：readXlsxRows(file, skipHeader)

8渲染管线（Canvas / SVG）

8.1 布局计算 layoutMetrics

function layoutMetrics(qr, st, textLine){
  const modules   = qr.size + st.quietZone * 2;   // 模块数（含静区）
  const modulePx  = st.sizePx / modules;          // 每模块像素
  const textPx    = textLine ? Math.round(st.textSize * 1.6) : 0;
  return { modules, modulePx, W: st.sizePx, H: st.sizePx + textPx };
}

8.2 Canvas 路径

renderCanvas(row, st, scale) → {canvas, qr}。绘制顺序：

1. drawModules —— 遍历矩阵画模块，支持三种样式（方形 / 圆点 / 圆角，圆角用 roundRect）
2. drawLogo —— 居中画 LOGO，按 logoRatio × sizePx 定尺寸；logoPad 为真时先垫一块白底
3. drawText —— 上/下绘制展示文字，超长自动缩字（fitText）

8.3 SVG 路径

renderSVG(row, st) 输出字符串。合并相邻模块为整段 <rect> 以减小体积；文字用 <text> + escapeXml() 转义。

8.4 三处调用的一致性

三处共用同一 renderCanvas，保证「预览所见 = 导出的样子」。

9ZIP 打包器实现

手写 PKZIP 格式，零第三方库。结构：本地文件头 + 数据 + 中央目录 + 中央目录结尾。

9.1 CRC32

const CRC_TABLE = (() => { ... })();   // 预计算 256 项查表
function crc32(buf){
  let c = 0xFFFFFFFF;
  for(let i = 0; i < buf.length; i++)
    c = CRC_TABLE[(c ^ buf[i]) & 0xFF] ^ (c >>> 8);
  return (c ^ 0xFFFFFFFF) >>> 0;
}

9.2 压缩 deflateRaw

async function deflateRaw(buf){
  if(typeof CompressionStream === "undefined") return null;  // → 调用方回退存储模式
  const cs = new CompressionStream("deflate-raw");
  const w = cs.writable.getWriter(); w.write(buf); w.close();
  return new Uint8Array(await new Response(cs.readable).arrayBuffer());
}

9.3 关键字段

9.4 偏移量与重名

offset 累计每个本地头 + 数据的长度，写进中央目录。重名文件自动追加 (2)、(3) 后缀，不覆盖。

10预览清晰度系统

二维码是高频黑白图形，用 CSS 强行放大一定会糊。解法是高倍率渲染 + 等比缩小。

const boxW = Math.max(240, Math.min(560, elSheet.parentElement.clientWidth - 72));
const cssScale = Math.min(1, boxW / st.sizePx);        // 显示尺寸
const showW   = Math.round(st.sizePx * cssScale);
const dpr     = window.devicePixelRatio || 1;
const renderScale = Math.min(4, Math.max(2, dpr));     // 渲染倍率，2×–4×

const r = renderCanvas(row, st, renderScale);          // 画布按高倍率渲染
r.canvas.style.width = showW + "px";                   // CSS 缩到显示尺寸

关键设计：sizePx 与 scale 解耦

• st.sizePx —— 逻辑尺寸（用户设定的输出边长）
• scale —— 渲染倍率（只影响预览画布的像素量）

旧实现用固定 1× 渲染再 CSS 放大 → 模糊；现在按 min(4, max(2, dpr)) 渲染，像素量提升 4–16 倍后降采样，放大看也锐利。

11性能分析与量级

在 Node + DOM 桩环境下实测（真机通常更快，仅作量级参考）：

结论

• 瓶颈只在 QR 编码本身；ECC H 约为 M 的两倍耗时（纠错码字更多）
• 解析与 CRC 可忽略不计
• 1000 条规模「生成 + 渲染 + 打包」整链 < 1 秒

主线程阻塞的缓解措施

• exportZip 按 CHUNK = 20 分批 await sleep(0) 让出主线程，同时更新进度条
• renderList 对 > 500 条只渲染前 500 项（LIMIT = 500），导出不受影响
• debounce 包裹文本域输入，避免每次按键都全量重解析 + 重绘

12已知问题与待办

12.1 设计上的取舍（非缺陷）

• SVG 不含 LOGO 与文字 —— 矢量输出保持纯粹，交由下游排版
• 无 undo 栈 —— 数据整理按钮直接改写文本域，可用 复制数据 先备份
• 旧浏览器 ZIP 不压缩 —— 回退存储模式，体积变大但可解压

12.2 潜在风险点

• 超大 LOGO（接近 25%）+ 低容错率 = 可能扫不出。UI 已提示「建议配 H 容错」
• CSV 模板在 Excel 直接双击时，个别环境中文可能乱码（BOM 已加；必要时用「从文本导入」并选 UTF-8）

12.3 可优化方向

• 把 generateQR 放进 Web Worker，彻底消除大数据集的界面卡顿
• 增加二维码「批量预览缩略图墙」
• 支持从粘贴板图片直接取 LOGO

13扩展指南

13.1 新增一种点样式（例：菱形）

1. 在 #dotStyle 的 <select> 里加一个 <option value="diamond">菱形</option>
2. 在 drawModules 的样式分支里加 else if(st.dotStyle === "diamond") 分支，用 ctx 画菱形路径
3. SVG 路径（renderSVG）同步加对应逻辑，保证两种输出一致

13.2 新增一种导出格式（例：WebP）

1. 导出区域加 <button data-v="webp">WebP</button>
2. state.fmt 会通过 seg 的通用事件自动更新
3. 在 exportOne / exportZip 里把 MIME 分支补上 "image/webp"
4. 确认 canvasToBlob 支持该类型（现代浏览器均支持）

13.3 新增一格「数据整理」按钮

$("btnXxx").addEventListener("click", () =>
  applyToRows(a => a.map(r => ({ ...r, content: 你的变换(r.content) })))
);

applyToRows 内部会调用 setRowsToText 写回并触发 refreshData，你只需提供纯变换函数。

13.4 代码风格约定

• 2 空格缩进；函数声明用 function name(){}
• 所有 DOM 引用走 $("id")，集中在 PART 5 顶部声明
• 注释说明「为什么」，而非「做什么」
• UI 文案必须与代码行为一致 —— 不支持的能力要在界面上显式说明，不能含糊

14调试与自测

14.1 语法检查

把 <script> 内容抽出后交给 Node：

node --check script.js

14.2 内核自检（打开即运行）

页面初始化时自动生成一个测试二维码，控制台输出：

[自检] QR 内核正常，版本 2，尺寸 25

14.3 id 连通性检查

用正则抽取 HTML 的 id 与 JS 的 $("...")，两边做集合比对，应「无缺、无余」。当前为 51 / 51 完全配对。

14.4 二维码正确性（权威验证）

把 generateQR 的矩阵导出为位图，交给主流扫码 App 同款算法 ZXing 解码比对原文：

import zxingcpp
res = zxingcpp.read_barcode(image)
assert res.text == original

14.5 往返自测（CSV 不变量）

const rows = [ {name:'a,b', content:'x,y'},
               {name:'q"t', content:'line1\nline2'} ];
setRowsToText(rows);
deepEqual(parseTextRows(elDataInput.value), rows);  // 必须相等

14.6 在 Node 里跑主脚本的要点

• 脚本区间用 findIndex(l => l.trim() === "<script>") 自定位，别写死行号
• 用 DOM 桩 + new Function(...) 执行；测试代码要注入到 IIFE 内最后的 })(); 之前，否则拿不到内部作用域
• Node 22 里 globalThis.navigator 只读；"use strict" 下隐式全局会抛错
• canvas 桩记得补 arcTo 等方法