# scan_util_project

**Repository Path**: Fie_Ryan/scan_util_project

## Basic Information

- **Project Name**: scan_util_project
- **Description**: 基于 @kit.ScanKit 封装的一站式扫码解决方案，支持摄像头实时扫码、图片识码、自定义扫码界面等功能，提供统一的结果处理和错误反馈机制。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-04
- **Last Updated**: 2025-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 鸿蒙, 自定义扫码, 相机扫码, 码图识别

## README

# 扫码工具类

## 介绍
扫码组件是基于 @kit.ScanKit 封装的一站式扫码解决方案，支持摄像头实时扫码、图片识码、自定义扫码界面等功能，提供统一的结果处理和错误反馈机制。扫码管理工具类均采用单例模式实现,确保在项目中永远只有一个实例.

## 统一的返回结果
```extendtypescript
export interface IScanResult {
  // 扫码结果
  state: ScanResultStateType;
  // 扫码结果数据
  result?: Array<scanBarcode.ScanResult> | scanBarcode.ScanResult
}
```

## 功能特性
- 1.支持摄像头实时扫码与图片上传识码
- 2.提供默认扫码界面，同时支持完全自定义扫码 UI
- 3.支持多种条码类型识别（二维码、条形码等）
- 4.统一的结果格式化与状态管理
- 5.完善的错误处理与日志记录
- 6.支持闪光灯控制等辅助功能

## 使用及安装, 更多使用案例前往 [扫码工具仓库](https://gitee.com/Fie_Ryan/scan_util_project) 查看
### 1.需要 ohos.permission.CAMERA 权限, 申请权限如下:
```json5
{
  "name": "ohos.permission.CAMERA",
  "reason": "$string:location_permission",
}
```
### 2.使用 ohpm 下载安装依赖
```typescript
 ohpm install @ryan/scan_util
```
### 3.在Abillity 的 onWindowStageCreate 方法中初始化
```extendtypescript
onWindowStageCreate(windowStage: window.WindowStage): void {
  try {
    windowStage.getMainWindow().then((windowObj: window.Window) => {
      windowStage.loadContent('pages/Index', (err) => {
        if (err.code) {
          return;
        }
        // 初始化
        UIContextSelf.setUIContext(windowObj);
      });
    })
  } catch (e) {
    hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the catch.');
  }
}
```
### 4.以自定义扫码组件为例,说明使用过程
```extendtypescript
import { CustomScanComponent, IScanResult } from '@ryan/scan_util';
import { Subscriber } from '@ryan/eventbus'
import { router } from '@kit.ArkUI';

@Entry
@Component
struct CustomPage {
  // 开启/关闭闪光灯
  @State isFlashLightEnable: boolean = false
  private options: CustomScanComponent.CustomScanComponentOption = new CustomScanComponent.CustomScanComponentOption()
  aboutToAppear(): void {
    this.options.cancelEventName = "CLOSE_CUSTOME_SCAN"
    this.options.successCallback = () => {
      router.back()
    }
    this.options.listener = {
      result: (result: IScanResult) => {
        AlertDialog.show({
          message: JSON.stringify(result)
        })
      },
      changeFlashLight: (state: boolean) => {
        this.isFlashLightEnable = state
      }
    }
  }

  @Subscriber("CLOSE_CUSTOME_SCAN")
  close() {
    router.back()
  }

  build() {
    Column() {
      CustomScanComponent({
        options: this.options,
        isFlashLightEnable: this.isFlashLightEnable
      })
    }
    .width("100%")
    .height("100%")
  }
}
```

## 主要工具类
### DefaultScanManage 默认扫码工具类
- 提供 **startScanForResult(params?: IScanForResultParams): Promise<IScanResult>** 方法直接调用
```typescript
const result: IScanResult = await DefaultScanManage.startScanForResult({ context: getContext(this) })
AlertDialog.show({
  message: JSON.stringify(result)
})
```
### CustomScanManage 自定义扫码工具类
- 外部调用的方法
```extendtypescript
class CustomScanManage {
  // 以下为外部调用主要方法
  /**
   * 初始化自定义扫码函数
   * @param options?: scanBarcode.ScanOptions,
   *    scanTypes 设置扫码类型，默认扫码ALL（全部码类型）。
   *    enableMultiMode 是否开启多码识别，默认false。true：多码识别、false：单码识别。
   *    enableAlbum 是否开启相册，默认true。true-开启相册扫码、false-关闭相册扫码。
   * @param resultCallback 扫码成功回调函数
   * @param errorCallback 扫码失败回调函数
   */
  public async initiateCustomScanManage(params?: ICustomeScanParam): Promise<void>;

  /**
   * 调起自定义扫码功能
   * @param surfaceId
   * @returns
   */
  public async startCustomScan(surfaceId: string): Promise<IScanResult>;

  /**
   * 停止相机流
   * @returns
   */
  public async customScanStop(): Promise<void> ;

  /**
   * 释放扫码相机流
   */
  public async customScanRelease(): Promise<void> ;

  /**
   * 销毁扫码工具，清理资源
   */
  public async destroy(): Promise<void>;

  /**
   * 根据传入的参数判断当前设备是否支持码能力
   * @returns
   */
  public canIUseScan(scanFlag: string): boolean;
}
```
- 使用示例
```extendtypescript
// 通过复制可以手动开启闪光灯功能
CustomScanManage.isFlashLightEnable = !this.isFlashLightEnable
// 传入 XComponentController 的 surfaceId即可开启扫码功能
CustomScanManage.startCustomScan(this.surfaceId)
```
### DetectBarcodeManage 图像识码工具类
```extendtypescript
class DetectBarcodeManage {
  /**
   * 初始化图像识码管理器
   * @param params 初始化参数，包含监听器等配置
   */
  public initiateDetectBarcodeManage(params: IDetectBarcodeParam) ;

  /**
   * 根据图片URL进行图像识码
   * @param url 图片的URL地址
   * @param params 识码配置选项，可选
   * @param listener 识码结果监听器，可选
   * @returns 识码结果数组
   * @throws {Error} 当识码过程中发生错误时抛出
   */
  public async decode(url: string, params?: ScanOptionConfig, listener?: DetectBarcodeAPIListener): Promise<IScanResult> ;

  /**
   * 重置管理器状态
   */
  public reset(): void ;
}
```
### PhotoPickerUtils 相册图片选择工具类
```extendtypescript
/**
 * 相册选择工具类
 */
export class PhotoPickerUtils {
  /**
   * 选择相册中的图片
   * @param params 相册选择参数，可选
   * @returns 选中图片的URI数组
   * @throws {BusinessError} 当选择过程中发生错误时抛出
   */
  static async select(params?: IPhotoPickerOptions,): Promise<Array<string>> ;
}
```

## 其他使用流程可以前往 [扫码工具仓库](https://gitee.com/Fie_Ryan/scan_util_project)  查看

## [鸿蒙相关工具仓库首页](https://gitee.com/Fie_Ryan)
```typescript
https://gitee.com/Fie_Ryan
```