id-scanner-lib 1.0.0 → 1.2.0

package/README.md

@@ -37,6 +37,49 @@
 npm install id-scanner-lib
 ```
 
+## 优化引入方式
+
+本库支持多种引入方式，可根据实际需求选择最优方案，减小应用体积：
+
+### 完整引入
+```javascript
+// 引入完整包（包含全部功能）
+import { IDScanner } from 'id-scanner-lib';
+
+const scanner = new IDScanner({
+  onQRCodeScanned: (result) => console.log('扫描结果:', result),
+  onIDCardScanned: (info) => console.log('身份证信息:', info)
+});
+```
+
+### 按需引入
+```javascript
+// 只引入二维码相关功能，减小应用体积
+import { ScannerModule } from 'id-scanner-lib/qr';
+
+const qrScanner = new ScannerModule({
+  onQRCodeScanned: (result) => console.log('二维码:', result)
+});
+```
+
+```javascript
+// 只引入OCR身份证识别功能
+import { OCRModule } from 'id-scanner-lib/ocr';
+
+const ocrScanner = new OCRModule({
+  onIDCardScanned: (info) => console.log('身份证信息:', info)
+});
+```
+
+```javascript
+// 只引入轻量核心功能（无OCR）
+import { IDScannerCore } from 'id-scanner-lib/core';
+
+const coreScanner = new IDScannerCore({
+  onQRCodeScanned: (result) => console.log('扫描结果:', result)
+});
+```
+
 ## 快速开始
 
 ### 基本用法
@@ -234,6 +277,83 @@ const scanner = new IDScanner({
 
 3. **关闭不必要的扫描**：不使用时及时停止扫描，节省资源。
 
+## 高级性能优化
+
+为满足生产环境的高性能需求，库内部实现了多种先进的性能优化策略：
+
+### 1. Web Worker多线程处理
+
+OCR和图像处理等计算密集型任务被移至Web Worker线程中执行，避免阻塞主线程UI渲染。
+
+```javascript
+// 启用Worker线程处理
+const ocrProcessor = new OCRProcessor({
+  useWorker: true // 默认值，可以明确指定
+});
+
+// 初始化会在后台线程创建OCR处理能力
+await ocrProcessor.initialize();
+```
+
+### 2. 内存管理与资源自动释放
+
+实现了资源自动管理机制，防止内存泄漏，特别适合长时间运行的应用场景。
+
+```javascript
+// 所有核心类都实现了Disposable接口
+// 可以通过ResourceManager统一管理
+import { ResourceManager } from 'id-scanner-lib/core';
+
+const resourceManager = new ResourceManager();
+resourceManager.register('scanner', scanner, true); // 最后一个参数为是否自动释放
+
+// 资源会在不使用一段时间后自动释放
+// 也可以手动释放
+await resourceManager.dispose('scanner');
+```
+
+### 3. 图像预处理优化
+
+自动降低分析图像尺寸，在保持识别率的同时大幅提升处理速度。
+
+```javascript
+// 可以配置最大图像尺寸
+const ocrProcessor = new OCRProcessor({
+  maxImageDimension: 1000 // 设置图像处理的最大尺寸
+});
+
+// 内部图像处理会自动缩小过大的图像
+// ImageProcessor.downsampleForProcessing(imageData, maxDimension);
+```
+
+### 4. 节流处理
+
+对视频帧分析应用节流策略，避免过度计算，降低设备发热和电池消耗。
+
+```javascript
+// 设置检测间隔毫秒数
+const detector = new IDCardDetector({
+  detectionInterval: 300 // 默认200ms，可根据需要调整
+});
+```
+
+### 5. 识别结果缓存
+
+通过图像指纹技术，缓存识别结果，短时间内相同图像避免重复识别。
+
+```javascript
+// 启用结果缓存
+const ocrProcessor = new OCRProcessor({
+  enableCache: true, // 默认值，可明确指定
+  cacheSize: 50 // 缓存最近50个结果
+});
+
+// 清除缓存
+ocrProcessor.clearCache();
+```
+
+这些性能优化在默认配置下已经启用，可根据应用特定需求进行调整。在移动设备上，这些优化可以将处理速度提升3-5倍，同时显著降低电池消耗。
+
 ## 常见问题解答
 
 **Q: 为什么我在移动设备上无法访问摄像头？**
@@ -263,6 +383,59 @@ A: 库的大小约为1MB，主要是因为包含OCR引擎。可以考虑按需
 | 安卓WebView   | 60+                 | 需要应用授予相机权限        |
 | iOS WebView  | 11+                 | 需要用户主动点击激活相机     |
 
+## 体积优化与性能优化
+
+本库设计时考虑了多种使用场景和设备性能限制，提供了多种优化选项：
+
+### 包体积优化
+1. **按需引入模块**：基于ES模块可以实现tree-shaking，只引入需要的功能，如：
+   ```javascript
+   // 只需要二维码功能时，包体积减小约65%
+   import { ScannerModule } from 'id-scanner-lib/qr';
+   ```
+
+2. **延迟加载OCR引擎**：OCR引擎体积较大，默认采用延迟加载策略：
+   ```javascript
+   // OCR引擎只在实际使用身份证识别功能时才会加载
+   const scanner = new IDScanner();
+   
+   // 这一步不会加载OCR引擎
+   await scanner.startQRScanner(videoElement);
+   
+   // 只有在需要识别身份证时才会加载OCR引擎
+   await scanner.startIDCardScanner(videoElement);
+   ```
+
+3. **分包构建**：完整库约1MB，但按功能拆分后最小可达200KB：
+   - 核心包 (无OCR): 约200KB
+   - 二维码扫描: 约350KB
+   - OCR模块: 约650KB
+
+4. **CDN加载**：可以通过CDN加载以加快访问速度：
+   ```html
+   <!-- 完整版 -->
+   <script src="https://cdn.jsdelivr.net/npm/id-scanner-lib/dist/id-scanner.min.js"></script>
+   
+   <!-- 或仅加载核心功能 -->
+   <script src="https://cdn.jsdelivr.net/npm/id-scanner-lib/dist/id-scanner-core.min.js"></script>
+   ```
+
+5. **版本更新记录**：
+   - v1.0.0: 首次发布版本
+   - v1.1.0: 模块化重构，实现按需加载，大幅减小体积
+
+### 运行时性能
+1. **摄像头参数自动优化**：根据设备性能自动调整摄像头分辨率
+2. **OCR引擎缓存**：OCR引擎加载后会缓存，避免重复加载
+3. **资源释放**：不使用时自动释放内存资源
+4. **图像预处理**：针对不同光线条件优化识别准确率
+
+### 推荐做法
+- 在应用初始化阶段，先使用核心功能
+- 为OCR等重型功能设置单独的入口或交互按钮
+- 在用户可能需要OCR前预加载，但不立即初始化
+- 实现加载状态UI反馈，提升用户体验
+
 ## 开发与贡献
 
 ### 本地开发

package/dist/core.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file 轻量级扫描库核心
+ * @description 不包含OCR功能的轻量版，只提供二维码和条形码扫描功能
+ * @module IDScannerCore
+ * @version 1.0.0
+ * @license MIT
+ */
+import { QRScannerOptions } from './scanner/qr-scanner';
+import { BarcodeScannerOptions } from './scanner/barcode-scanner';
+import { CameraOptions } from './utils/camera';
+/**
+ * IDScannerCore配置选项
+ */
+export interface IDScannerCoreOptions {
+    cameraOptions?: CameraOptions;
+    qrScannerOptions?: QRScannerOptions;
+    barcodeScannerOptions?: BarcodeScannerOptions;
+    onQRCodeScanned?: (result: string) => void;
+    onBarcodeScanned?: (result: string) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * IDScannerCore 轻量级扫描类
+ *
+ * 提供二维码和条形码扫描功能，不包含OCR身份证识别功能
+ */
+export declare class IDScannerCore {
+    private options;
+    private qrScanner;
+    private barcodeScanner;
+    private camera;
+    private scanMode;
+    private videoElement;
+    /**
+     * 构造函数
+     * @param options 配置选项
+     */
+    constructor(options?: IDScannerCoreOptions);
+    /**
+     * 初始化扫描器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 启动二维码扫描
+     * @param videoElement HTML视频元素
+     */
+    startQRScanner(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * 启动条形码扫描
+     * @param videoElement HTML视频元素
+     */
+    startBarcodeScanner(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * 停止扫描
+     */
+    stop(): void;
+    /**
+     * 处理二维码扫描结果
+     */
+    private handleQRScan;
+    /**
+     * 处理条形码扫描结果
+     */
+    private handleBarcodeScan;
+    /**
+     * 处理错误
+     */
+    private handleError;
+    /**
+     * 释放资源
+     */
+    terminate(): Promise<void>;
+}
+export { QRScanner, QRScannerOptions } from './scanner/qr-scanner';
+export { BarcodeScanner, BarcodeScannerOptions } from './scanner/barcode-scanner';
+export { Camera, CameraOptions } from './utils/camera';
+export { ImageProcessor } from './utils/image-processing';

package/dist/id-recognition/data-extractor.d.ts

@@ -71,4 +71,35 @@ export declare class DataExtractor {
      * @returns {IDCardInfo} 增强后的身份证信息
      */
     static enhanceIDCardInfo(ocrInfo: IDCardInfo, idNumber?: string): IDCardInfo;
+    /**
+     * 提取并验证身份证信息
+     *
+     * @param idCardInfo 初步提取的身份证信息
+     * @returns 验证和增强后的身份证信息
+     */
+    extractAndValidate(idCardInfo: IDCardInfo): IDCardInfo;
+    /**
+     * 规范化身份证号码
+     */
+    private normalizeIDNumber;
+    /**
+     * 验证身份证号码是否有效
+     */
+    private validateIDNumber;
+    /**
+     * 从身份证号中提取出生日期
+     */
+    private extractBirthDateFromID;
+    /**
+     * 从身份证号中提取性别信息
+     */
+    private extractGenderFromID;
+    /**
+     * 规范化日期格式
+     */
+    private normalizeDate;
+    /**
+     * 规范化地址信息
+     */
+    private normalizeAddress;
 }

package/dist/id-recognition/id-detector.d.ts

@@ -3,7 +3,31 @@
  * @description 提供自动检测和定位图像中的身份证功能
  * @module IDCardDetector
  */
-import { DetectionResult } from '../utils/types';
+/**
+ * DetectionResult接口
+ *
+ * 包含身份证检测结果信息
+ */
+export interface DetectionResult {
+    success: boolean;
+    imageData?: ImageData;
+    boundingBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    confidence?: number;
+    message?: string;
+}
+/**
+ * IDCardDetector配置选项
+ */
+export interface IDCardDetectorOptions {
+    onDetection?: (result: DetectionResult) => void;
+    onError?: (error: Error) => void;
+    detectionInterval?: number;
+}
 /**
  * 身份证检测器类
  *