React项目qr-code-styling多SVG二维码ID重复问题解决方案

qr-code-styling 生成SVG格式二维码时，内部渐变、裁剪路径、图案填充等元素默认使用固定ID值，同页面渲染多个二维码实例时就会出现ID重复。浏览器解析DOM时同ID只会匹配第一个命中的元素，后续所有SVG对同ID的样式引用都会指向第一个SVG内的定义，最终出现修改单个二维码样式、全页面二维码同步变更的异常。

方案1：使用官方配置设置唯一ID前缀（推荐） #

qr-code-styling 1.5.0及以上版本支持idPrefix配置项，初始化实例时传入全局唯一的前缀，库会自动给当前实例所有内部元素ID拼接该前缀，从根源避免ID重复。
React场景下可以直接用内置的useIdHook生成唯一值，无需额外引入第三方依赖：

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

const QrCodeItem = ({ value, qrConfig }) => {
  const uniquePrefix = useId();
  const containerRef = useRef(null);
  const qrInstance = useRef(null);

  useEffect(() => {
    qrInstance.current = new QRCodeStyling({
      width: 220,
      height: 220,
      type: 'svg',
      data: value,
      // 核心配置：为当前实例设置唯一ID前缀
      idPrefix: uniquePrefix,
      ...qrConfig
    });
    qrInstance.current.append(containerRef.current);

    return () => {
      containerRef.current.innerHTML = '';
    };
  }, [value, qrConfig, uniquePrefix]);

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

// 页面多实例渲染无冲突
export default function QrListPage() {
  return (
    <div className="qr-group">
      <QrCodeItem value="https://demo.com/page1" qrConfig={{ dotsColor: '#1677ff' }} />
      <QrCodeItem value="https://demo.com/page2" qrConfig={{ dotsColor: '#ff4d4f' }} />
      <QrCodeItem value="https://demo.com/page3" qrConfig={{ dotsColor: '#52c41a' }} />
    </div>
  );
}

注意：如果项目使用的qr-code-styling版本低于1.5.0，没有idPrefix配置项，请使用下方方案2兼容

方案2：挂载后手动替换SVG内部ID #

如果暂时无法升级库版本，可以在二维码SVG挂载到DOM后，遍历当前SVG下的所有带ID元素，替换为带唯一后缀的ID，同时同步替换SVG内部所有对这些ID的引用，实现ID隔离：

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

// 工具函数：替换单个SVG内的重复ID
const replaceDuplicateSvgIds = (svgElement, uniqueSuffix) => {
  if (!svgElement) return;
  const idMapping = new Map();
  // 收集所有原有ID并生成新ID
  svgElement.querySelectorAll('[id]').forEach(el => {
    const originId = el.id;
    const newId = `${originId}-${uniqueSuffix}`;
    el.id = newId;
    idMapping.set(originId, newId);
  });
  // 替换所有url(#xxx)格式的ID引用
  svgElement.querySelectorAll('*').forEach(el => {
    Array.from(el.attributes).forEach(attr => {
      if (!attr.value.includes('url(#')) return;
      idMapping.forEach((newId, originId) => {
        attr.value = attr.value.replace(`url(#${originId})`, `url(#${newId})`);
      });
    });
  });
};

const QrCodeItem = ({ value, qrConfig }) => {
  const containerRef = useRef(null);
  // 生成当前实例唯一后缀
  const uniqueSuffix = useRef(`qr_${Date.now()}_${Math.random().toString(36).slice(2)}`).current;

  useEffect(() => {
    const qrInstance = new QRCodeStyling({
      width: 220,
      height: 220,
      type: 'svg',
      data: value,
      ...qrConfig
    });
    qrInstance.append(containerRef.current);
    // 挂载完成后执行ID替换
    const svgEl = containerRef.current.querySelector('svg');
    replaceDuplicateSvgIds(svgEl, uniqueSuffix);

    return () => {
      containerRef.current.innerHTML = '';
    };
  }, [value, qrConfig, uniqueSuffix]);

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

• 优先选择官方idPrefix方案，相比手动DOM替换性能更好，无后续兼容风险
• 生成唯一标识时不要用列表索引作为后缀，动态增删二维码列表时索引值会变化，可能引发ID重复
• 修改单个二维码样式时，调用对应二维码实例的update方法传入新配置，不要直接通过全局DOM操作修改样式，避免跨实例污染

内容的提问来源于stack exchange，提问作者Devlydexter