xdz-ios/CapabilityQRCode/使用说明.md

二维码扫码功能使用说明（iOS）

功能特点

• ✅ 使用华为 Scan Kit 实现二维码扫描功能
• ✅ 自动处理相机权限
• ✅ 全屏沉浸式体验
• ✅ 支持二维码生成和图片识别
• ✅ 超简洁的 API，业务层只需一行代码
• ✅ 单例模式，统一管理

快速开始

调用方式

import CapabilityQRCode

let qrCodeService = QRCodeServiceFactory.getInstance()
qrCodeService.scanQRCode(viewController: self) { response in
    if response.success {
        // 扫码成功
        let qrCodeContent = response.data
        print("扫码结果: \(qrCodeContent ?? "")")
    } else {
        // 扫码失败或取消
        let error = response.errorMessage
        print("扫码失败: \(error ?? "")")
    }
}

完整示例

import UIKit
import CapabilityQRCode

class ViewController: UIViewController {
    
    private let qrCodeService = QRCodeServiceFactory.getInstance()
    
    @IBAction func scanButtonTapped(_ sender: UIButton) {
        qrCodeService.scanQRCode(viewController: self) { response in
            self.handleScanResult(response)
        }
    }
    
    private func handleScanResult(_ response: QRCodeResponse) {
        if response.success {
            guard let content = response.data else { return }
            // 处理扫码结果
            processQRCode(content)
        } else {
            // 处理错误
            showError(response.errorMessage)
        }
    }
    
    private func processQRCode(_ content: String) {
        // 业务逻辑处理
        print("二维码内容: \(content)")
    }
    
    private func showError(_ message: String?) {
        let alert = UIAlertController(
            title: "扫码失败",
            message: message ?? "未知错误",
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "确定", style: .default))
        present(alert, animated: true)
    }
}

API 说明

QRCodeService 接口

public protocol QRCodeService {
    /// 生成二维码
    func generateQRCode(content: String, size: CGFloat) -> UIImage?
    
    /// 扫描二维码
    func scanQRCode(viewController: UIViewController, callback: @escaping (QRCodeResponse) -> Void)
    
    /// 识别图片中的二维码
    func recognizeQRCode(image: UIImage, callback: @escaping (QRCodeResponse) -> Void)
}

QRCodeResponse 响应模型

public struct QRCodeResponse {
    public let success: Bool          // 是否成功
    public let data: String?          // 二维码内容
    public let errorCode: Int?        // 错误码
    public let errorMessage: String?  // 错误消息
    public let timestamp: Int64       // 时间戳
}

集成华为 Scan Kit

前置条件

1. 在项目中集成华为 Scan Kit Framework

   • 将 ScanKitFrameWork.framework 和 ScanKitFrameWorkBundle.bundle 添加到项目
   • 在 Build Phases > Link Binary With Libraries 中添加框架
   • 在 Build Settings > Framework Search Paths 中添加框架路径

2. 配置 Info.plist

   • 添加相机权限说明：NSCameraUsageDescription

权限配置

在 Info.plist 中添加：

<key>NSCameraUsageDescription</key>
<string>需要相机权限来扫描二维码</string>

注意事项

1. 华为 Scan Kit Framework：如果项目中没有集成华为 Scan Kit Framework，代码会自动降级使用系统原生 AVFoundation 实现

2. 权限处理：扫码功能会自动请求相机权限，如果用户拒绝权限，会返回相应的错误信息

3. 线程安全：所有回调都在主线程执行，可以直接更新 UI

4. 单例模式：QRCodeService 是单例，多个界面可以共享同一个服务实例

降级方案

如果没有集成华为 Scan Kit Framework，代码会自动使用系统原生 AVFoundation 实现扫码功能，确保功能可用。

参考文档

• 华为 Scan Kit iOS 开发指南