Qrcode 扫码能力

@rydeen/qrcode 基于 @capacitor-rydeen/barcode-scanning 封装了 扫码 UI、权限处理与结果回调，用于实现二维码/条码扫描能力，可广泛应用于登录、支付码识别、订单查询等场景。

设计定位

• 一站式扫码流程：从权限检查到 UI 展示、扫码结果返回，全链路封装。
• 可配置 UI：支持自定义提示文案、扫光条颜色、提示音、主容器 ID 等。
• 与 App 生命周期集成：Android 返回键、取消回调、权限拒绝回调统一管理。

安装与依赖

npm install @rydeen/qrcode

Peer 依赖（需在业务项目中安装并 npx cap sync）：

• @capacitor-rydeen/barcode-scanning
• @capacitor/app

快速开始

import { QrcodeManage } from '@rydeen/qrcode'

const qrcode = new QrcodeManage({
  mainContainerId: 'app',
  promptText: '将二维码放入框内，即可自动识别',
  color: 'white',
  deniedCallback: async () => {
    const { BarcodeScanner } = await import('@capacitor-rydeen/barcode-scanning')
    await BarcodeScanner.openSettings()
  },
})

export async function scanOnce() {
  try {
    const barcode = await qrcode.startScan()
    const content = barcode.displayValue ?? barcode.rawValue
    console.log('扫码结果:', content)
    return content
  } catch (e) {
    console.log('扫码取消或失败', e)
    return null
  }
}

实战示例：收银扫码支付

场景：收银界面点击「扫码支付」按钮后，弹出扫码 UI，扫描顾客付款码并回填到收银表单。

import { QrcodeManage } from '@rydeen/qrcode'

const payCodeScanner = new QrcodeManage({
  mainContainerId: 'app',
  promptText: '请将顾客付款码对准摄像头',
  color: '#00ff00',
})

export async function scanPayCodeAndSubmit() {
  const result = await payCodeScanner.startScan()
  const payCode = result.displayValue ?? result.rawValue

  // 将支付码写入表单或直接发起支付请求
  // await submitPayment(payCode)
}

API 与类型参考

QrcodeOptions

• mainContainerId?：应用主容器元素 ID（如 Vue 的 #app），扫码时会调整该容器与扫码层的展示关系。
• promptText?：扫描界面提示文案。
• promptSound?：扫描成功后的提示音 URL。
• color?：扫光条颜色。
• cancelListener?：取消扫描时的回调（无参）。
• deniedCallback?：相机权限被拒绝时的回调，返回 Promise；可在内部调用 BarcodeScanner.openSettings()。
• startScanOption?：传给 BarcodeScanner.startScan() 的选项，类型为 StartScanOptions。

主要方法

方法	签名	说明
构造函数	new QrcodeManage(options?: QrcodeOptions)	创建扫码管理器并挂载自定义元素 capacitor-scanner。
startScan	startScan(): Promise<Barcode>	启动扫码流程：权限检查 → UI 展示 → 监听 barcodesScanned，返回首个条码。
stopScan	stopScan(): Promise<void>	停止扫描并隐藏 UI，触发 cancelListener。
checkPermission	checkPermission(): Promise<boolean>	检查相机权限是否已授权。
showScanUI	showScanUI(): Promise<void>	显示扫码 UI（不一定开始扫描）。
hideScanUI	hideScanUI(): Promise<void>	隐藏扫码 UI。

其中 Barcode、StartScanOptions 等类型来自 @capacitor-rydeen/barcode-scanning，包含条码值、类型、坐标等信息。

平台支持与注意事项

平台	说明
Android	通常完整支持，相机权限与返回键行为由插件处理。
iOS	取决于 @capacitor-rydeen/barcode-scanning 的实现与相机权限策略。
Web / Electron	视 barcode-scanning 插件与浏览器/宿主环境的相机支持情况而定。

• 避免重复实例：同一页面尽量使用一个 QrcodeManage 实例，避免重复挂载 DOM。
• 权限体验：首次调用会弹出相机权限，建议在权限被拒绝时给出清晰提示与「去设置」指引。
• 返回键行为：Android 上会监听 App.addListener('backButton')，按返回键会调用 stopScan() 并触发 cancelListener。