React Barcode Scanner API 参考 – React Barcode Scanner

BarcodeScannerProvider

BarcodeScannerProvider 用于创建相互隔离的媒体流和闪光灯作用域。Provider 是可选的；Provider 外部的 hooks 会继续使用全局兼容作用域。

名称	类型	默认值	说明
`initialTorchOn`	`boolean`	`false`	Provider store 创建时读取一次的闪光灯初始状态。
`children`	`ReactNode`	必填	属于该作用域的扫码器和状态消费者。


<BarcodeScannerProvider initialTorchOn={false}>
  <BarcodeScanner />
  <ScannerControls />
</BarcodeScannerProvider>

useStreamState() 和 useTorch() 会解析距离最近的 Provider。不同 Provider 互相隔离；没有 Provider 时则解析模块级全局兼容 store。

基础作用域规则见快速入门。

BarcodeScanner

除了下列属性，BarcodeScanner 也支持 React 标准的 video 元素属性：

名称	类型	默认值	说明
`options`	`ScanOptions`	`DEFAULT_OPTIONS`	扫描间隔和条码格式。
`onCapture`	`(barcodes: DetectedBarcode[]) => void`	—	检测到一个或多个条码后调用。
`onCameraError`	`(error: Error) => void`	—	相机初始化失败时调用。
`onScanError`	`(error: Error) => void`	—	条码检测失败时调用。
`trackConstraints`	`MediaTrackConstraints`	`DEFAULT_CONSTRAINTS`	额外的视频轨道约束。
`paused`	`boolean`	`false`	在不卸载组件的情况下暂停视频和扫描。

useCamera


function useCamera(
  ref: RefObject<HTMLVideoElement | null>,
  trackConstraints?: MediaTrackConstraints
): {
  isCameraReady: boolean
  error: Error | undefined
}

创建相机媒体流、绑定到 video 元素，并暴露初始化错误。

DEFAULT_CONSTRAINTS


{
  width: { min: 640, ideal: 1280 },
  height: { min: 480, ideal: 720 },
  facingMode: { ideal: 'environment' },
  advanced: [
    { width: 1920, height: 1280 },
    { aspectRatio: 1.333 }
  ]
}

useScanning


function useScanning(
  ref: RefObject<HTMLVideoElement | null>,
  options?: ScanOptions
): {
  detectedBarcodes: DetectedBarcode[] | undefined
  error: Error | undefined
  startScan: () => void
  stopScan: () => void
}

如果导入了随包提供的 react-barcode-scanner/polyfill，创建检测器前会等待其加载完成。其他兼容 Barcode Detection API 的实现通过 globalThis.BarcodeDetector 使用。只要 formats 不变，就会复用同一个检测器。

DEFAULT_OPTIONS


{
  delay: 1000,
  formats: ['qr_code']
}

useTorch


function useTorch(defaultTorchOn?: boolean): {
  isTorchSupported: boolean
  error: Error | undefined
  isTorchOn: boolean
  setIsTorchOn: (torch: boolean) => void
}

闪光灯是否可用取决于当前相机轨道以及浏览器、设备能力。

useStreamState


function useStreamState(): [
  MediaStream | undefined,
  (newState: MediaStream | undefined) => void
]

用于在 BarcodeScanner 外部的组件中读取或更新 useCamera 创建的媒体流。

没有 BarcodeScannerProvider 时，useStreamState 和 useTorch 使用模块级共享状态。如果页面同时运行多个扫码器，应分别用 Provider 包裹每个扫码器及其消费者。

Types

ScanOptions


interface ScanOptions {
  delay?: number
  formats?: Array<BarcodeFormat | string>
}

DetectedBarcode


interface DetectedBarcode {
  boundingBox: DOMRectReadOnly
  cornerPoints: Point[]
  format: string
  rawValue: string
}