React Barcode Scanner 快速入门 – React Barcode Scanner

快速开始

import React from 'react'
import { BarcodeScanner } from 'react-barcode-scanner'
import 'react-barcode-scanner/polyfill'
 
export default () => {
  return (
    <BarcodeScanner />
  )
}

条形码格式

BarcodeScanner 默认支持 qr_code。如果需要扫描其他条码格式，请配置 formats：

<BarcodeScanner options={{ formats: ['code_128'] }} />

⚠️

扫码器基于 Barcode Detection API。zbar polyfill 支持条码格式列表 (opens in a new tab)中除 aztec、data_matrix 和 pdf417 之外的格式。

扫码感应延迟

出于性能考虑，BarcodeScanner 默认每 1000ms 扫描一次。可以通过 delay 调整扫描间隔：

<BarcodeScanner options={{ delay: 500 }} />

闪光灯

可以使用 useTorch Hook 检查设备支持情况并控制闪光灯：

import React from 'react'
import { BarcodeScanner, useTorch } from 'react-barcode-scanner'
 
export default () => {
  const { isTorchSupported, isTorchOn, setIsTorchOn } = useTorch()
 
  const onTorchSwitch = () => {
    setIsTorchOn(!isTorchOn)
  }
 
  return (
    <div style={{ width: '100%', height: '360px' }}>
      <BarcodeScanner />
      {isTorchSupported
        ? <button onClick={onTorchSwitch}>切换闪光灯</button>
        : null}
    </div>
  )
}

闪光灯支持情况取决于浏览器和设备，具体参考 MediaTrackConstraints (opens in a new tab)。

状态作用域与多实例

完整的状态归属、生命周期、闪光灯异步行为和 SSR 规则见状态作用域与多实例。

没有 Provider 时，BarcodeScanner、useStreamState() 和 useTorch() 会使用全局兼容作用域，原有的单扫码器用法无需修改。

页面同时运行多个扫码器时，应分别使用 BarcodeScannerProvider 包裹每个扫码器及其控制组件：

import {
  BarcodeScanner,
  BarcodeScannerProvider,
  useStreamState,
  useTorch
} from 'react-barcode-scanner'
 
function ScannerControls () {
  const [stream] = useStreamState()
  const { isTorchOn, setIsTorchOn } = useTorch()
 
  return (
    <section>
      <p>媒体流：{stream?.id ?? '无'}</p>
      <button onClick={() => setIsTorchOn(!isTorchOn)}>
        闪光灯：{isTorchOn ? '开启' : '关闭'}
      </button>
    </section>
  )
}
 
export default function Scanners () {
  return (
    <>
      <BarcodeScannerProvider>
        <BarcodeScanner />
        <ScannerControls />
      </BarcodeScannerProvider>
 
      <BarcodeScannerProvider initialTorchOn>
        <BarcodeScanner />
        <ScannerControls />
      </BarcodeScannerProvider>
    </>
  )
}

initialTorchOn 只在对应 Provider store 创建时读取一次，之后修改该属性不会覆盖用户已经操作过的状态。

与框架使用

Next.js

包本身可以在 SSR 阶段导入，但扫码器会在挂载后使用浏览器 API。Provider、扫码器和外部状态组件应位于同一个客户端组件中：

ScannerPanel.tsx

'use client'
 
import {
  BarcodeScanner,
  BarcodeScannerProvider
} from 'react-barcode-scanner'
import 'react-barcode-scanner/polyfill'
 
export default function ScannerPanel () {
  return (
    <BarcodeScannerProvider>
      <BarcodeScanner />
      <ScannerControls />
    </BarcodeScannerProvider>
  )
}

Pages Router 中，如果希望整个扫码区域不参与 SSR，应动态加载完整面板：

import dynamic from 'next/dynamic'
 
const ScannerPanel = dynamic(
  () => import('../components/ScannerPanel'),
  { ssr: false }
)

App Router 中，声明 dynamic(..., { ssr: false }) 的包装组件本身必须是客户端组件：

'use client'
 
import dynamic from 'next/dynamic'
 
const ScannerPanel = dynamic(
  () => import('./ScannerPanel'),
  { ssr: false }
)
 
export default function ScannerPageClient () {
  return <ScannerPanel />
}

安装状态作用域