qrcode.js 自定义样式：修改颜色与使用 SVG 渲染模式

作者：流萤

时间：2026-11-03

深入讲解 qrcode.js 如何通过 colorDark 与 colorLight 自定义二维码色彩，以及如何开启 useSVG 切换至矢量 SVG 渲染模式。包含完整代码示例、Canvas 与 SVG 渲染深度对比及常见问题排查。

文章目录

在前端网页中生成二维码时，默认的黑白像素块往往难以满足视觉规范与高分辨率屏幕的需求。使用经典库 qrcode.js 时，通过配置 colorDark 与 colorLight 可以精确指定码点与背景颜色；配置 useSVG: true 则可将底层默认的 HTML5 Canvas 位图渲染切换为纯矢量 SVG 模式。本文通过具体参数演示、渲染管道解析、Canvas 与 SVG 在相同条件下的特性对比及常见问题排查，指导读者完成可自由定制外观的高清矢量二维码开发。

qrcode.js 自定义样式：修改颜色与使用 SVG 渲染模式 — 图 0：qrcode.js 视觉定制核心属性与矢量渲染模式特性概览

一、快速上手：qrcode.js 的基本调用与配置项

在网页端生成二维码时，davidshimjs/qrcodejs 是被广泛应用的经典轻量级脚本。它不依赖大型前端框架，仅需提供一个容纳二维码的 DOM 节点，传入待编码的文本与配置参数即可初始化。

构造函数接收两个参数：第一个是目标 HTML 容器元素（或其 ID 字符串），第二个是可选的配置对象。在没有任何视觉定制的情况下，该库会默认输出标准的黑白位图。

<!-- 1. 引入 qrcode.js 脚本库 -->
<script src="https://cdn.jsdelivr.net/npm/qrcodejs@1.0.0/qrcode.min.js"></script>

<!-- 2. 准备容器 DOM -->
<div id="qrcode-box"></div>

<!-- 3. 执行初始化配置 -->
<script>
  const container = document.getElementById("qrcode-box");
  const qr = new QRCode(container, {
    text: "https://example.com",
    width: 220,
    height: 220,
    colorDark: "#2A4365",    // 自定义前景色（码点及寻象定位角）
    colorLight: "#EDF2F7",   // 自定义背景色（码底与留白静区）
    correctLevel: QRCode.CorrectLevel.H, // 纠错级别（L: 7%, M: 15%, Q: 25%, H: 30%）
    useSVG: true             // 启用 SVG 矢量渲染模式
  });
</script>

为了准确理解底层是如何根据上述选项完成图像生成的，下面的流程图展示了从开发者传入配置对象开始，经过 Reed-Solomon 纠错矩阵运算，直至根据 useSVG 的布尔值分流至不同绘图引擎的完整执行步骤。

二、修改前景色与背景色（colorDark 与 colorLight）

在 qrcode.js 中，颜色配置直接对应二维码的物理结构构成。二维码由三种核心图元构成：寻象图形（三个角落用于定位的“回”字形方块）、对齐与时序同步图案，以及承载编码数据的模块方阵。

1. 参数职能与支持的颜色格式

colorDark（深色前景色）：负责绘制所有功能性定位角、时序连接线和代表二进制数据 1 的矩阵模块。默认值为纯黑色 #000000。
colorLight（浅色背景色）：负责填充二维码的底色、数据间隙以及环绕四周的“静区（Quiet Zone）”。默认值为纯白色 #ffffff。

这两个配置项接受符合标准 CSS 颜色规范的字符串，包括十六进制简写与全写（如 #1B365D、#333）、RGB/RGBA 函数式声明（如 rgba(33, 49, 89, 0.95)）以及标准颜色关键字（如 navy、transparent）。

// 示范：品牌深青色搭配柔和浅暖底色
const qrcode = new QRCode(document.getElementById("brand-qr"), {
  text: "https://example.com/pay",
  width: 180,
  height: 180,
  colorDark: "#1F4E5B",     // 品牌主色：深青石绿
  colorLight: "#F4F6F0",    // 浅暖底色：降低屏幕白光刺眼度
  useSVG: true
});

2. 光学对比度与静区规范

定制颜色时最容易犯的错误是“过度追求视觉柔和而牺牲识别率”。手机摄像头与工业扫描枪依赖明暗亮度的阶跃差（Luminance Contrast）提取黑白二值信号。若前景色过浅或背景色过暗，会导致灰度二值化失败。

此外，二维码四周必须保留至少 4 个模块宽度的“静区”。colorLight 会完整填充静区，若将 colorLight 设为 transparent，则二维码将依赖父级容器的背景；如果父级背景混杂图案或颜色过深，扫描将立即失效。

三、启用 SVG 渲染模式与 Canvas 的关键差异

在 davidshimjs/qrcodejs 中，默认的绘图配置是 useSVG: false。此时库内部会使用 CanvasDrawing 引擎进行像素级绘制。而当显式配置 useSVG: true 时，库将实例化 SVGDrawing 引擎。

1. 关键差异分析：为什么选择 SVG？

为了理清两种模式的适用场景，我们在完全一致的尺寸（如 200×200）、相同编码内容和相同颜色配置的前提下，对比它们在以下四个关键维度上的技术差异：

对比维度	Canvas 模式（默认 useSVG: false）	SVG 渲染模式（useSVG: true）
DOM 节点结构	在容器内同时生成一个 `<canvas>` 元素与一个通过 `toDataURL()` 导出的 `<img>` 标签（用于兼容长按保存）。	在容器内直接生成一个干净的 `<svg>` 根节点，内部全部由基于坐标的 `<rect>` 图元组成。
视网膜屏与缩放表现	属于栅格位图。在 2x/3x Retina 屏或用户缩放网页时，若未手动以 `devicePixelRatio` 放大重绘，边缘极易模糊发虚。	纯数学矢量描述。无论页面缩放到何种比例，在任何高分辨率显示器或 4K 屏幕上始终保持绝对锐利边缘。
CSS 渗透控制能力	黑白像素直接固化在显存画布中，外部 CSS 样式表无法选中和篡改内部单个方块的颜色或圆角。	作为标准 DOM 节点存在。可以通过 CSS 选择器如 `svg rect` 动态覆盖填充色、添加渐变滤镜或圆角过渡。
导出与跨端印刷	直接导出为 PNG/JPG 位图，若用于易拉宝、海报或宣传折页等高精度喷绘，分辨率不足会导致严重马赛克。	本身就是合法的独立矢量文件，可直接提取 XML 源码并作为 `.svg` 导入 Illustrator 等专业排版工具无损出图。

以下架构对比图清晰展现了在相同容器下，Canvas 模式产生的“双层位图混合”机制与 SVG 模式“纯矢量 DOM 树”的根本机制差异。

四、进阶技巧：动态更新、CSS 样式控制与导出矢量文件

1. 动态更新二维码内容与清空操作

当页面中的 URL 或文本发生变化时，无需销毁重建 DOM 实例，可以直接调用实例提供的 makeCode() 方法。但在调用前，为了防止部分历史版本库在 SVG 模式下叠加追加图元，推荐养成先执行 clear() 再执行 makeCode() 的习惯：

// 实例化 SVG 模式二维码
const qrInstance = new QRCode(document.getElementById("dynamic-qr"), {
  text: "https://example.com/item/1001",
  width: 200,
  height: 200,
  colorDark: "#2C3E50",
  colorLight: "#FFFFFF",
  useSVG: true
});

// 当用户在输入框键入新链接时触发更新
function updateQrText(newUrl) {
  qrInstance.clear();       // 清理旧图形
  qrInstance.makeCode(newUrl); // 计算新矩阵并重新生成矢量节点
}

2. 利用外部 CSS 实现响应式与柔和圆角

由于 useSVG: true 模式下输出的是纯正的 SVG DOM 树，我们可以利用 CSS 轻易实现响应式自适应布局。通过将宿主容器宽度设置为百分比，并强制内部 SVG 自适应，即可在不同屏幕尺寸下保持比例自适应：

/* 容器响应式适配样式 */
#dynamic-qr {
  width: 100%;
  max-width: 240px;
  margin: 0 auto;
}

/* 穿透控制内联 SVG 自适应大小 */
#dynamic-qr svg {
  width: 100% !important;
  height: auto !important;
  display: block;
}

/* 给 SVG 内的方块图元赋予柔和圆角（适用于现代浏览器） */
#dynamic-qr svg rect {
  rx: 1.5px;
  ry: 1.5px;
}

3. 一键导出保存为独立 .svg 矢量文件

在很多业务场景中（例如宣传物料生成后台、名片定制工具），用户需要下载二维码的矢量文件以便放入印刷流程。在 SVG 模式下，直接抓取容器内的 innerHTML 并转换为 Blob 即可实现下载：

function exportSvgFile(containerId, filename = "qrcode.svg") {
  const container = document.getElementById(containerId);
  const svgElement = container.querySelector("svg");
  if (!svgElement) return;

  // 序列化 SVG DOM 节点并封装为文件流
  const serializer = new XMLSerializer();
  const svgString = serializer.serializeToString(svgElement);
  const blob = new Blob([svgString], { type: "image/svg+xml;charset=utf-8" });

  const downloadLink = document.createElement("a");
  downloadLink.href = URL.createObjectURL(blob);
  downloadLink.download = filename;
  document.body.appendChild(downloadLink);
  downloadLink.click();
  document.body.removeChild(downloadLink);
  URL.revokeObjectURL(downloadLink.href);
}

五、常见问题与排查要点

关键避坑注意事项

1. 宿主 DOM 节点必须已挂载：如果在 DOMContentLoaded 之前或在尚未插入页面的虚拟 DOM 上调用 new QRCode(element)，会导致库无法准确获取容器计算尺寸，从而抛出空引用或导致图形被压成 0 像素。
2. 避免过高的纠错级别占用过多信息量：correctLevel 设为 H (30%) 虽可容纳一定损耗，但会显著增加二维码的点阵密度（Version 级别上升），使得每个方块面积更小。在常规纯展示场景下，选择 M (15%) 或 Q (25%) 能获得更疏朗、更好辨认的方块布局。
3. 移动端长按保存兼容性：部分移动端微信内置浏览器支持长按 <img> 弹出“识别图中的二维码”，但对内联 <svg> 的长按菜单支持度有限。若业务强依赖移动端长按识别，需权衡使用 Canvas 模式导出的 <img> 或动态将 SVG 转为图片遮罩。