更新记录

1.0.0（2026-09-18）

UTS 原生扫码：全屏取景、多二维码点击选择、双指/滑块变焦、手电筒

平台兼容性

uni-app(5.01)

其他

stq-scanner（UTS 全屏扫码插件）

UTS 原生扫码插件：全屏取景扫码；检测到多个二维码时定格当前画面并停止识别（微信式），绿角框 + 码中心实心箭头标注，用户点击选择其一返回；双指捏合/滑块变焦，手电筒（底部居中，图标+文字）。

• 单码模式（multi: false）：识别到第一个码立即返回
• 多码模式（multi: true，默认）：识别到多个码时定格截图、停止识别，点击标注框选择
• 运行环境要求：HBuilderX 3.9+，uni-app Vue3（manifest.json 中 "vueVersion": "3"）

一、迁移到新项目的通用步骤

1. 拷贝插件目录：整个 uni_modules/stq-scanner/ 复制到目标项目 uni_modules/ 下
2. （推荐）拷贝统一调用入口：utils/scan.js（App 端自动走原生插件，H5/小程序端自动降级 uni.scanCode）
3. 按平台配置权限：见下文【二、Android 使用方法】/【三、iOS 使用方法】
4. 制作自定义调试基座（插件含原生代码与三方依赖，标准基座不可用）： HBuilderX → 运行 → 运行到手机或模拟器 → 制作自定义调试基座
5. 选自定义基座运行：打包完成后 基座选择 → 自定义调试基座 → 运行
6. 重打基座触发条件：uni_modules/stq-scanner/utssdk/ 下任何 .uts、.swift、config.json、AndroidManifest.xml 变更；纯 JS/页面变更无需重打

二、Android 使用方法

1. 权限配置

manifest.json → app-plus → distribute → android → permissions 中确保包含：

"android" : {
    "permissions" : [
        "<uses-permission android:name=\"android.permission.CAMERA\"/>",
        "<uses-feature android:name=\"android.hardware.camera\"/>",
        "<uses-feature android:name=\"android.hardware.camera.autofocus\"/>"
    ]
}

运行时相机权限由插件自行申请（UTSAndroid.requestSystemPermission），拒绝时返回 permission_denied。

2. 依赖说明（无需手动配置）

插件自带 utssdk/app-android/config.json，云打包自动拉取 maven 依赖：

minSdkVersion 21。设备无相机或启动失败返回 camera_error: ...。

3. 打基座

• 调试：制作自定义调试基座时勾选 Android，包名默认即可，证书可用"云端证书"
• 正式发行：云打包（发行 → 原生App-云打包）会自动带上插件与依赖，无需额外操作

4. Android 端实现要点（维护参考）

• CameraX 预览 + ImageAnalysis 帧（YUV→NV21）送 MLKit 实时识别
• 多码时 PreviewView.getBitmap() 定格，对截图重跑 MLKit（识别框与画面同源，天然对齐）
• 手电筒 CameraControl.enableTorch；变焦 setZoomRatio（滑杆竖直 setRotation(270°) + 双指捏合，上限 10x）

三、iOS 使用方法

1. 权限配置

manifest.json → app-plus → distribute → ios → privacyDescription 中确保包含：

"ios" : {
    "privacyDescription" : {
        "NSCameraUsageDescription" : "扫描二维码需要使用相机"
    }
}

插件内 utssdk/app-ios/config.json 已同时声明（"privacies": ["NSCameraUsageDescription"]、deploymentTarget: 12.0），云打包时合并到 Info.plist。运行时权限由插件申请，拒绝时返回 permission_denied。

2. 证书要求

打 iOS 自定义基座（含调试）需要 Apple 开发者账号：

• 有 Mac + Xcode：可在【设置 → 运行配置】配置本地编译环境，本地打基座
• 无 Mac：制作自定义调试基座时勾选 iOS，填写 .p12 证书 + .mobileprovision 描述文件（开发证书 + 已注册测试设备的 adhoc 描述文件即可）

3. 打基座

• 调试：制作自定义调试基座 → 勾选 iOS → 填证书 → 云端打包
• 正式发行：Appstore 类型云打包自动带上插件，无需额外操作

4. iOS 端实现要点（维护参考）

• 原生 Swift 混编（同官方 uni-camera 插件架构）：ScanViewController.swift 承担全部扫码逻辑，index.uts 仅薄封装（DCloudUTSFoundation / UTSiOS.getCurrentViewController()）
• AVFoundation AVCaptureMetadataOutput 实时识别；多码时 AVCapturePhotoOutput 拍帧定格，用 Vision（VNDetectBarcodesRequest）对照片重识别，方向用 cgOrientation 显式映射后按 aspectFill 换算坐标
• 手电筒 AVCaptureDevice.torchMode；变焦 videoZoomFactor（滑杆 transform 旋转 -90° 竖直 + 双指捏合，上限 10x）
• 已知适配点：该云打包环境无 .qrCode 便捷常量，用 ISO 串 org.iso.QRCode 过滤；UISlider 赋值需显式 Float()

四、调用方式

方式 A：经 utils/scan.js（推荐，跨端兼容）

import { scanCode } from '@/utils/scan.js'

const res = await scanCode({ multi: true })   // multi 可省略，默认 true

if (res.code === 0) {
  // res.result 为二维码内容字符串
  uni.showToast({ title: res.result, icon: 'none' })
} else if (res.cancelled) {
  // 用户取消，静默处理
} else if (res.message === 'permission_denied') {
  uni.showToast({ title: '相机权限被拒绝', icon: 'none' })
} else {
  uni.showToast({ title: '扫码失败: ' + res.message, icon: 'none' })
}

App 端自动走 UTS 原生插件；H5/小程序端自动降级 uni.scanCode（返回字段已做映射，语义一致）。

方式 B：直接调插件（仅 App 端）

import { scanCode } from '@/uni_modules/stq-scanner'

const res = await scanCode({ multi: false })

API

scanCode(options): Promise\<ScanResult>

ScanResult：

Promise resolve 一切完成场景（成功/取消/失败），reject 仅在插件未集成（如未打自定义基座）时触发。两端返回结构完全一致。

五、交互说明（两端一致）

• 全屏相机取景，左上角 × 关闭（返回 cancelled）
• 单码（或 multi:false）：识别即自动返回，无需点击
• 多码：定格当前画面并停止识别 → 每个码画绿角框 + 中心实心箭头 → 顶部提示"检测到多个二维码，请点击选择其中一个" → 点击目标码返回；此时手电筒/变焦隐藏
• 手电筒：底部居中"手电筒"按钮（图标+文字），开启变绿并显示光束
• 变焦：右侧竖直滑块（底端最小/顶端最大）+ 双指捏合，滑块下方显示当前倍数

六、目录结构

uni_modules/stq-scanner/
├─ package.json                 type: uts
├─ README.md                    本文档
└─ utssdk/
   ├─ interface.uts             对外接口与类型定义
   ├─ app-android/
   │  ├─ index.uts              入口：权限申请 + 启动扫码页 + Promise 包装
   │  ├─ ScanActivity.uts       扫码页：CameraX/变焦/手电筒/定格+重识别/多码分发
   │  ├─ OverlayView.uts        多码角框遮罩层 + 中心箭头 + 点击命中
   │  ├─ config.json            maven 依赖（CameraX/MLKit）、minSdk 21
   │  └─ AndroidManifest.xml    扫码 Activity 注册
   └─ app-ios/
      ├─ index.uts              薄封装：权限/present/回调 Promise 化
      ├─ ScanViewController.swift  扫码 VC：AVFoundation/Vision/变焦/手电筒/定格重识别
      └─ config.json            deploymentTarget 12.0 + NSCameraUsageDescription

七、已知注意事项

• 仅识别二维码（QR_CODE）；扩展条码改 Android BarcodeScannerOptions.setBarcodeFormats 与 iOS availableMetadataObjectTypes 过滤串
• 变焦为数码变焦（上限 10x），辅助对准远/小码
• 定格重识别在截图里找不到 ≥2 个码时会自动恢复实时扫码（极罕见）
• iOS 端改动需 Mac+Xcode 本地编译或云端打包验证，每轮云打包只暴露第一批错误，逐批修