二維碼（QR Code）

根據文字或 URL 產生二維碼，並作為行內圖片嵌入文件。

匯入

import { qrcodePlugin, type QRCodePluginOptions } from 'docx-kit'

相依

需要 qrcode 包作為同儕相依套件：

pnpm add qrcode

選項

選項	型別	預設值	說明
text	string	必填	要編碼的文字或 URL
size	number	128	二維碼圖片尺寸，單位為像素
errorCorrectionLevel	'L' | 'M' | 'Q' | 'H'	'M'	糾錯級別
margin	number	1	靜區邊距，單位為模組
caption	string	—	二維碼下方的可選題注

糾錯級別

級別	恢復能力	使用場景
L	約 7%	高密度資料、乾淨環境
M	約 15%	通用場景（預設）
Q	約 25%	需要可靠掃描
H	約 30%	疊加標誌或可能破損的環境

範例

基本二維碼

import { createDocx, qrcodePlugin } from 'docx-kit/node'

const doc = createDocx()
  .use(qrcodePlugin())
  .h1('Website QR')
  .plugin('qrcode', {
    text: 'https://example.com',
  })
  .save('basic-qr.docx')

名片二維碼

const doc = createDocx()
  .use(qrcodePlugin())
  .h1('Business Card')
  .plugin('qrcode', {
    text: 'https://ntnyq.com',
    size: 256,
    errorCorrectionLevel: 'H',
    margin: 2,
    caption: 'Scan to visit my website',
  })
  .save('business-card.docx')

付款二維碼

const doc = createDocx()
  .use(qrcodePlugin())
  .h1('Invoice #2026-001')
  .p('Please scan the QR code below to complete payment:')
  .plugin('qrcode', {
    text: 'https://pay.example.com/invoice/2026-001',
    size: 200,
    errorCorrectionLevel: 'M',
    caption: 'Pay with WeChat / Alipay',
  })
  .save('payment-qr.docx')

Wi-Fi 二維碼

const doc = createDocx()
  .use(qrcodePlugin())
  .h1('Office Wi-Fi')
  .p('Scan the QR code to connect to the office network:')
  .plugin('qrcode', {
    // Wi-Fi QR code format
    text: 'WIFI:T:WPA;S:Office-Network;P:password123;;',
    size: 180,
    caption: 'Office Wi-Fi',
  })
  .save('wifi-qr.docx')

無題注的小二維碼

const doc = createDocx()
  .use(qrcodePlugin())
  .h1('Document Reference')
  .plugin('qrcode', {
    text: 'REF-2026-06-11-001',
    size: 80,
    margin: 0,
  })
  .save('small-qr.docx')

多個二維碼

const doc = createDocx()
  .use(qrcodePlugin())
  .h1('Multi-Channel Contact')

  .h2('Website')
  .plugin('qrcode', {
    text: 'https://example.com',
    caption: 'Visit our website',
  })

  .h2('WeChat')
  .plugin('qrcode', {
    text: 'https://weixin.qq.com/q/xxxxx',
    caption: 'Follow us on WeChat',
  })

  .h2('Email')
  .plugin('qrcode', {
    text: 'mailto:contact@example.com',
    caption: 'Send us an email',
  })

  .save('multi-qr.docx')

樣式自訂

工廠的 { styles } 設定實例預設值，options.styles 覆寫單次呼叫。外掛套件與 docx-kit 入口匯出 QRCodeConfig 和 QRCodeStyles。優先順序：內建/主題預設值 → 初始化 styles → 通用 style → 單次部位 styles。巢狀欄位合併，陣列整體替換，undefined 沿用預設，0 / false 生效；支援單位與 $colors.primary 等主題 token。

部位	樣式型別	範圍
caption	TextStyleRule	文字排版
captionParagraph, imageParagraph	ParagraphStyleRule	段落背景、框線、對齊、間距及分頁

這些樣式控制 DOCX 段落與圖說；QR Code 像素及尺寸繼續使用原有選項。

qrcodePlugin({
  styles: { caption: { color: '#2563EB', fontSize: 14 } },
})

單次呼叫在 options.styles 中使用相同部位名稱。JSON DSL、AI 工具 schema 與 MCP 驗證共用這些契約；未知部位與放錯部位的屬性會被拒絕。