@unif/react-native-hms-scan 0.1.0

package/src/Scanner/Scanner.tsx

@@ -0,0 +1,238 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Linking, StyleSheet, View } from 'react-native';
+import { ThemeProvider, ToastHost, toast } from '@unif/react-native-design';
+import { HmsScanView } from '../HmsScanView';
+import { decodeImage } from '../decodeImage';
+import {
+  getCameraPermissionStatus,
+  requestCameraPermission,
+} from '../permissions';
+import type { BarcodeFormat, ScanProduct, ScanResult } from '../types';
+import { scanChrome } from './scanChrome';
+import { Viewfinder } from './Viewfinder';
+import { ScanTopBar } from './ScanTopBar';
+import { ScanToolbar } from './ScanToolbar';
+import { ResultFocus } from './ResultFocus';
+import { ResultFail } from './ResultFail';
+import { DeniedOverlay } from './DeniedOverlay';
+
+type Phase = 'init' | 'scan' | 'detecting' | 'success' | 'fail' | 'denied';
+
+const VF_SIZE = 256;
+const DEFAULT_HINT = '将条码 / 二维码放入框内，自动扫描';
+
+export interface ScannerProps {
+  /** 顶栏标题，默认 "扫一扫"。 */
+  title?: string;
+  /** 限定识别码制；不传 = 全部。 */
+  formats?: BarcodeFormat[];
+  /** 取景态提示文案。 */
+  hintText?: string;
+  /** 顶部安全区（默认 54）。用 react-native-safe-area-context 时可传 insets.top。 */
+  topInset?: number;
+  /** 底部安全区（默认 34）。 */
+  bottomInset?: number;
+  /** 左上角关闭。 */
+  onClose?: () => void;
+  /**
+   * 扫到条码后由宿主解析商品信息（用于浮层确认卡）。
+   * 返回 null/undefined 视为"未识别"，抛错亦然。不传则默认用扫到的原文当商品名。
+   */
+  resolveProduct?: (
+    result: ScanResult
+  ) => ScanProduct | null | undefined | Promise<ScanProduct | null | undefined>;
+  /** 用户点"确认"：把结果带回上一级（宿主通常在此导航返回）。 */
+  onConfirm?: (product: ScanProduct, result: ScanResult) => void;
+  /**
+   * 点"相册"：宿主用自己的图片选择器选图并返回本地 uri（取消则返回 null）。
+   * 不传则相册按钮不可用。
+   */
+  pickImage?: () => Promise<string | null>;
+}
+
+/**
+ * 成品「扫一扫」界面（聚焦款）。底层 <HmsScanView> 出相机画面，取景框 / 工具栏 / 结果卡
+ * 全用 @unif/react-native-design 的主题令牌与组件绘制（统一风格）。自带 ThemeProvider +
+ * ToastHost，可直接整屏接入；放进宿主已有的 ThemeProvider 里也兼容。
+ */
+export function Scanner(props: ScannerProps) {
+  return (
+    <ThemeProvider>
+      <ScannerInner {...props} />
+      <ToastHost />
+    </ThemeProvider>
+  );
+}
+
+function ScannerInner({
+  title = '扫一扫',
+  formats,
+  hintText = DEFAULT_HINT,
+  topInset = 54,
+  bottomInset = 34,
+  onClose,
+  resolveProduct,
+  onConfirm,
+  pickImage,
+}: ScannerProps) {
+  const [phase, setPhase] = useState<Phase>('init');
+  const [torch, setTorch] = useState(false);
+  const [product, setProduct] = useState<ScanProduct | null>(null);
+  const [detectMs, setDetectMs] = useState(0);
+
+  const handlingRef = useRef(false);
+  const detectStartRef = useRef(0);
+  const lastResultRef = useRef<ScanResult | null>(null);
+  const mountedRef = useRef(true);
+
+  // 权限流：已授权 → scan；否则请求；仍未授权 → denied。
+  useEffect(() => {
+    mountedRef.current = true;
+    (async () => {
+      try {
+        let status = await getCameraPermissionStatus();
+        if (status === 'undetermined' || status === 'denied') {
+          status = await requestCameraPermission();
+        }
+        if (!mountedRef.current) return;
+        setPhase(status === 'granted' ? 'scan' : 'denied');
+      } catch {
+        if (mountedRef.current) setPhase('scan');
+      }
+    })();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const reset = useCallback(() => {
+    handlingRef.current = false;
+    setProduct(null);
+    setPhase('scan');
+  }, []);
+
+  const finalize = useCallback(
+    async (result: ScanResult) => {
+      lastResultRef.current = result;
+      try {
+        const resolved = resolveProduct
+          ? await resolveProduct(result)
+          : { name: result.value };
+        if (!mountedRef.current) return;
+        if (!resolved) {
+          setPhase('fail');
+          return;
+        }
+        setProduct({ barcode: result.value, ...resolved });
+        setDetectMs(Date.now() - detectStartRef.current);
+        setPhase('success');
+      } catch {
+        if (mountedRef.current) setPhase('fail');
+      }
+    },
+    [resolveProduct]
+  );
+
+  const onCameraResult = useCallback(
+    (results: ScanResult[]) => {
+      if (phase !== 'scan' || handlingRef.current) return;
+      const first = results[0];
+      if (!first) return;
+      handlingRef.current = true;
+      detectStartRef.current = Date.now();
+      setPhase('detecting');
+      void finalize(first);
+    },
+    [phase, finalize]
+  );
+
+  const onScanError = useCallback((error: { code: string; message: string }) => {
+    if (error.code === 'E_NO_CAMERA_PERMISSION') setPhase('denied');
+  }, []);
+
+  const onAlbum = useCallback(async () => {
+    if (!pickImage || handlingRef.current) return;
+    try {
+      const uri = await pickImage();
+      if (!uri || !mountedRef.current) return;
+      handlingRef.current = true;
+      detectStartRef.current = Date.now();
+      setPhase('detecting');
+      const results = await decodeImage(uri, formats ? { formats } : undefined);
+      if (!mountedRef.current) return;
+      const first = results[0];
+      if (!first) {
+        setPhase('fail');
+        return;
+      }
+      await finalize(first);
+    } catch {
+      if (mountedRef.current) {
+        handlingRef.current = true;
+        setPhase('fail');
+      }
+    }
+  }, [pickImage, formats, finalize]);
+
+  const onConfirmPress = useCallback(() => {
+    const r = lastResultRef.current;
+    const p = product;
+    if (p && r) onConfirm?.(p, r);
+    toast.success('已确认 · 扫描结果已填入上一级');
+    reset();
+  }, [product, onConfirm, reset]);
+
+  const showChrome = phase === 'scan' || phase === 'detecting';
+
+  return (
+    <View style={styles.root}>
+      {phase !== 'denied' && phase !== 'init' && (
+        <HmsScanView
+          style={StyleSheet.absoluteFill}
+          formats={formats}
+          paused={phase !== 'scan'}
+          torch={torch}
+          onScanResult={onCameraResult}
+          onScanError={onScanError}
+        />
+      )}
+
+      {showChrome && (
+        <Viewfinder size={VF_SIZE} detecting={phase === 'detecting'} hintText={hintText} />
+      )}
+
+      {phase !== 'denied' && phase !== 'init' && (
+        <ScanTopBar title={title} topInset={topInset} onClose={onClose} />
+      )}
+
+      {showChrome && (
+        <ScanToolbar
+          flash={torch}
+          bottomInset={bottomInset}
+          onFlash={() => setTorch((t) => !t)}
+          onAlbum={onAlbum}
+        />
+      )}
+
+      {phase === 'success' && product && (
+        <ResultFocus
+          product={product}
+          detectMs={detectMs}
+          bottomInset={bottomInset}
+          onContinue={reset}
+          onConfirm={onConfirmPress}
+        />
+      )}
+
+      {phase === 'fail' && <ResultFail bottomInset={bottomInset} onRetry={reset} />}
+
+      {phase === 'denied' && (
+        <DeniedOverlay onClose={onClose} onSettings={() => Linking.openSettings()} />
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: scanChrome.cameraBg },
+});

package/src/Scanner/Viewfinder.tsx

@@ -0,0 +1,115 @@
+import { useEffect, useRef } from 'react';
+import { Animated, Easing, StyleSheet, View } from 'react-native';
+import { Icon, useColors, r } from '@unif/react-native-design';
+import { scanChrome } from './scanChrome';
+import { ScanHint } from './ScanHint';
+
+interface ViewfinderProps {
+  /** 取景窗边长（px）。窗高 = size × 0.82。 */
+  size: number;
+  /** 识别中（停止呼吸/脉冲动画，准星与边框变淡）。 */
+  detecting: boolean;
+  /** 取景态提示文案。 */
+  hintText: string;
+}
+
+// 聚焦款取景：圆角窗 + 白描边 + 主题主色脉冲准星环 + 中心十字（design 的 scan 图标）。
+// 窗外暗化用「上 / 中(左+窗+右) / 下」三段布局还原（等价于设计稿 box-shadow 挖洞）。
+export function Viewfinder({ size, detecting, hintText }: ViewfinderProps) {
+  const c = useColors();
+  const windowH = Math.round(size * 0.82);
+  const scale = useRef(new Animated.Value(1)).current;
+  const pulse = useRef(new Animated.Value(1)).current;
+
+  useEffect(() => {
+    if (detecting) {
+      scale.setValue(1);
+      pulse.setValue(0.25);
+      return;
+    }
+    const ease = Easing.inOut(Easing.ease);
+    const breathe = Animated.loop(
+      Animated.sequence([
+        Animated.timing(scale, { toValue: 1.012, duration: 1300, easing: ease, useNativeDriver: true }),
+        Animated.timing(scale, { toValue: 1, duration: 1300, easing: ease, useNativeDriver: true }),
+      ])
+    );
+    const reticle = Animated.loop(
+      Animated.sequence([
+        Animated.timing(pulse, { toValue: 0.55, duration: 900, easing: ease, useNativeDriver: true }),
+        Animated.timing(pulse, { toValue: 1, duration: 900, easing: ease, useNativeDriver: true }),
+      ])
+    );
+    breathe.start();
+    reticle.start();
+    return () => {
+      breathe.stop();
+      reticle.stop();
+    };
+  }, [detecting, scale, pulse]);
+
+  const scrim = { backgroundColor: c.scrim };
+
+  return (
+    <View style={styles.overlay} pointerEvents="none">
+      <View style={[styles.scrimTop, scrim]} />
+
+      <View style={[styles.midRow, { height: windowH }]}>
+        <View style={[styles.scrimSide, scrim]} />
+        <Animated.View style={{ width: size, height: windowH, transform: [{ scale }] }}>
+          <View style={styles.windowBorder} />
+          <Animated.View
+            style={[styles.reticle, { borderColor: c.primary, opacity: pulse }]}
+          />
+          <View style={styles.crosshair}>
+            <Icon name="scan" size={r(30)} color={scanChrome.crosshair} />
+          </View>
+        </Animated.View>
+        <View style={[styles.scrimSide, scrim]} />
+      </View>
+
+      <View style={[styles.scrimBottom, scrim]}>
+        <ScanHint detecting={detecting} text={hintText} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, zIndex: 15 },
+  // 上:下 = 1:1.35，使取景窗略高于屏幕中线
+  scrimTop: { flex: 1 },
+  scrimBottom: { flex: 1.35, alignItems: 'center' },
+  midRow: { flexDirection: 'row' },
+  scrimSide: { flex: 1 },
+  windowBorder: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderRadius: r(22),
+    borderWidth: 1.5,
+    borderColor: scanChrome.windowBorder,
+  },
+  reticle: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderRadius: r(22),
+    borderWidth: 2,
+  },
+  crosshair: {
+    position: 'absolute',
+    top: '50%',
+    left: '50%',
+    width: r(30),
+    height: r(30),
+    marginTop: r(-15),
+    marginLeft: r(-15),
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});

package/src/Scanner/scanChrome.ts

@@ -0,0 +1,20 @@
+// 相机暗景之上的 chrome 专属常量——取景区恒为深色实景，这些不随主题变化。
+// 其余颜色一律走 @unif/react-native-design 主题令牌（useColors / useThemedStyles）。
+export const scanChrome = {
+  /** 相机未就绪时的底色（深色实景占位）。 */
+  cameraBg: '#0c0b0a',
+  white: '#FFFFFF',
+  /** 顶栏关闭键玻璃底。 */
+  glassDisc: 'rgba(20,18,16,0.42)',
+  /** 工具栏未点亮玻璃底。 */
+  glassDisc2: 'rgba(28,26,24,0.5)',
+  glassBorder: 'rgba(255,255,255,0.16)',
+  glassBorderActive: 'rgba(255,255,255,0.25)',
+  /** 取景提示文字。 */
+  hintText: 'rgba(255,255,255,0.86)',
+  toolbarLabel: 'rgba(255,255,255,0.82)',
+  /** 取景窗白色描边。 */
+  windowBorder: 'rgba(255,255,255,0.55)',
+  crosshair: 'rgba(255,255,255,0.9)',
+  textShadow: 'rgba(0,0,0,0.55)',
+} as const;

package/src/decodeImage.ts

@@ -0,0 +1,36 @@
+import NativeHmsScan from './NativeHmsScan';
+import { formatsToCsv, parseResultsJson } from './format';
+import { HmsScanError, type DecodeImageOptions, type ScanResult } from './types';
+
+/**
+ * 从本地图片解码条码 / 二维码（华为 Bitmap 模式）。
+ *
+ * @param uri 本地图片：file:// / content:// / ph:// / 绝对路径。**不下载远程 URL**，
+ *            如需识别网络图请宿主先下载到本地再传入。
+ * @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 不能为空');
+  }
+  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');
+  }
+}

package/src/format.ts

@@ -0,0 +1,93 @@
+import {
+  ALL_BARCODE_FORMATS,
+  type BarcodeContentType,
+  type BarcodeFormat,
+  type ScanCornerPoint,
+  type ScanResult,
+} from './types';
+
+const FORMAT_SET = new Set<string>([...ALL_BARCODE_FORMATS, 'UNKNOWN']);
+
+const CONTENT_TYPES: readonly BarcodeContentType[] = [
+  'TEXT',
+  'URL',
+  'EMAIL',
+  'PHONE',
+  'SMS',
+  'WIFI',
+  'CONTACT',
+  'EVENT',
+  'LOCATION',
+  'DRIVER',
+  'ISBN',
+  'ARTICLE',
+  'OTHER',
+];
+const CONTENT_SET = new Set<string>(CONTENT_TYPES);
+
+/** 把任意字符串安全收敛成 BarcodeFormat（未知归 UNKNOWN）。 */
+export function coerceFormat(value: unknown): BarcodeFormat {
+  return typeof value === 'string' && FORMAT_SET.has(value)
+    ? (value as BarcodeFormat)
+    : 'UNKNOWN';
+}
+
+/** 把任意字符串安全收敛成 BarcodeContentType（未知/缺省 → undefined）。 */
+export function coerceContentType(value: unknown): BarcodeContentType | undefined {
+  return typeof value === 'string' && CONTENT_SET.has(value)
+    ? (value as BarcodeContentType)
+    : undefined;
+}
+
+/** formats[] → 逗号分隔 CSV（传给原生）；空/未传 → ''（= 全部码制）。 */
+export function formatsToCsv(formats?: readonly BarcodeFormat[]): string {
+  return formats && formats.length > 0 ? formats.join(',') : '';
+}
+
+function coerceCornerPoints(value: unknown): ScanCornerPoint[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const points = value
+    .filter(
+      (p): p is { x: number; y: number } =>
+        !!p && typeof p.x === 'number' && typeof p.y === 'number'
+    )
+    .map((p) => ({ x: p.x, y: p.y }));
+  return points.length > 0 ? points : undefined;
+}
+
+function coerceResult(raw: unknown): ScanResult | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const r = raw as Record<string, unknown>;
+  // 没有有效 value 的命中无意义，丢弃
+  if (typeof r.value !== 'string' || r.value.length === 0) return null;
+  const result: ScanResult = {
+    value: r.value,
+    format: coerceFormat(r.format),
+  };
+  const contentType = coerceContentType(r.contentType);
+  if (contentType) result.contentType = contentType;
+  const cornerPoints = coerceCornerPoints(r.cornerPoints);
+  if (cornerPoints) result.cornerPoints = cornerPoints;
+  return result;
+}
+
+/**
+ * 解析原生回传的 JSON 字符串 → 强类型 ScanResult[]。
+ * 任何脏数据都被安全过滤；解析失败返回空数组而非抛错。
+ */
+export function parseResultsJson(json: string): ScanResult[] {
+  if (!json) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const out: ScanResult[] = [];
+  for (const item of parsed) {
+    const r = coerceResult(item);
+    if (r) out.push(r);
+  }
+  return out;
+}

package/src/index.tsx

@@ -0,0 +1,35 @@
+// @unif/react-native-hms-scan —— 华为 HMS 统一扫码服务 RN bridge
+// 能力：定制视图扫码（底层 <HmsScanView> + 成品 <Scanner> 扫一扫页）+ 图片识别（decodeImage）。
+
+// ── 类型与常量 ──
+export {
+  ALL_BARCODE_FORMATS,
+  HmsScanError,
+} from './types';
+export type {
+  BarcodeFormat,
+  BarcodeContentType,
+  ScanCornerPoint,
+  ScanResult,
+  DecodeImageOptions,
+  CameraPermissionStatus,
+  HmsScanErrorCode,
+  ScanProduct,
+} from './types';
+
+// ── 码制工具 ──
+export { coerceFormat, coerceContentType, formatsToCsv } from './format';
+
+// ── 底层 headless 相机组件 ──
+export { HmsScanView } from './HmsScanView';
+export type { HmsScanViewProps, TorchStatus } from './HmsScanView';
+
+// ── 图片识别 ──
+export { decodeImage } from './decodeImage';
+
+// ── 相机权限 ──
+export { getCameraPermissionStatus, requestCameraPermission } from './permissions';
+
+// ── 成品扫一扫页（聚焦款，浅色） ──
+export { Scanner } from './Scanner/Scanner';
+export type { ScannerProps } from './Scanner/Scanner';

package/src/mock.ts

@@ -0,0 +1,43 @@
+// Jest mock for @unif/react-native-hms-scan —— 供消费者在测试中替换本库，
+// 避免 jest 环境加载 HmsScan TurboModule / HmsScanView Fabric 组件而崩溃。
+//
+// 用法（消费者 jest setup 或单个测试文件）：
+//
+//   jest.mock('@unif/react-native-hms-scan', () =>
+//     require('@unif/react-native-hms-scan/mock')
+//   );
+//
+// 替换后 decodeImage / 权限方法都是 jest.fn；<HmsScanView> / <Scanner> 渲染为 null。
+// 按需覆盖单次返回：
+//   (decodeImage as jest.Mock).mockResolvedValueOnce([{ value: '690...', format: 'EAN_13' }]);
+
+import type { FC } from 'react';
+import type {
+  CameraPermissionStatus,
+  DecodeImageOptions,
+  ScanResult,
+} from './types';
+import type { HmsScanViewProps } from './HmsScanView';
+import type { ScannerProps } from './Scanner/Scanner';
+
+// 纯 JS 类型 / 常量 / Error / 码制工具：保留真实实现（不碰原生）。
+export * from './types';
+export { coerceFormat, coerceContentType, formatsToCsv } from './format';
+
+// ── 图片识别 ──
+export const decodeImage = jest.fn(
+  (_uri: string, _options?: DecodeImageOptions): Promise<ScanResult[]> =>
+    Promise.resolve([])
+);
+
+// ── 相机权限 ──（默认已授权）
+export const getCameraPermissionStatus = jest.fn(
+  (): Promise<CameraPermissionStatus> => Promise.resolve('granted')
+);
+export const requestCameraPermission = jest.fn(
+  (): Promise<CameraPermissionStatus> => Promise.resolve('granted')
+);
+
+// ── 组件 ──（渲染 null，避免触碰原生）
+export const HmsScanView: FC<HmsScanViewProps> = () => null;
+export const Scanner: FC<ScannerProps> = () => null;

package/src/permissions.ts

@@ -0,0 +1,27 @@
+import NativeHmsScan from './NativeHmsScan';
+import type { CameraPermissionStatus } from './types';
+
+function normalize(status: string): CameraPermissionStatus {
+  switch (status) {
+    case 'granted':
+    case 'denied':
+    case 'blocked':
+    case 'undetermined':
+      return status;
+    default:
+      return 'undetermined';
+  }
+}
+
+/** 查询当前相机权限状态（不弹窗）。 */
+export async function getCameraPermissionStatus(): Promise<CameraPermissionStatus> {
+  return normalize(await NativeHmsScan.getCameraPermissionStatus());
+}
+
+/**
+ * 发起相机权限请求（必要时弹系统授权框），返回请求后的状态。
+ * 若用户已永久拒绝（blocked），需引导去系统设置开启。
+ */
+export async function requestCameraPermission(): Promise<CameraPermissionStatus> {
+  return normalize(await NativeHmsScan.requestCameraPermission());
+}