qrcode-alipay

支付宝品牌二维码生成器。默认输出符合支付场景视觉的 SVG 二维码：三个定位点使用支付宝蓝，中间带支付宝「支」logo，核心 API 不依赖 React、Vue 或浏览器 DOM。

安装

pnpm add qrcode-alipay

也可以使用 npm 或 yarn：

npm install qrcode-alipay
yarn add qrcode-alipay

推荐用法

如果项目使用 React 或 Vue，优先使用组件，不需要处理 SVG 字符串或 descriptor。

import { AlipayQRCode } from 'qrcode-alipay/react';

export function PaymentQRCode({ value }: { value: string }) {
  return (
    <AlipayQRCode
      value={value}
      size={240}
      ariaLabel="支付宝支付二维码"
      className="payment-qr"
    />
  );
}

<script setup lang="ts">
import { AlipayQRCode } from 'qrcode-alipay/vue';
</script>

<template>
  <AlipayQRCode
    value="https://qr.alipay.com/example"
    :size="240"
    aria-label="支付宝支付二维码"
    class-name="payment-qr"
  />
</template>

value 必须是二维码真实内容。请传纯 URL 字符串，例如 https://qr.alipay.com/example；不要传 Markdown 链接文本，例如 [https://qr.alipay.com/example](https://qr.alipay.com/example)。

不同 API 怎么选

| 场景 | 推荐 API | 返回值怎么用 | | --- | --- | --- | | React 项目 | qrcode-alipay/react 的 <AlipayQRCode /> | 直接作为 React 组件渲染。 | | Vue 3 项目 | qrcode-alipay/vue 的 <AlipayQRCode /> | 直接作为 Vue 组件渲染。 | | 普通 HTML 或只想放进 <img> | toDataURL(value, options) | 返回 data:image/svg+xml 地址，赋给 <img src>。 | | 服务端模板、保存文件、自己插入 HTML | toSvg(value, options) | 返回完整 SVG 字符串。 | | 写框架适配层或自定义渲染器 | createAlipayQRCode(value, options) | 返回结构化 SVG descriptor，需要调用方自行渲染。 |

toDataURL：用于 <img src>

import { toDataURL } from 'qrcode-alipay';

const src = toDataURL('https://qr.alipay.com/example', {
  size: 240,
});

<img src="data:image/svg+xml;charset=UTF-8,..." alt="支付宝支付二维码" />

toSvg：返回 SVG 字符串

toSvg 返回的是一段完整 SVG markup 字符串，适合服务端模板、下载保存，或在确认内容可信后插入 HTML。

import { toSvg } from 'qrcode-alipay';

const svg = toSvg('https://qr.alipay.com/example', {
  size: 240,
  title: '支付宝支付二维码',
});

// svg 类似：
// <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ..." ...>...</svg>

在浏览器中可以这样使用：

document.querySelector('#qr')!.innerHTML = svg;

React 项目里通常不建议优先用 toSvg，因为插入字符串需要 dangerouslySetInnerHTML。如果确实需要：

<div dangerouslySetInnerHTML={{ __html: svg }} />

createAlipayQRCode：返回 descriptor

createAlipayQRCode 返回的不是 DOM 节点，也不是字符串，而是一棵描述 SVG 的普通对象。它用于高级场景，例如你要自己写 React/Vue 之外的框架适配层。

import { createAlipayQRCode } from 'qrcode-alipay';

const descriptor = createAlipayQRCode('https://qr.alipay.com/example', {
  size: 240,
});

console.log(descriptor.tag); // 'svg'
console.log(descriptor.attrs.viewBox); // '0 0 ... ...'
console.log(descriptor.children); // rect/path/title/logo 等子节点描述
console.log(descriptor.metadata.moduleCount); // 二维码模块数量

descriptor 大致结构如下：

type SvgNodeDescriptor =
  | string
  | {
      tag: string;
      attrs?: Record<string, string | number | boolean | null | undefined>;
      children?: SvgNodeDescriptor[];
    };

如果只是业务页面展示二维码，请用 React/Vue 组件或 toDataURL，不用直接消费 descriptor。

配置项

公开配置只覆盖通用渲染能力：

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | size | number \| string | 240 | SVG 的宽高。不传时是固定 240，不会自动变成 100%。 | | margin | number | 0 | 二维码 quiet zone，单位为二维码模块。 | | title | string | - | 写入 SVG 内部的 <title>，用于辅助技术识别；不会作为可见文字显示。 | | ariaLabel | string | Alipay QR code | SVG 根节点的可访问性描述。不传时优先使用 title，否则使用默认值。 | | className | string | - | SVG 根节点 class。 |

品牌色、中心 logo 和纠错等级默认固定，避免不同业务接入后出现不一致的支付宝支付二维码。

扫码安全建议：如果二维码外层没有白色 padding 或白色卡片容器，建议传 margin: 1 或更高；如果外层已经有足够白色留白，保持默认 margin: 0 更符合组件布局习惯。

响应式建议：size 不传默认是 240。如需自适应父容器，请显式传 size: '100%'，并确保父容器有稳定的宽高或 aspect-ratio: 1。

title 不是二维码上方的展示标题。如果业务页面需要展示“支付宝扫码支付”这类可见文案，请在 SVG 外部自行渲染；title 只负责 SVG 语义和无障碍场景。

Webpack 兼容性

[email protected] 起，发布产物会降级到更兼容的 JS 语法，避免旧 webpack 因无法解析 ?? 或 ?. 在 node_modules 中报 Module parse failed: Unexpected token。

如果你仍然遇到类似错误：

• 先升级到 [email protected] 或更高版本。
• 确认项目实际安装的版本：npm ls qrcode-alipay。
• 清理构建缓存后重新启动 dev server。

文档

公开使用说明见 publicDocs/usage.md。

本地开发

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm demo

docs/ 是内部设计与实现文档，不会随 npm 包发布。