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 />
  )
}

上面的示例使用随包提供的 ZBar WASM polyfill。需要切换到兼容的 ZXing WASM 实现时，请查看安装说明。

条形码格式

BarcodeScanner 默认扫描 qr_code。formats 使用 Barcode Detection API 定义的官方支持格式：


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

⚠️

实际可用格式取决于当前浏览器或 polyfill 的 BarcodeDetector 实现。可通过 BarcodeDetector.getSupportedFormats() 查询；ZBar 与 ZXing 的差异请查看安装选项。

扫码感应延迟

出于性能考虑，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 。

Hooks 的状态作用域

BarcodeScannerProvider 用来确定 useStreamState()、useTorch() 等扫码 Hooks 读取哪一个扫码器的状态。它主要提供给调用这些 Hooks 的组件使用；BarcodeScanner 内部也通过 Hooks 加入同一个作用域。

只有一个扫码器时，可以不使用 Provider，扫码器和 Hooks 会共享默认的全局作用域。
其他组件需要调用扫码 Hooks 时，应把它和扫码器放在同一个 Provider 中。
同时运行多个扫码器时，每个扫码器使用一个 Provider，媒体流和闪光灯状态就不会串在一起。

调用 Hooks 的组件必须位于 Provider 内部：


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

需要多个扫码器时，为每个 ScannerPanel 分别重复一组 Provider 即可。

与框架使用

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 />
}