QR Code Styling 库在 Next.js 中的多实例问题解析

在 Next.js 项目中使用 QR Code Styling 库时，开发者可能会遇到一个常见问题：当页面中存在多个 QR 码组件时，所有实例都显示相同的内容，而不是各自独立的内容。这种现象通常发生在使用 SVG 渲染模式时。

问题根源分析

该问题的本质在于 QR Code Styling 库的实例管理方式。当开发者创建一个全局的 QR 码实例并在多个组件中复用时，由于 SVG 渲染的特殊性，所有实例实际上共享了同一个 DOM 元素引用。这导致最后渲染的 QR 码内容会覆盖之前的所有实例。

解决方案

经过社区验证，有以下两种有效的解决方案：

1. 使用 Canvas 渲染模式替代 SVG

   • 将 QR 码的渲染类型从 SVG 改为 Canvas
   • Canvas 渲染天然支持多实例隔离
   • 性能上 Canvas 在大尺寸渲染时可能更有优势

2. 为每个 QR 码创建独立实例

   • 将 QR 码实例的创建移至组件内部
   • 确保每个组件拥有自己独立的 QR 码实例
   • 这种方式适用于需要保持 SVG 渲染的场景

最佳实践代码示例

import { useEffect, useRef } from "react";
import QRCodeStyling from "qr-code-styling";

const QRCode = ({ value }) => {
  const qrCode = new QRCodeStyling({
    width: 500,
    height: 500,
    type: "canvas", // 关键修改点
    backgroundOptions: {
      color: "transparent",
    },
    dotsOptions: {
      color: "#4267b2",
      type: "rounded",
    },
    data: value,
  });

  const ref = useRef(null);

  useEffect(() => {
    if (ref.current) {
      qrCode.update({ data: value });
      qrCode.append(ref.current);
    }
  }, [value]);

  return <div ref={ref} />;
};

版本兼容性说明

该问题在 QR Code Styling 库的 1.7.1 及以上版本中已得到官方修复。建议开发者：

1. 检查当前使用的库版本
2. 及时升级到最新稳定版
3. 如果因项目限制无法升级，可采用上述解决方案

总结

处理 QR 码多实例问题时，开发者应理解不同渲染模式的特点。Canvas 方案提供更好的隔离性，而 SVG 方案在特定场景下可能有矢量缩放优势。根据项目实际需求选择合适的解决方案，同时保持依赖库的版本更新，可以避免这类问题的发生。