xdz-app/capability-qrcode/使用说明.md

二维码扫码功能使用说明

功能特点

• ✅ 使用华为 Customized View Mode 实现精美的自定义扫码界面
• ✅ 全屏沉浸式体验
• ✅ 流畅的扫描线动画
• ✅ 超简洁的 API，业务层只需一行代码
• ✅ 内部自动处理 Activity Result，无需手动处理 onActivityResult
• ✅ 单例模式，统一管理

快速开始

调用方式（与BLE模块完全一致）

import com.narutohuo.xindazhou.qrcode.factory.QRCodeManagerFactory
import com.narutohuo.xindazhou.qrcode.api.QRCodeManager

val qrCodeManager: QRCodeManager = QRCodeManagerFactory.getInstance()
qrCodeManager.scanQRCode(this) { response ->
    if (response.success) {
        // 扫码成功
        val qrCodeContent = response.data
    } else {
        // 扫码失败或取消
        val error = response.errorMessage
    }
}

完整示例

import com.narutohuo.xindazhou.qrcode.factory.QRCodeManagerFactory
import com.narutohuo.xindazhou.qrcode.api.QRCodeManager
import com.narutohuo.xindazhou.qrcode.model.QRCodeResponse

class MainActivity : AppCompatActivity() {
    
    private val qrCodeManager: QRCodeManager = QRCodeManagerFactory.getInstance()
    
    fun startScan() {
        qrCodeManager.scanQRCode(this) { response ->
            handleScanResult(response)
        }
    }
    
    private fun handleScanResult(response: QRCodeResponse) {
        if (response.success) {
            val content = response.data
            // 处理扫码结果
            processQRCode(content)
        } else {
            // 处理错误
            showError(response.errorMessage)
        }
    }
    
    private fun processQRCode(content: String?) {
        // 业务逻辑处理
    }
    
    private fun showError(message: String?) {
        // 显示错误
    }
}

注意：✅ 不需要实现 onActivityResult！内部已经自动处理了

API 说明

QRCodeManager 接口

interface QRCodeManager {
    /**
     * 扫描二维码
     * 
     * @param activity Activity上下文（必须是 FragmentActivity 或 AppCompatActivity）
     * @param callback 扫描结果回调，返回QRCodeResponse
     */
    fun scanQRCode(activity: Activity, callback: (QRCodeResponse) -> Unit)
}

QRCodeResponse 响应模型

data class QRCodeResponse(
    val success: Boolean,           // 是否成功
    val data: String? = null,       // 二维码内容
    val errorCode: Int? = null,     // 错误码
    val errorMessage: String? = null, // 错误消息
    val timestamp: Long = System.currentTimeMillis() // 时间戳
)

注意事项

1. Activity 类型：必须使用 AppCompatActivity 或 FragmentActivity（内部使用 Fragment 桥接 ActivityResultLauncher）
2. 相机权限：确保在 AndroidManifest.xml 中声明了相机权限，运行时会自动请求
3. 单例模式：使用 Factory 获取的实例是单例，多个界面可以共享
4. 无需处理 onActivityResult：内部已经自动处理，业务层完全不需要关心

界面效果

• 全屏沉浸式扫码界面
• 居中显示扫码框（280dp × 280dp）
• 四个角的装饰线条（青色 #00E5FF）
• 流畅的扫描线动画
• 半透明遮罩突出扫码区域
• 顶部返回按钮
• 底部提示文字

依赖说明

• 华为 HMS Scan Kit: 2.12.0.300
• AndroidX AppCompat: 1.6.1
• AndroidX Fragment: 1.6.2
• AndroidX Activity: 1.8.2
• 最低 SDK 版本: 26

与其他模块对比

BLE 模块调用方式

import com.narutohuo.xindazhou.ble.factory.BLEServiceFactory
import com.narutohuo.xindazhou.ble.api.BLEService

val bleService: BLEService = BLEServiceFactory.create(context)
bleService.connect(device) { response ->
    // 处理结果
}

二维码模块调用方式（完全一致！）

import com.narutohuo.xindazhou.qrcode.factory.QRCodeManagerFactory
import com.narutohuo.xindazhou.qrcode.api.QRCodeManager

val qrCodeManager: QRCodeManager = QRCodeManagerFactory.getInstance()
qrCodeManager.scanQRCode(this) { response ->
    // 处理结果
}

与BLE模块完全一致的调用方式！ 🎉