@unif/react-native-hms-scan 0.6.1 → 1.0.0

package/src/Scanner/ScannerInner.tsx

@@ -0,0 +1,391 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { AppState, Linking, StyleSheet, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { HmsScanView } from '../HmsScanView/HmsScanView';
+import { decodeImage } from '../decodeImage';
+import {
+  getCameraPermissionStatus,
+  requestCameraPermission,
+} from '../permissions';
+import { formatConfiguration } from '../format';
+import { scanError } from '../errors';
+import type {
+  RequestedScanFormat,
+  ScannerImage,
+  ScanFailure,
+  ScanResult,
+  ScanTorchState,
+} from '../types';
+import { Viewfinder } from './Viewfinder';
+import { ScanTopBar } from './ScanTopBar';
+import { ScanToolbar } from './ScanToolbar';
+import { ResultFocus } from './ResultFocus/ResultFocus';
+import { ResultFail } from './ResultFail';
+import { DeniedOverlay } from './DeniedOverlay';
+import { ScanErrorOverlay } from './ScanErrorOverlay';
+
+import { styles } from './styles';
+import type { Phase, ScannerProps, SelectedResult } from './types';
+
+export function ScannerInner({
+  title = '扫一扫',
+  hintText = '将条码 / 二维码放入框内，自动扫描',
+  formats,
+  topInset,
+  bottomInset,
+  showTorch = true,
+  autoConfirm = false,
+  pickImage,
+  onConfirm,
+  onClose,
+  onError,
+}: ScannerProps) {
+  const insets = useSafeAreaInsets();
+  const config = formatConfiguration(formats);
+  const configKey = config.error?.message ?? config.csv;
+  const configRef = useRef(config);
+  configRef.current = config;
+  const callbacks = useRef({ onConfirm, onClose, onError, autoConfirm });
+  callbacks.current = { onConfirm, onClose, onError, autoConfirm };
+  const [phase, setPhase] = useState<Phase>('init');
+  const [result, setResult] = useState<Readonly<ScanResult> | null>(null);
+  const [torchRequest, setTorchRequest] = useState(false);
+  const [torchState, setTorchState] = useState<Readonly<ScanTorchState>>({
+    on: false,
+  });
+  const [scanSession, setScanSession] = useState(0);
+  const [activeFormats, setActiveFormats] = useState<
+    readonly RequestedScanFormat[]
+  >([]);
+  const mounted = useRef(false);
+  const closed = useRef(false);
+  const accepting = useRef(false);
+  const cameraSession = useRef(0);
+  const permissionRun = useRef(0);
+  const imageRun = useRef(0);
+  const imagePending = useRef(false);
+  const restartAfterImage = useRef(false);
+  const waitingForSettings = useRef(false);
+  const selected = useRef<SelectedResult | null>(null);
+
+  const stopAdoption = useCallback(() => {
+    accepting.current = false;
+    ++cameraSession.current;
+    ++imageRun.current;
+    ++permissionRun.current;
+    selected.current = null;
+  }, []);
+  const startScan = useCallback(() => {
+    if (!mounted.current || closed.current) return;
+    if (imagePending.current) {
+      restartAfterImage.current = true;
+      setPhase('processing');
+      return;
+    }
+    const current = configRef.current;
+    if (current.error) {
+      setPhase('error');
+      callbacks.current.onError?.(current.error);
+      return;
+    }
+    setActiveFormats(
+      current.csv ? (current.csv.split(',') as RequestedScanFormat[]) : []
+    );
+    setResult(null);
+    selected.current = null;
+    accepting.current = true;
+    setScanSession(++cameraSession.current);
+    setPhase('scan');
+  }, []);
+  const reportFatal = useCallback(
+    (error: Readonly<ScanFailure>) => {
+      stopAdoption();
+      setResult(null);
+      setTorchRequest(false);
+      setPhase(error.reason === 'permission_denied' ? 'denied' : 'error');
+      callbacks.current.onError?.(error);
+    },
+    [stopAdoption]
+  );
+  const runPermission = useCallback(
+    async (requestIfNeeded: boolean) => {
+      const run = ++permissionRun.current;
+      const current = () =>
+        mounted.current && !closed.current && run === permissionRun.current;
+      let status;
+      try {
+        status = await getCameraPermissionStatus();
+        if (!current()) return;
+        if (
+          requestIfNeeded &&
+          (status === 'denied' || status === 'undetermined')
+        ) {
+          status = await requestCameraPermission();
+          if (!current()) return;
+        }
+      } catch (error) {
+        if (current()) reportFatal(error as ScanFailure);
+        return;
+      }
+      if (status === 'granted') startScan();
+      else {
+        accepting.current = false;
+        setPhase('denied');
+      }
+    },
+    [reportFatal, startScan]
+  );
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      stopAdoption();
+    };
+  }, [stopAdoption]);
+  useEffect(() => {
+    if (closed.current) return;
+    stopAdoption();
+    setResult(null);
+    if (imagePending.current) {
+      restartAfterImage.current = true;
+      setPhase('processing');
+      return;
+    }
+    if (configRef.current.error) {
+      reportFatal(configRef.current.error);
+      return;
+    }
+    setPhase('init');
+    void runPermission(true);
+  }, [configKey, reportFatal, runPermission, stopAdoption]);
+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active' && waitingForSettings.current && !closed.current) {
+        waitingForSettings.current = false;
+        void runPermission(false);
+      }
+    });
+    return () => subscription.remove();
+  }, [runPermission]);
+  useEffect(() => {
+    if (!showTorch) setTorchRequest(false);
+  }, [showTorch]);
+
+  const deliver = useCallback(() => {
+    const item = selected.current;
+    if (!mounted.current || closed.current || !item || item.delivered) return;
+    // Mark delivery before calling business code. A callback failure cannot undo it.
+    item.delivered = true;
+    setPhase('done');
+    callbacks.current.onConfirm(item.result);
+  }, []);
+  const adopt = useCallback(
+    (next: Readonly<ScanResult>) => {
+      selected.current = { result: next, delivered: false };
+      setResult(next);
+      setPhase('result');
+      if (callbacks.current.autoConfirm) deliver();
+    },
+    [deliver]
+  );
+  const onCameraResult = useCallback(
+    (results: readonly ScanResult[]) => {
+      if (
+        !mounted.current ||
+        closed.current ||
+        !accepting.current ||
+        scanSession !== cameraSession.current
+      )
+        return;
+      const first = results[0];
+      if (!first) return;
+      accepting.current = false;
+      adopt(first);
+    },
+    [adopt, scanSession]
+  );
+  const onCameraError = useCallback(
+    (error: Readonly<ScanFailure>) => {
+      if (
+        !mounted.current ||
+        closed.current ||
+        !accepting.current ||
+        scanSession !== cameraSession.current
+      )
+        return;
+      reportFatal(error);
+    },
+    [reportFatal, scanSession]
+  );
+  const close = useCallback(() => {
+    if (closed.current) return;
+    closed.current = true;
+    stopAdoption();
+    setTorchRequest(false);
+    setPhase('closed');
+    callbacks.current.onClose?.();
+  }, [stopAdoption]);
+  const reset = useCallback(() => {
+    stopAdoption();
+    startScan();
+  }, [startScan, stopAdoption]);
+  const retry = useCallback(() => {
+    stopAdoption();
+    if (imagePending.current) {
+      restartAfterImage.current = true;
+      return;
+    }
+    setPhase('init');
+    void runPermission(true);
+  }, [runPermission, stopAdoption]);
+  const openSettings = useCallback(async () => {
+    waitingForSettings.current = true;
+    try {
+      await Linking.openSettings();
+    } catch (error) {
+      waitingForSettings.current = false;
+      if (mounted.current && !closed.current)
+        reportFatal(
+          scanError(error, {
+            reason: 'unavailable',
+            message: '打开系统设置失败',
+          })
+        );
+    }
+  }, [reportFatal]);
+
+  const onAlbum = useCallback(async () => {
+    if (
+      !pickImage ||
+      !accepting.current ||
+      imagePending.current ||
+      closed.current
+    )
+      return;
+    accepting.current = false;
+    const run = ++imageRun.current;
+    const current = () =>
+      mounted.current && !closed.current && run === imageRun.current;
+    const inputFormats = activeFormats;
+    imagePending.current = true;
+    setPhase('processing');
+    let image: ScannerImage | null = null;
+    let results: readonly ScanResult[] | undefined;
+    let failure: ScanFailure | undefined;
+    try {
+      image = await pickImage();
+      if (current() && image)
+        results = await decodeImage({ uri: image.uri, formats: inputFormats });
+    } catch (error) {
+      failure = scanError(error, {
+        reason: 'image_unavailable',
+        message: '选择或读取图片失败',
+      });
+    } finally {
+      imagePending.current = false;
+      // The original provider owns cleanup, including after this component unmounts.
+      try {
+        image?.onSourceReleased?.();
+      } finally {
+        if (current()) {
+          if (failure) {
+            setPhase('imageError');
+            callbacks.current.onError?.(failure);
+          } else if (!image) startScan();
+          else if (results?.[0]) adopt(results[0]);
+          else setPhase('empty');
+        } else if (
+          restartAfterImage.current &&
+          mounted.current &&
+          !closed.current
+        ) {
+          restartAfterImage.current = false;
+          setPhase('init');
+          void runPermission(true);
+        }
+      }
+    }
+  }, [activeFormats, adopt, pickImage, runPermission, startScan]);
+
+  const hasCamera = !['init', 'denied', 'error', 'closed'].includes(phase);
+  const showChrome = phase === 'scan' || phase === 'processing';
+  const bottom = bottomInset ?? insets.bottom;
+  return (
+    <View style={styles.root}>
+      {hasCamera && (
+        <HmsScanView
+          key={scanSession}
+          style={StyleSheet.absoluteFill}
+          formats={activeFormats}
+          paused={phase !== 'scan'}
+          torch={torchRequest}
+          onScanResult={onCameraResult}
+          onScanError={onCameraError}
+          onTorchState={(state) => {
+            if (
+              !closed.current &&
+              mounted.current &&
+              scanSession === cameraSession.current
+            ) {
+              setTorchState(state);
+              // A failed request or the SDK's controls can change actual state.
+              // Keep the next toggle based on that report, without optimistic UI.
+              setTorchRequest(showTorch && state.on);
+            }
+          }}
+        />
+      )}
+      {showChrome && (
+        <Viewfinder
+          size={256}
+          detecting={phase === 'processing'}
+          hintText={hintText}
+        />
+      )}
+      {hasCamera && (
+        <ScanTopBar title={title} topInset={topInset ?? insets.top} />
+      )}
+      {showChrome && (
+        <ScanToolbar
+          flash={torchState.on}
+          bottomInset={bottom}
+          onFlash={
+            showTorch && torchState.available !== false
+              ? () => setTorchRequest((value) => !value)
+              : undefined
+          }
+          onAlbum={pickImage ? onAlbum : undefined}
+          onClose={onClose ? close : undefined}
+        />
+      )}
+      {phase === 'result' && result && (
+        <ResultFocus
+          result={result}
+          bottomInset={bottom}
+          onRescan={reset}
+          onConfirm={deliver}
+        />
+      )}
+      {(phase === 'empty' || phase === 'imageError') && (
+        <ResultFail
+          bottomInset={bottom}
+          failed={phase === 'imageError'}
+          onRescan={reset}
+        />
+      )}
+      {phase === 'error' && (
+        <ScanErrorOverlay
+          onClose={onClose ? close : undefined}
+          onRetry={retry}
+        />
+      )}
+      {phase === 'denied' && (
+        <DeniedOverlay
+          onClose={onClose ? close : undefined}
+          onSettings={openSettings}
+        />
+      )}
+    </View>
+  );
+}

package/src/Scanner/styles.ts

@@ -0,0 +1,6 @@
+import { StyleSheet } from 'react-native';
+import { scanChrome } from './scanChrome';
+
+export const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: scanChrome.cameraBg },
+});

package/src/Scanner/types.ts

@@ -0,0 +1,36 @@
+import type {
+  RequestedScanFormat,
+  ScannerImage,
+  ScanFailure,
+  ScanResult,
+} from '../types';
+
+export type Phase =
+  | 'init'
+  | 'scan'
+  | 'processing'
+  | 'result'
+  | 'empty'
+  | 'imageError'
+  | 'denied'
+  | 'error'
+  | 'done'
+  | 'closed';
+export interface ScannerProps {
+  title?: string;
+  hintText?: string;
+  formats?: readonly RequestedScanFormat[];
+  topInset?: number;
+  bottomInset?: number;
+  showTorch?: boolean;
+  autoConfirm?: boolean;
+  pickImage?(): Promise<ScannerImage | null>;
+  onConfirm(result: Readonly<ScanResult>): void;
+  onClose?(): void;
+  onError?(error: Readonly<ScanFailure>): void;
+}
+
+export interface SelectedResult {
+  result: Readonly<ScanResult>;
+  delivered: boolean;
+}

package/src/constants.ts

@@ -0,0 +1,55 @@
+import type { ScanFailure } from './types';
+
+/** The one source for public scan formats and input validation. */
+export const SCAN_FORMATS = [
+  'QR_CODE',
+  'AZTEC',
+  'DATA_MATRIX',
+  'PDF417',
+  'CODABAR',
+  'CODE_39',
+  'CODE_93',
+  'CODE_128',
+  'EAN_8',
+  'EAN_13',
+  'UPC_A',
+  'UPC_E',
+  'ITF14',
+  'MULTI_FUNCTIONAL',
+  'UNKNOWN',
+] as const;
+export const SCAN_CONTENT_TYPES = [
+  'TEXT',
+  'URL',
+  'EMAIL',
+  'PHONE',
+  'SMS',
+  'WIFI',
+  'CONTACT',
+  'EVENT',
+  'LOCATION',
+  'DRIVER',
+  'ISBN',
+  'ARTICLE',
+  'OTHER',
+] as const;
+
+export const SCAN_FORMAT_SET: ReadonlySet<string> = new Set(SCAN_FORMATS);
+export const SCAN_CONTENT_TYPE_SET: ReadonlySet<string> = new Set(
+  SCAN_CONTENT_TYPES
+);
+
+export const SCAN_ERROR_REASONS: Readonly<
+  Record<string, ScanFailure['reason']>
+> = {
+  E_INVALID_INPUT: 'invalid_input',
+  E_NO_CAMERA_PERMISSION: 'permission_denied',
+  E_NO_READ_PERMISSION: 'permission_denied',
+  E_IMAGE_LOAD_FAILED: 'image_unavailable',
+  E_DECODE_FAILED: 'decode_failed',
+  E_INVALID_RESPONSE: 'invalid_response',
+  E_UNSUPPORTED: 'unsupported',
+  E_UNSUPPORTED_FORMAT: 'unsupported',
+  E_CAMERA_INIT: 'unavailable',
+  E_UNAVAILABLE: 'unavailable',
+};

package/src/decodeImage.ts

@@ -1,37 +1,43 @@
 import NativeHmsScan from './NativeHmsScan';
 import { formatsToCsv, parseResultsJson } from './format';
-import { HmsScanError, type DecodeImageOptions, type ScanResult } from './types';
+import { scanError } from './errors';
+import { ScanError } from './ScanError';
+import type { DecodeScanImageInput, ScanResult } from './types';
 
-/**
- * 从本地图片解码条码 / 二维码（华为 Bitmap 模式）。
- *
- * @param uri 本地图片。iOS 支持 file://、绝对路径、data:；Android 支持
- *            file://、绝对路径、content://、android.resource://。
- *            两端都不下载远程 URL，也不支持 ph:// / assets-library://。
- * @param options 可选；formats 限定码制，不传 = 全部。
- * @returns 命中的结果数组（可能为空）。
- * @throws HmsScanError 图片加载失败 / 读权限缺失等。
- */
 export async function decodeImage(
-  uri: string,
-  options?: DecodeImageOptions
-): Promise<ScanResult[]> {
-  if (!uri) {
-    throw new HmsScanError('E_IMAGE_LOAD_FAILED', 'decodeImage: uri 不能为空');
+  input: Readonly<DecodeScanImageInput>
+): Promise<readonly ScanResult[]> {
+  // No remote authority, empty filename, fragment, query or malformed escapes.
+  const uri = input?.uri;
+  if (
+    typeof uri !== 'string' ||
+    !/^file:\/\/\/(?:[^?#\s]+\/)*[^/?#\s]+$/i.test(uri)
+  ) {
+    throw new ScanError({
+      reason: 'invalid_input',
+      message: 'decodeImage 需要可读的 file URI',
+    });
   }
   try {
-    const json = await NativeHmsScan.decodeImage(uri, formatsToCsv(options?.formats));
-    return parseResultsJson(json);
-  } catch (e) {
-    // 原生 reject 的 code 透传为 HmsScanError
-    const err = e as { code?: string; message?: string };
-    if (
-      err.code === 'E_NO_READ_PERMISSION' ||
-      err.code === 'E_IMAGE_LOAD_FAILED' ||
-      err.code === 'E_DECODE_FAILED'
-    ) {
-      throw new HmsScanError(err.code, err.message);
-    }
-    throw new HmsScanError('E_UNKNOWN', err.message ?? 'decodeImage failed');
+    decodeURIComponent(uri);
+  } catch {
+    throw new ScanError({
+      reason: 'invalid_input',
+      message: '图片 URI 编码无效',
+    });
+  }
+  const csv = formatsToCsv(input.formats);
+  if (!NativeHmsScan)
+    throw new ScanError({
+      reason: 'unavailable',
+      message: 'HMS Scan 原生模块未安装',
+    });
+  try {
+    return parseResultsJson(await NativeHmsScan.decodeImage(uri, csv));
+  } catch (error) {
+    throw scanError(error, {
+      reason: 'decode_failed',
+      message: '图片识别失败',
+    });
   }
 }

package/src/decodeImage.web.ts

@@ -0,0 +1,8 @@
+import { unsupportedScanError } from './errors';
+import type { DecodeScanImageInput, ScanResult } from './types';
+
+export async function decodeImage(
+  _input: Readonly<DecodeScanImageInput>
+): Promise<readonly ScanResult[]> {
+  throw unsupportedScanError();
+}

package/src/errors.ts

@@ -0,0 +1,26 @@
+import { ScanError } from './ScanError';
+import { SCAN_ERROR_REASONS } from './constants';
+import type { NativeScanFailure, ScanFailure } from './types';
+
+/** Native boundary normalization; Scanner only uses this for its external picker. */
+export function scanError(
+  error: unknown,
+  fallback: Readonly<ScanFailure>
+): ScanError {
+  if (error instanceof ScanError) return error;
+  const raw =
+    error && typeof error === 'object' ? (error as NativeScanFailure) : {};
+  const sourceCode = typeof raw.code === 'string' ? raw.code : undefined;
+  return new ScanError({
+    reason: (sourceCode && SCAN_ERROR_REASONS[sourceCode]) || fallback.reason,
+    message: typeof raw.message === 'string' ? raw.message : fallback.message,
+    ...(sourceCode ? { sourceCode } : {}),
+  });
+}
+
+export function unsupportedScanError(): ScanError {
+  return new ScanError({
+    reason: 'unsupported',
+    message: 'HMS Scan 仅支持 Android 与 iOS 设备',
+  });
+}