HarmonyOS Scan Kit（统一扫码服务）概述与开发准备

前言

在万物互联的智能终端时代，扫码功能早已超越了简单的信息读取，演变为连接物理世界与数字服务的核心枢纽。无论是支付转账、自助点餐、设备绑定还是扫码登录，扫码都是用户最频繁使用的交互方式之一。HarmonyOS 作为面向全场景的分布式操作系统，提供了 Scan Kit（统一扫码服务）——一套软硬协同的系统级扫码解决方案，帮助开发者快速构建精准、高效的码图识别与生成能力。

本文将作为 Scan Kit 系列教程的开篇，系统性地介绍 Scan Kit 的核心概念、能力架构、支持的码制式、使用场景以及开发前的准备工作，为后续深入学习打下坚实基础。

提示：Scan Kit 是 HarmonyOS 系统级能力，无需额外集成第三方 SDK，包体 0 增加，一行代码即可接入扫码功能。

一、Scan Kit 核心概念

1.1 什么是 Scan Kit

Scan Kit（统一扫码服务） 是华为软硬协同的系统级扫码服务，帮助开发者的应用快速构建面向各种场景的码图识别和生成能力，以及扫码直达能力。Scan Kit 应用了多项计算机视觉技术和AI算法技术，不仅实现了远距离自动扫码，同时还针对多种复杂扫码场景（如暗光、污损、模糊、小角度、曲面码等）做了识别优化，提升扫码成功率与用户体验。

Scan Kit 的核心设计理念是系统级能力开放，即开发者无需在应用中集成庞大的扫码 SDK，而是直接调用系统提供的扫码接口，享受系统级别的性能优化和权限管理。

1.2 Scan Kit 的核心优势

Scan Kit 相比传统第三方扫码库，具备以下核心优势：

  • 一行代码，接入简单：系统级接口，包体 0 增加，无需额外集成 SDK
  • 系统相机权限预授权：默认界面扫码无需开发者再次申请相机权限，保护用户信息安全
  • 多项 CV 技术加持：应用计算机视觉技术，提升扫码成功率和速度
  • 端侧 AI 算法：实现远距离识码，复杂场景下依然保持高识别率
  • 扫码直达能力：用户可通过控制中心等系统级入口一键扫码，直达应用服务页面

1.3 能力体系架构

Scan Kit 的能力体系可以划分为以下四个层级：

层级 能力名称 说明 适用场景
系统级分发层 扫码直达 系统识别码值后通过 App Linking 直接跳转应用服务页 浅层入口、一步直达
标准化交互层 默认界面扫码 系统提供全套扫码 UI，包含相机预览、闪光灯、相册入口 通用扫码场景
深度定制层 自定义界面扫码 完全控制相机流和扫码引擎，自定义 UI 交互 个性化扫码界面
图像解析与生成层 图像识码 + 码图生成 图库图片识别、相机预览流识别、文本/字节数组生成码图 内容加工场景

推荐接入顺序：优先接入"扫码直达"能力，再根据业务需求选择默认界面扫码或自定义界面扫码，最后按需集成图像识码和码图生成能力。

在这里插入图片描述

Scan Kit 四层能力体系架构：从系统级分发层到图像解析与生成层，覆盖全场景扫码需求

二、支持的码制式

2.1 13种全球主流码制式

Scan Kit 支持 13种全球主流码制式 的识别与生成，以及 MULTIFUNCTIONAL CODE 的识别：

序号 码制式类型 码类型 分类 典型应用场景
1 QR Code 二维码 矩阵式 支付、分享、登录
2 Data Matrix 二维码 矩阵式 工业标识、医疗器械
3 PDF417 二维码 堆叠式 证件、登机牌
4 Aztec 二维码 矩阵式 交通票务
5 EAN-8 条形码 一维码 商品零售
6 EAN-13 条形码 一维码 国际商品编码
7 UPC-A 条形码 一维码 北美商品编码
8 UPC-E 条形码 一维码 小型商品包装
9 Codabar 条形码 一维码 图书馆、血库
10 Code 39 条形码 一维码 工业、物流
11 Code 93 条形码 一维码 物流、仓储
12 Code 128 条形码 一维码 物流、供应链
13 ITF-14 条形码 一维码 货运包装箱

在这里插入图片描述

Scan Kit 支持 QR Code、Data Matrix、PDF417、Aztec 等13种全球主流码制式的识别与生成

2.2 码制式使用建议

针对不同业务场景，选择合适的码制式：

  1. 支付场景：推荐使用 QR Code，支持纠错等级配置，容错率高达 30%
  2. 商品零售：推荐使用 EAN-13 或 UPC-A，符合国际商品编码标准
  3. 物流追踪：推荐使用 Code 128，支持全 ASCII 字符集编码
  4. 工业制造：推荐使用 Data Matrix，小尺寸高密度编码
  5. 证件识别：推荐使用 PDF417，支持大容量数据编码

三、使用场景

3.1 六大典型业务场景

Scan Kit 覆盖了以下六大典型业务场景：

场景 描述 示例应用
支付转账 生成付款码/收款码，扫码付款、转账 银行 App、购物 App
自助服务 点餐、骑车、充电等 O2O 商业模式 美团、哈啰、怪兽充电
用户拉新 生成名片、课程、商品等邀请卡 社交 App、教育 App
验证登录 电脑、手表、显示器等设备扫码登录 微信、企业微信
设备绑定 扫码绑定摄像头、投影仪、车机等 智能家居 App
扫码查物 扫描商品条形码/二维码查询信息 电商 App、信息查询 App

3.2 合作案例

Scan Kit 已在多个头部应用中落地：

  • 美团单车：实现"一步开锁骑行"，用户通过控制中心扫一扫即可快速开锁，缩短操作路径
  • 丰巢：升级取件体验，用户下拉控制中心轻松一扫即可快速取件
  • 企业微信：高效办公交互，识别精准迅速，一扫直达

四、功能使用限制

4.1 各能力限制条件

在使用 Scan Kit 各能力时，需要注意以下限制条件：

能力 限制条件
扫码直达 仅支持 HTTPS 架构的网页链接接入；仅支持中国境内使用（港澳台除外）
默认界面扫码 相册扫码只支持单码识别；不支持界面 UX 添加自定义设置
自定义界面扫码 需要授权相机权限；需要开发者自行实现扫码的人机交互界面
码图生成 对生成参数有范围限制（宽高 200-4096px）；字节数组仅支持 QR Code
图像识码 需通过 PhotoViewPicker 获取图片路径；图像数据仅支持 NV21 格式

4.2 支持的设备

能力 支持设备
扫码直达 Phone、Tablet
默认界面扫码 Phone、Tablet、Wearable（API 23+，需后置相机）
自定义界面扫码 Phone、Tablet、Wearable（API 23+，需后置相机）
图像识码 Phone、Tablet、Wearable（API 23+）
码图生成 Phone、Tablet、Wearable、PC/2in1、TV

五、开发准备

5.1 基础准备工作

在开始使用 Scan Kit 之前，需要完成以下基础准备工作：

  1. 参考 应用开发准备 完成基本开发环境搭建
  2. 安装 DevEco Studio 最新版本，配置 HarmonyOS SDK
  3. 创建或导入 HarmonyOS 项目，使用 Stage 模型
  4. 确保项目 API 版本满足 Scan Kit 要求（最低 API 11）

5.2 扫码直达专用准备

如果计划接入扫码直达能力，还需要额外完成以下步骤：

  1. 在 AppGallery Connect 控制台开通 App Linking 服务
  2. 在开发者网站上关联应用
  3. 在 App Linking 中配置二维码、条形码关联的网址域名
  4. 在应用的 module.json5 文件中关联域名

重要提示：接入 App Linking 不能使用 DevEco Studio 的自动签名功能，必须使用手动签名。App Linking 方式当前仅支持 HTTPS 网址，具备应用和网页两种呈现方式。

5.3 模块导入

Scan Kit 各功能模块的导入方式如下：

// 导入扫码核心模块（包含 ScanType 枚举、ScanResult 等）
import { scanCore } from '@kit.ScanKit';

// 导入默认界面扫码模块
import { scanBarcode } from '@kit.ScanKit';

// 导入自定义界面扫码模块
import { customScan } from '@kit.ScanKit';

// 导入图像识码模块
import { detectBarcode } from '@kit.ScanKit';

// 导入码图生成模块
import { generateBarcode } from '@kit.ScanKit';

5.4 权限配置

不同扫码能力对权限的要求不同：

// module.json5 中的权限配置示例
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:camera_permission_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

默认界面扫码无需在 module.json5 中申请相机权限，系统已预授权。自定义界面扫码则需要申请相机权限。

六、示例工程参考

6.1 官方示例工程

华为官方提供了完整的 Scan Kit 示例工程，建议开发者基于示例工程进行个性化修改：

6.2 示例工程结构

官方示例工程涵盖了以下功能模块的完整实现：

// 示例工程主要模块结构
// 1. 默认界面扫码示例
//    - Promise 方式调用
//    - Callback 方式调用
//    - ScanOptions 参数配置
// 2. 自定义界面扫码示例
//    - 相机流初始化
//    - 自定义 UI 渲染
//    - 闪光灯/变焦控制
// 3. 图像识码示例
//    - 本地图片识别
//    - 图像数据识别
// 4. 码图生成示例
//    - 文本生成码图
//    - 字节数组生成码图
//    - 带 Logo 的二维码生成

七、快速上手：第一个扫码应用

7.1 默认界面扫码示例

以下是最简单的默认界面扫码实现，一行代码即可完成扫码功能：

import { scanBarcode, scanCore } from '@kit.ScanKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'ScanDemo';

@Entry
@Component
struct ScanPage {
  build() {
    Column() {
      Button('开始扫码')
        .backgroundColor($r('sys.color.ohos_id_color_button_normal'))
        .fontColor($r('sys.color.ohos_id_color_text_primary_activated'))
        .type(ButtonType.Capsule)
        .width('90%')
        .margin({ top: 20 })
        .onClick(() => {
          // 获取当前上下文
          const context: common.Context = getContext(this);

          // 配置扫码参数
          const options: scanBarcode.ScanOptions = {
            scanTypes: [scanCore.ScanType.QR_CODE, scanCore.ScanType.EAN_13],
            enableMultiMode: true,
            enableAlbum: true
          };

          // 启动默认界面扫码
          scanBarcode.startScanForResult(context, options)
            .then((result: scanBarcode.ScanResult) => {
              hilog.info(0x0001, TAG,
                `扫码成功，码值: ${result.originalValue}, 码类型: ${result.scanType}`);
              // 处理扫码结果
              this.handleScanResult(result);
            })
            .catch((err: BusinessError) => {
              if (err.code === 10005001) {
                hilog.info(0x0001, TAG, '用户取消扫码');
              } else {
                hilog.error(0x0001, TAG,
                  `扫码失败，错误码: ${err.code}, 错误信息: ${err.message}`);
              }
            });
        })

      Text('点击按钮启动系统扫码界面')
        .fontSize(14)
        .fontColor($r('sys.color.ohos_id_color_text_secondary'))
        .margin({ top: 16 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  private handleScanResult(result: scanBarcode.ScanResult): void {
    // 根据扫码结果进行业务处理
    AlertDialog.show({
      title: '扫码结果',
      message: `码值: ${result.originalValue}\n码类型: ${result.scanType}`,
      confirm: {
        value: '确定',
        action: () => { }
      }
    });
  }
}

7.2 封装通用扫码服务

在实际项目中，建议将扫码功能封装为通用服务类：

import { scanBarcode, scanCore } from '@kit.ScanKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export class ScanService {
  /**
   * 启动通用扫码（默认界面）
   * @param context 上下文
   * @param scanTypes 指定码制式，不传则识别所有类型
   * @returns 扫码结果字符串，取消返回 'USER_CANCEL'
   */
  static async startQuickScan(
    context: common.Context,
    scanTypes?: scanCore.ScanType[]
  ): Promise<string> {
    const options: scanBarcode.ScanOptions = {
      scanTypes: scanTypes || [scanCore.ScanType.ALL],
      enableMultiMode: true,
      enableAlbum: true
    };

    try {
      const result: scanBarcode.ScanResult =
        await scanBarcode.startScanForResult(context, options);
      return result.originalValue || '';
    } catch (error) {
      const err = error as BusinessError;
      if (err.code === 10005001) {
        return 'USER_CANCEL';
      }
      throw new Error(`扫码失败: ${err.message}`);
    }
  }

  /**
   * 启动仅识别二维码的扫码
   */
  static async scanQRCode(context: common.Context): Promise<string> {
    return this.startQuickScan(context, [scanCore.ScanType.QR_CODE]);
  }

  /**
   * 启动仅识别条形码的扫码
   */
  static async scanBarcode(context: common.Context): Promise<string> {
    return this.startQuickScan(context, [
      scanCore.ScanType.EAN_8,
      scanCore.ScanType.EAN_13,
      scanCore.ScanType.CODE_128,
      scanCore.ScanType.CODE_39
    ]);
  }
}

7.3 在页面中使用封装后的服务

import { ScanService } from '../services/ScanService';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct PaymentPage {
  @State scanResult: string = '';

  build() {
    Column() {
      Button('扫码支付')
        .onClick(async () => {
          try {
            const context: common.Context = getContext(this);
            const result = await ScanService.scanQRCode(context);
            if (result !== 'USER_CANCEL') {
              this.scanResult = result;
              // 根据扫码结果跳转支付页面
              this.navigateToPayment(result);
            }
          } catch (err) {
            const error = err as BusinessError;
            AlertDialog.show({
              title: '扫码异常',
              message: error.message,
              confirm: { value: '确定', action: () => { } }
            });
          }
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }

  private navigateToPayment(result: string): void {
    // 处理扫码结果，跳转支付页面
    console.info(`准备支付，码值: ${result}`);
  }
}

八、Scan Kit 与其他方案的对比

8.1 与第三方扫码库对比

对比维度 Scan Kit（系统级） ZXing（开源） Google ML Kit 微信扫码 SDK
接入方式 系统 API，无需集成 需集成 AAR/HAR 需集成 SDK 需集成 SDK
包体大小 0 增加 约 2-3MB 约 8-15MB 约 5-10MB
相机权限 预授权（默认界面） 需申请 需申请 需申请
码制式支持 13种 10+种 12种 10+种
远距离扫码 支持（AI 算法） 不支持 部分支持 不支持
复杂场景优化 暗光/污损/曲面 基础 部分 基础
扫码直达 支持 不支持 不支持 不支持
维护成本 系统自动更新 需手动更新 需手动更新 需手动更新

8.2 与 Android/iOS 扫码方案对比

特性 HarmonyOS Scan Kit Android CameraX + ML Kit iOS AVFoundation
二维码生成 generateBarcode ZXing / ML Kit CIFilter
二维码识别 scanBarcode / customScan ML Kit / ZXing AVCaptureMetaDataOutput
图像识码 detectBarcode ML Kit Bitmap CIDetector
扫码直达 App Linking App Links / Universal Links Universal Links
引擎接入 统一 Kit 入口 各库独立接入 各框架独立接入

九、接口能力全景图

9.1 Scan Kit 接口总览

模块 接口名 功能描述 返回形式
scanBarcode startScanForResult 启动默认界面扫码 Promise / Callback
customScan init 初始化自定义扫码引擎 Promise
customScan start 启动自定义扫码 Promise / Callback
customScan stop 暂停扫码 void
customScan release 释放扫码资源 Promise
customScan getFlashLightStatus 获取闪光灯状态 Promise / Callback
customScan openFlashLight 打开闪光灯 Promise / Callback
customScan closeFlashLight 关闭闪光灯 Promise / Callback
customScan setZoom 设置变焦比 Promise / Callback
customScan getZoom 获取变焦比 Promise / Callback
customScan setFocusPoint 设置对焦位置 Promise / Callback
customScan resetFocus 恢复默认对焦模式 Promise / Callback
customScan rescan 重新触发扫码 Promise / Callback
detectBarcode decode 识别本地图片中的码图 Promise / Callback
detectBarcode decodeImage 识别图像数据中的码图 Promise
generateBarcode createBarcode 文本/字节数组生成码图 Promise / Callback

9.2 核心数据结构

// ScanOptions - 扫码参数配置
interface ScanOptions {
  scanTypes?: scanCore.ScanType[];  // 指定扫码类型
  enableMultiMode?: boolean;        // 是否开启多码模式
  enableAlbum?: boolean;            // 是否显示相册入口
}

// ScanResult - 扫码结果
interface ScanResult {
  originalValue: string;   // 码图原始值
  scanType: scanCore.ScanType;  // 码图类型
  codeFormat?: string;     // 码图格式
}

// CreateOptions - 码图生成参数
interface CreateOptions {
  scanType: scanCore.ScanType;     // 码图类型
  width: number;                   // 码图宽度（px）
  height: number;                  // 码图高度（px）
  margin?: number;                 // 最小边距（px）
  level?: ErrorCorrectionLevel;    // 纠错水平
  backgroundColor?: number;        // 背景颜色（HEX）
  pixelMapColor?: number;          // 码图颜色（HEX）
}

十、常见问题与注意事项

10.1 开发中常见问题

以下是在使用 Scan Kit 开发过程中常见的几个问题及解决方案：

  1. 默认界面扫码取消处理：错误码 10005001 表示用户取消扫码，属于正常业务逻辑，不应作为错误处理
  2. 自定义界面扫码权限：必须在 module.json5 中声明 ohos.permission.CAMERA 权限，并在运行时动态申请
  3. 码图生成尺寸限制：宽高必须在 [200, 4096] 范围内，否则会抛出参数非法错误
  4. 字节数组生成码图：仅支持 QR Code 类型，且 width 必须等于 height
  5. 扫码直达签名：不能使用 DevEco Studio 自动签名，必须使用手动签名

10.2 设备兼容性检查工具

在实际开发中，建议封装一个设备兼容性检查工具：

import { scanCore } from '@kit.ScanKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[DeviceCapability]';

/**
 * 设备扫码能力检查工具
 */
export class DeviceCapabilityChecker {
  /**
   * 检查设备是否支持默认界面扫码
   */
  static isDefaultScanSupported(): boolean {
    try {
      if (typeof scanCore.isDefaultScanSupported === 'function') {
        return scanCore.isDefaultScanSupported();
      }
      return true; // 低版本默认支持
    } catch (err) {
      hilog.warn(0x0001, TAG,
        `isDefaultScanSupported check failed: ${JSON.stringify(err)}`);
      return false;
    }
  }

  /**
   * 检查设备是否支持自定义界面扫码
   */
  static isCustomScanSupported(): boolean {
    try {
      if (typeof scanCore.isCustomScanSupported === 'function') {
        return scanCore.isCustomScanSupported();
      }
      return true;
    } catch (err) {
      hilog.warn(0x0001, TAG,
        `isCustomScanSupported check failed: ${JSON.stringify(err)}`);
      return false;
    }
  }

  /**
   * 获取设备完整的扫码能力报告
   */
  static getCapabilityReport(): Record<string, boolean> {
    return {
      defaultScan: this.isDefaultScanSupported(),
      customScan: this.isCustomScanSupported(),
      generateBarcode: true,
      detectBarcode: true
    };
  }
}

10.3 最佳实践建议

  • 优先接入扫码直达：通过少量工作即可实现系统级扫码入口，一步直达应用服务页
  • 默认界面优先：通用扫码场景优先使用默认界面扫码，无需 UI 开发，体验与系统一致
  • 按需自定义：仅在需要个性化 UI 时使用自定义界面扫码
  • 参考示例工程：基于 官方示例工程 进行个性化修改
  • 关注 API 版本更新：不同 API 版本功能有所不同，详见 Scan Kit 开发指南

总结

本文作为 Scan Kit 系列教程的开篇，系统性地介绍了 Scan Kit 的核心概念、能力架构、支持的 13 种码制式、六大典型业务场景以及开发前的准备工作。通过本文的学习，你应该已经对 Scan Kit 有了全面的认识，并能够搭建基础的开发环境。

Scan Kit 作为 HarmonyOS 系统级的扫码服务，通过一行代码、零包体增加的方式，帮助开发者快速构建高质量的扫码功能。其核心优势在于系统级权限预授权、AI 算法加持的复杂场景识别优化，以及创新的扫码直达能力。

在后续的文章中，我们将逐一深入讲解扫码直达服务、默认界面扫码、自定义界面扫码、图像识码和码图生成的详细开发流程。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

# harmonyos # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

HarmonyOS 鸿蒙 Subject Sticker 主体抠图贴纸实战 —— AI 分割、像素白边与五轮真机排雷

avatar HarmonyOS开发者社区
cover

HarmonyOS 鸿蒙 ArkUI 保留属性名踩坑实录 —— 那些「看起来能命名、一编译就报错」的 @Prop

avatar HarmonyOS开发者社区
cover

HarmonyOS 鸿蒙 CollectibleBookshelf 原生 3D 书架实战 —— 不用 WebGL，一个 rotateY 逼出来的投影布局法

avatar HarmonyOS开发者社区