手写一个纯离线二维码工具箱：架构、三个踩坑与 UI 重设计实录

目录

1. 为什么我不再用在线二维码工具
2. 技术选型：一个 HTML + 四个本地库
3. URL 多重解码：一个可能被略过的细节
4. 踩坑一：图片还没加载完，就开始了解析
5. 踩坑二：BarcodeDetector 的返回值是个 Promise
6. 踩坑三：解析失败？试试给图片做预处理
7. UI 重设计：从"能用"到"好用"
8. 可继续扩展的方向

1. 为什么我不再用在线二维码工具

需求其实很简单：识别一张截图里的二维码、给一段链接生成扫码图、批量解码条形码。

但打开任何一个在线工具都要过几道坎：

• 要联网，突然断网就没法用；
• 图片要上传到云端服务器，涉及隐私我用着不安心；
• 页面上广告和"再下载一个 App"的诱导比功能还多。

于是我决定做一个纯离线、单 HTML 文件、生成与解析一体的工具。目标是：下载到本地双击就能用，功能不依赖任何网络与后端，图片数据全程不离开本机内存。

模块清单：

2. 技术选型：一个 HTML + 四个本地库

整个项目的架构用一句话就能说清：所有逻辑与样式都写在一个 HTML 文件里，功能库以本地 <script> 方式引用，零构建、零依赖、零网络请求。

这也是我推荐给个人工具类项目的一种姿态：在不引入工程化成本的前提下，把可维护性做到极致。四个库各有明确分工，互不冗余：

• qrcode.min.js 负责生成。API 极简：new QRCode(el, { text, width, height, correctLevel })，还支持容错等级，我选了最高的 H 级；
• jsQR.min.js 负责解析二维码。它接受 canvas 像素数据，不用摄像头、不用后端，纯前端算出结果；
• JsBarcode 一行调用即可在 Canvas 上绘制多种条码格式；
• ZXing 是条码解析的"兜底杀手锏"，配合原生 BarcodeDetector 形成双通道。

选中这些库的共同理由是：体积小、文档简单、改造余地大。工具类项目里，能少依赖就少依赖，能本地化就本地化。

3. URL 多重解码：一个可能被略过的细节

decodeURIComponent() 一次只能解一层编码。如果 URL 被编码了多次（比如某些系统会反复 encodeURIComponent），只解一次就会得到一串充满 % 的残缺结果。

我的处理是用一个带终止条件的循环：

let decoded = input;
let lastDecoded;
do {
    lastDecoded = decoded;
    try {
        decoded = decodeURIComponent(decoded);
    } catch (e) {
        break;               // 已无可解字符或非法序列，安全退出
    }
} while (decoded !== lastDecoded && decoded.includes('%'));

这里的细节有三个：

1. try/catch 必须包住解码——遇到非法 % 序列会抛异常，不能让它影响外层流程；
2. decoded !== lastDecoded——解不动了就别再做无效循环；
3. includes('%')——没有百分号就说明已是纯文本，提前收手。

心得：写工具类函数时，把"输入为空、输入已是最简、输入非法"这三个边界想清楚，质量往往比主流程的实现更见功力。

4. 踩坑一：图片还没加载完，就开始了解析

这是整个开发过程中最典型的坑，也是很多前端新手会遇到的问题。

初版条码解析代码是这样写的：

const image = new Image();
new Promise((resolve, reject) => {
    image.onload = resolve;
    image.onerror = reject;
    image.src = currentBarcodeImageFile;
});

// ⚠️ 下面这些代码在图片加载完成前就执行了！
const canvas = document.createElement('canvas');
canvas.width = image.width;    // 此时 image.width 还是 0
canvas.height = image.height;  // 0
ctx.drawImage(image, 0, 0);    // 画了一张"空气"

new Promise(...) 只是声明了一个异步任务，并没有 await 它。于是在图片真正加载完成之前，后续同步代码已经拿着 image.width = 0 开始画布初始化了——canvas 是空的，解析永远失败，而且错误信息让人一头雾水。

正确写法是：先用 await 悬停，等 onload 触发再继续。

await new Promise((resolve, reject) => {
    image.onload = resolve;
    image.onerror = () => reject(new Error('条形码图片加载失败'));
    image.src = currentBarcodeImageFile;
});

心得：凡是依赖图片等异步资源继续执行的逻辑，必须保证"资源就绪"这个前置条件真正满足。我的检查清单是：这段代码是同步执行的吗？如果中间夹了异步 API，我有没有等它完成？建议把"加载资源"和"处理资源"拆成两段明确的生命周期。

5. 踩坑二：BarcodeDetector 的返回值是个 Promise

BarcodeDetector 是浏览器原生 API，不需要引第三方库，性能也更好。但我刚接入时就翻车了：

const barcodes = detector.detect(canvas);
if (barcodes.length > 0) {   // ❌ barcodes 实际是 Promise 对象
    ...
}

detect() 返回的不是数组而是 Promise。直接读 .length 得到 undefined，条件判断永远不成立，日志里也看不出明显报错。

正确写法同样是一个 await：

const barcodes = await detector.detect(canvas);
if (barcodes.length > 0) {
    resultTextarea.value = barcodes[0].rawValue;
}

心得：调用浏览器新 API 前，先确认它的返回类型。尤其近几年新增的 API（BarcodeDetector、File System Access、各类 Blink 新特性）几乎都是异步的。排查这类"代码没报错但不生效"的问题时，最快的验证手段就是：

console.log('barcodes:', barcodes);      // 先看原型链
console.log(barcodes instanceof Promise); // 再看是不是 Promise

6. 踩坑三：解析失败？试试给图片做预处理

ZXing 对模糊、低对比度、光照不均匀的图片，解析成功率会急剧下降。起初我以为是库的问题，后来发现：先对图片做预处理，远比换一个解析库有效。

我给图片做了一步"灰度化 + 自动对比度拉伸"：

for (let i = 0, j = 0; i < data.length; i += 4, j++) {
    const r = data[i], g = data[i+1], b = data[i+2];
    let gray = 0.299 * r + 0.587 * g + 0.114 * b;      // 标准灰度公式
    gray = Math.max(0, Math.min(255, (gray - 100) * 2)); // 对比度拉伸
    processed[j] = gray;
}

灰度公式使用了业界标准的 BT.601 系数（0.299 / 0.587 / 0.114），这是有科学依据的，而不是简单的三通道取平均值。把数据从"彩色噪点图"变成"黑白分明的高对比图"后，ZXing 的识别成功率提升了一个量级。

更进一步的兜底是：当所有解析器都失败时，写了一个兜底分析器——对图片做水平扫描，统计黑白条数量和分布，如果检测到条码特征但解码失败，就友好地提示用户"图片质量不佳"、“格式不支持"或"条码不完整”，并给出可操作的改进建议。

心得：在图像识别类任务里，"投喂给算法的输入质量"比"算法本身"更影响结果。先预处理数据，再谈换方案，是性价比最高的一条优化路径。

7. UI 重设计：从"能用"到"好用"

第一版是标准的"白底 + 紫蓝渐变"工具页，功能齐全但排布没有辨识度。我参照 Linear 风格（暗色精密感）重构了一个版本，并且刻意只改样式不动逻辑——保证功能零回归。

新版 UI 的几个关键决定：

• 微边框与高光：卡片使用 1px 半透明白色描边 + 顶沿渐变高光线，营造"精密仪器"的统一质感；
• 按钮语义化分层：主操作按钮用靛紫渐变 + 辉光；次操作按钮低调描边；危险操作（清空）用红色玻璃态。三种视觉权重一眼可分；
• 状态可视化：顶部常驻"状态胶囊"，配呼吸圆点三态（就绪 / 运行中 / 出错），替代原来角落里的一次性状态文字；
• 布局合并：二维码生成与条形码生成合并到同一张卡，用 Tab 切换，页面竖向滚动长度几乎减半。

重构的最大体会是：好 UI 不是装饰，而是一种信息设计。它要让用户不加思考就能回答三个问题——“这个按钮能点吗？点了发生什么？现在系统在干嘛？”。

题外话：如果你也想做这种"工具型页面"的视觉升级，建议把配色、动效、交互规范先写成设计变量（CSS 变量），再逐卡填充内容，这样整个页面的质感会非常统一。

8. 可继续扩展的方向

工具已经可用了，但如果想继续玩，下面几条很有价值：

1. 摄像头实时扫码：jsQR 已支持对视频帧流逐帧解析，加个 getUserMedia 就能做扫码枪；
2. 多二维码同时识别：jsQR 内部支持 locate 模式；给页面加个 FileSystem API 批量拖入，可一次解析多图；
3. 生成历史记录：用 localStorage 保存最近处理的 10 条 URL 与结果，支持一键复填；
4. 二维码样式化：qrcode 库支持前景/背景色自定义，可再加入 logo 融合与容错等级可选。

结尾：这件事告诉我，个人工具类项目最有价值的地方，往往不在"实现了什么"，而在"踩过的坑教会了你什么"。如果你也在造轮子，欢迎在评论区聊聊你的踩坑经历——互相交换经验，是最快的成长方式。