@hxa-rn/vision-camera-code-scanner 0.2.0

package/src/index.ts

@@ -0,0 +1,504 @@
+import type { Code, CodeType, Frame } from 'react-native-vision-camera';
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.BarcodeFormat
+ */
+export enum BarcodeFormat {
+  UNKNOWN = -1,
+  ALL_FORMATS = 0,
+  CODE_128 = 1,
+  CODE_39 = 2,
+  CODE_93 = 4,
+  CODABAR = 8,
+  DATA_MATRIX = 16,
+  EAN_13 = 32,
+  EAN_8 = 64,
+  ITF = 128,
+  QR_CODE = 256,
+  UPC_A = 512,
+  UPC_E = 1024,
+  PDF417 = 2048,
+  AZTEC = 4096,
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.BarcodeValueType
+ */
+export enum BarcodeValueType {
+  UNKNOWN = 0,
+  CONTACT_INFO = 1,
+  EMAIL = 2,
+  ISBN = 3,
+  PHONE = 4,
+  PRODUCT = 5,
+  SMS = 6,
+  TEXT = 7,
+  URL = 8,
+  WIFI = 9,
+  GEO = 10,
+  CALENDAR_EVENT = 11,
+  DRIVER_LICENSE = 12,
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.Address.AddressType
+ */
+export enum AddressType {
+  UNKNOWN = 0,
+  WORK = 1,
+  HOME = 2,
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.Address
+ */
+export interface Address {
+  addressLines?: string[];
+  type?: AddressType;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.PersonName
+ */
+export interface PersonName {
+  first?: string;
+  formattedName?: string;
+  last?: string;
+  middle?: string;
+  prefix?: string;
+  pronunciation?: string;
+  suffix?: string;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.ContactInfo
+ */
+export interface ContactInfo {
+  addresses?: Address[];
+  emails?: Email[];
+  name?: PersonName;
+  organization?: string;
+  phones?: Phone[];
+  title?: string;
+  urls?: string[];
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.Email.FormatType
+ */
+export enum EmailType {
+  UNKNOWN = 0,
+  WORK = 1,
+  HOME = 2,
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.Email
+ */
+export interface Email {
+  address?: string;
+  body?: string;
+  subject?: string;
+  type?: EmailType;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.Phone.FormatType
+ */
+export enum PhoneType {
+  UNKNOWN = 0,
+  WORK = 1,
+  HOME = 2,
+  FAX = 3,
+  MOBILE = 4,
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.Phone
+ */
+export interface Phone {
+  number?: string;
+  type?: PhoneType;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.Sms
+ */
+export interface Sms {
+  message?: string;
+  phoneNumber?: string;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.UrlBookmark
+ */
+export interface UrlBookmark {
+  title?: string;
+  url?: string;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.WiFi.EncryptionType
+ */
+export enum EncryptionType {
+  OPEN = 1,
+  WPA = 2,
+  WEP = 3,
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.WiFi
+ */
+export interface Wifi {
+  encryptionType?: EncryptionType;
+  password?: string;
+  ssid?: string;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.GeoPoint
+ */
+export interface GeoPoint {
+  lat?: number;
+  lng?: number;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.CalendarDateTime
+ */
+export interface Date {
+  day: number;
+  hours: number;
+  minutes: number;
+  month: number;
+  rawValue: string;
+  seconds: number;
+  year: number;
+  isUtc: boolean;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.CalendarEvent
+ */
+export interface CalendarEvent {
+  description?: string;
+  end?: Date;
+  location?: string;
+  organizer?: string;
+  start?: Date;
+  status?: string;
+  summary?: string;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode.DriverLicense
+ */
+export interface DriverLicense {
+  addressCity?: string;
+  addressState?: string;
+  addressStreet?: string;
+  addressZip?: string;
+  birthDate?: string;
+  documentType?: string;
+  expiryDate?: string;
+  firstName?: string;
+  gender?: string;
+  issueDate?: string;
+  issuingCountry?: string;
+  lastName?: string;
+  licenseNumber?: string;
+  middleName?: string;
+}
+
+/**
+ * @see https://developer.android.com/reference/android/graphics/Rect.html
+ */
+export interface Rect {
+  bottom: number;
+  left: number;
+  right: number;
+  top: number;
+}
+
+/**
+ * @see https://developer.android.com/reference/android/graphics/Point.html
+ */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * @see https://developers.google.com/android/reference/com/google/mlkit/vision/barcode/Barcode
+ */
+export type Barcode = {
+  boundingBox?: Rect;
+  cornerPoints?: Point[];
+  displayValue?: string;
+  rawValue?: string;
+  format: BarcodeFormat;
+  content:
+    | {
+        type:
+          | BarcodeValueType.UNKNOWN
+          | BarcodeValueType.ISBN
+          | BarcodeValueType.TEXT;
+        data: string;
+      }
+    | {
+        type: BarcodeValueType.CONTACT_INFO;
+        data: ContactInfo;
+      }
+    | {
+        type: BarcodeValueType.EMAIL;
+        data: Email;
+      }
+    | {
+        type: BarcodeValueType.PHONE;
+        data: Phone;
+      }
+    | {
+        type: BarcodeValueType.SMS;
+        data: Sms;
+      }
+    | {
+        type: BarcodeValueType.URL;
+        data: UrlBookmark;
+      }
+    | {
+        type: BarcodeValueType.WIFI;
+        data: Wifi;
+      }
+    | {
+        type: BarcodeValueType.GEO;
+        data: GeoPoint;
+      }
+    | {
+        type: BarcodeValueType.CALENDAR_EVENT;
+        data: CalendarEvent;
+      }
+    | {
+        type: BarcodeValueType.DRIVER_LICENSE;
+        data: DriverLicense;
+      };
+};
+
+export interface CodeScannerOptions {
+  /**
+   * checkInverted: `Allows you to also scan white barcode with black backgrounds`
+   *
+   * 注意：鸿蒙（HarmonyOS）Scan Kit 无图像反色识别选项，此选项在鸿蒙端被忽略。
+   */
+  checkInverted?: boolean;
+}
+
+/**
+ * 鸿蒙端 BarcodeFormat → CodeType 映射（含上游 codeType→ScanType off-by-one 补偿）。
+ *
+ * 上游 @react-native-ohos/react-native-vision-camera（4.0.3/4.7.1）ScanManager 的 codeType
+ * 数组多插了 'itf-14' 条目，导致 `codeType.indexOf(type)` 的索引被直接当作 ScanType 枚举值传给
+ * Scan Kit customScan 时，从 itf-14 之后的格式整体偏移 1（如 QR 被配置成 UPC_A）。因此对受影响的
+ * 四种格式传入「可命中正确 ScanType 索引」的 CodeType 字符串：
+ *
+ * | 目标 BarcodeFormat | 期望 ScanType | 传入 CodeType | indexOf |
+ * |--------------------|---------------|---------------|---------|
+ * | QR_CODE            | QR_CODE(11)   | 'pdf-417'     | 11      |
+ * | PDF417             | PDF417(10)    | 'itf-14'      | 10      |
+ * | UPC_A              | UPC_A(12)     | 'qr'          | 12      |
+ * | UPC_E              | UPC_E(13)     | 'upc-a'       | 13      |
+ *
+ * @internal
+ */
+const FORMAT_TO_CODE_TYPE: Record<BarcodeFormat, CodeType | null> = {
+  [BarcodeFormat.UNKNOWN]: null,
+  [BarcodeFormat.ALL_FORMATS]: null,
+  [BarcodeFormat.CODE_128]: 'code-128',
+  [BarcodeFormat.CODE_39]: 'code-39',
+  [BarcodeFormat.CODE_93]: 'code-93',
+  [BarcodeFormat.CODABAR]: 'codabar',
+  [BarcodeFormat.DATA_MATRIX]: 'data-matrix',
+  [BarcodeFormat.EAN_13]: 'ean-13',
+  [BarcodeFormat.EAN_8]: 'ean-8',
+  [BarcodeFormat.ITF]: 'itf',
+  [BarcodeFormat.QR_CODE]: 'pdf-417',
+  [BarcodeFormat.UPC_A]: 'qr',
+  [BarcodeFormat.UPC_E]: 'upc-a',
+  [BarcodeFormat.PDF417]: 'itf-14' as CodeType,
+  [BarcodeFormat.AZTEC]: 'aztec',
+};
+
+/**
+ * 鸿蒙端 Code.type → BarcodeFormat 反向映射（含补偿反向翻译）。
+ *
+ * 上报方向：ScanManager 用 `this.codeType[data.scanType]` 报告 code.type。因请求时已用补偿后的
+ * CodeType，扫码命中后 scanType 为正确的 ScanType 数值，故 code.type 即为补偿字符串本身，需按
+ * 反向表翻译回原 BarcodeFormat。'upc-e' 无有效 ScanType（indexOf 落在 14），映射为 UNKNOWN。
+ *
+ * @internal
+ */
+const CODE_TYPE_TO_FORMAT: Record<string, BarcodeFormat> = {
+  unknown: BarcodeFormat.UNKNOWN,
+  aztec: BarcodeFormat.AZTEC,
+  codabar: BarcodeFormat.CODABAR,
+  'code-39': BarcodeFormat.CODE_39,
+  'code-93': BarcodeFormat.CODE_93,
+  'code-128': BarcodeFormat.CODE_128,
+  'data-matrix': BarcodeFormat.DATA_MATRIX,
+  'ean-8': BarcodeFormat.EAN_8,
+  'ean-13': BarcodeFormat.EAN_13,
+  itf: BarcodeFormat.ITF,
+  'itf-14': BarcodeFormat.PDF417,
+  'pdf-417': BarcodeFormat.QR_CODE,
+  qr: BarcodeFormat.UPC_A,
+  'upc-a': BarcodeFormat.UPC_E,
+  'upc-e': BarcodeFormat.UNKNOWN,
+};
+
+/**
+ * 将 JS 层 BarcodeFormat[] 转换为 vision-camera codeScanner 需要的 CodeType[]。
+ *
+ * - 空数组或包含 ALL_FORMATS：返回空数组，触发 Scan Kit customScan 的 ALL 默认扫描。
+ * - 其余格式经 FORMAT_TO_CODE_TYPE 映射（含上游 off-by-one 补偿）。
+ *
+ * @internal
+ */
+export function mapFormatsToCodeTypes(types: BarcodeFormat[]): CodeType[] {
+  if (!types || types.length === 0) {
+    return [];
+  }
+  if (types.includes(BarcodeFormat.ALL_FORMATS)) {
+    return [];
+  }
+  const result: CodeType[] = [];
+  for (const format of types) {
+    const codeType = FORMAT_TO_CODE_TYPE[format];
+    if (codeType) {
+      result.push(codeType);
+    }
+  }
+  return result;
+}
+
+/**
+ * 将 vision-camera 扫码回调的 Code 转换为原 API 的 Barcode 类型。
+ *
+ * 鸿蒙 Scan Kit 的 ScanResult 仅提供 originalValue / scanCodeRect / cornerPoints，
+ * 无 MLKit/iOS Vision 的丰富结构化字段，因此 content 统一降级为
+ * `{ type: BarcodeValueType.TEXT, data: rawValue }`。
+ *
+ * @internal
+ */
+export function toBarcode(code: Code): Barcode {
+  const format = CODE_TYPE_TO_FORMAT[code.type] ?? BarcodeFormat.UNKNOWN;
+  const value = code.value;
+  const barcode: Barcode = {
+    format,
+    content: {
+      type: BarcodeValueType.TEXT,
+      data: value ?? '',
+    },
+  };
+  if (value !== undefined) {
+    barcode.rawValue = value;
+    barcode.displayValue = value;
+  }
+  if (code.frame) {
+    barcode.boundingBox = {
+      left: code.frame.x,
+      top: code.frame.y,
+      right: code.frame.x + code.frame.width,
+      bottom: code.frame.y + code.frame.height,
+    };
+  }
+  if (code.corners) {
+    barcode.cornerPoints = code.corners;
+  }
+  return barcode;
+}
+
+/**
+ * 按调用方请求的格式，归一化 UPC_A / EAN_13 上报结果。
+ *
+ * UPC_A 与「前导 0 的 EAN_13」条纹图案完全等价，Scan Kit / 多数扫码库常把 UPC_A
+ * 报成 EAN_13（13 位且以 0 开头），或把 EAN_13 报成 UPC_A（去掉前导 0）。
+ * 当请求格式仅包含其中一种时，按请求意图纠正 format 与数值，便于格式过滤用例验证。
+ *
+ * @internal
+ */
+export function normalizeReportedBarcode(
+  barcode: Barcode,
+  requestedTypes: BarcodeFormat[]
+): Barcode {
+  if (
+    !requestedTypes ||
+    requestedTypes.length === 0 ||
+    requestedTypes.includes(BarcodeFormat.ALL_FORMATS)
+  ) {
+    return barcode;
+  }
+
+  const wantsUpcA = requestedTypes.includes(BarcodeFormat.UPC_A);
+  const wantsEan13 = requestedTypes.includes(BarcodeFormat.EAN_13);
+  const value = barcode.rawValue ?? barcode.displayValue ?? '';
+
+  // 仅请求 UPC_A：Scan Kit 常把 UPC_A 报成带前导 0 的 EAN_13
+  if (
+    wantsUpcA &&
+    !wantsEan13 &&
+    barcode.format === BarcodeFormat.EAN_13 &&
+    value.length === 13 &&
+    value.startsWith('0')
+  ) {
+    const upc = value.slice(1);
+    return {
+      ...barcode,
+      format: BarcodeFormat.UPC_A,
+      rawValue: upc,
+      displayValue: upc,
+      content: { type: BarcodeValueType.TEXT, data: upc },
+    };
+  }
+
+  // 仅请求 EAN_13：偶发把等价码报成 12 位 UPC_A
+  if (
+    wantsEan13 &&
+    !wantsUpcA &&
+    barcode.format === BarcodeFormat.UPC_A &&
+    value.length === 12
+  ) {
+    const ean = '0' + value;
+    return {
+      ...barcode,
+      format: BarcodeFormat.EAN_13,
+      rawValue: ean,
+      displayValue: ean,
+      content: { type: BarcodeValueType.TEXT, data: ean },
+    };
+  }
+
+  return barcode;
+}
+
+/**
+ * Scans barcodes in the passed frame with MLKit
+ *
+ * @param frame Camera frame
+ * @param types Array of barcode types to detect (for optimal performance, use less types)
+ * @param options Scan options
+ * @returns Detected barcodes from MLKit
+ *
+ * 鸿蒙端不支持：Frame Processor 工作集机制在 @react-native-ohos/react-native-vision-camera v4
+ * 中不存在（不导出 useFrameProcessor / FrameProcessorPlugin）。此函数在鸿蒙端导出为抛错 stub，
+ * 请改用 `useScanBarcodes` 返回的 codeScanner 并传给 `<Camera codeScanner={...}>`。
+ */
+export function scanBarcodes(
+  _frame: Frame,
+  _types: BarcodeFormat[],
+  _options?: CodeScannerOptions
+): Barcode[] {
+  throw new Error(
+    'Harmony 不支持 Frame Processor worklet，请使用 useScanBarcodes 返回的 codeScanner 并传给 <Camera codeScanner={...}>'
+  );
+}
+
+export * from './hook';