更新记录

1.0.1（2026-07-22）

更新插件使用demo等

1.0.0（2026-07-22）

插件首次发布

平台兼容性

uni-app(4.71)

uni-app x(4.71)

gt-scan

面向 uni-app 与 uni-app x 的 Android、iOS UTS 扫码插件。提供原生全屏扫码页，支持单次扫码、连续扫码、同帧多码、相册/本地图片识别、运行时相机控制和二维码生成。

平台与依赖

仅实现 App-Android 和 App-iOS。Web、小程序、HarmonyOS 不支持。

UTS 原生插件必须制作包含本插件的自定义调试基座；标准基座不包含插件的原生依赖和代码。

功能

• 单次扫码，调用方式接近 uni.scanCode。
• 连续扫码，多次触发 onScan。
• 同一帧返回多个码，单批最多 10 个。
• 按内容和码制去重，可设置去重与回调间隔。
• 扫描区域、前后摄像头、手势缩放、闪光灯、相机切换。
• 原生扫码页标题、提示语、颜色和按钮显隐配置。
• 扫码页内从相册选择图片，或直接调用 decodeImage 识别本地图片。
• 生成自定义尺寸、颜色、容错级别和静区的二维码 PNG。
• 相机权限状态查询与主动请求。
• 全部识别能力离线运行，不上传相机画面、图片或结果。

快速开始

import {
  scanCode,
  GtScanResult
} from '@/uni_modules/gt-scan'

scanCode({
  formats: ['QR_CODE', 'BAR_CODE'],
  onlyFromCamera: false,
  enableVibrate: true,
  timeoutMs: 30000,
  success: (res : GtScanResult) => {
    console.log('内容：', res.result)
    console.log('码制：', res.scanType)
  },
  fail: (error) => {
    if (error.errCode != 9012010) {
      console.error('扫码失败：', error)
    }
  }
})

BAR_CODE 是输入时可用的条形码集合别名，不会作为结果中的 scanType 返回。

连续扫码

import {
  startScan,
  stopScan,
  GtScanBatchResult
} from '@/uni_modules/gt-scan'

let batchCount = 0

startScan({
  formats: ['QR_CODE', 'CODE_128', 'EAN_13'],
  multi: true,
  maxResults: 5,
  duplicateIntervalMs: 1200,
  scanIntervalMs: 180,
  onScan: (res : GtScanBatchResult) => {
    batchCount += 1
    console.log('本批结果：', res.results)
    if (batchCount >= 5) {
      stopScan()
    }
  },
  onStateChange: (res) => {
    console.log('会话状态：', res.state)
  },
  fail: (error) => {
    console.error('会话失败：', error)
  },
  complete: (res) => {
    console.log('扫码会话结束：', res)
  }
})

startScan.success 在相机进入 running 时执行一次；onScan 可执行多次；complete 在会话结束时执行一次。用户点击取消时，fail 和 complete 都会收到 9012010。

识别本地图片

import { decodeImage } from '@/uni_modules/gt-scan'

uni.chooseImage({
  count: 1,
  success: (chooseResult) => {
    if (chooseResult.tempFilePaths.length == 0) return
    decodeImage({
      path: chooseResult.tempFilePaths[0],
      maxResults: 10,
      success: (res) => {
        console.log('图片中的码：', res.results)
      }
    })
  }
})

Android 支持普通文件路径、file:// 和 content://；iOS 支持沙盒内的普通文件路径和 file://。

生成二维码

import { createQRCode } from '@/uni_modules/gt-scan'

createQRCode({
  content: 'https://example.com/product?id=100',
  width: 640,
  height: 640,
  margin: 4,
  correctionLevel: 'M',
  foregroundColor: '#111827',
  backgroundColor: '#FFFFFF',
  success: (res) => {
    console.log('二维码临时文件：', res.tempFilePath)
  }
})

输出为应用缓存目录下的临时 PNG，应用或系统清理缓存后可能失效。需要长期保存时，请由业务代码复制到持久目录。margin 单位为二维码模块数，范围 0...32。

支持的码制

运行时可调用 getSupportedFormats() 获取公共格式列表。iOS 12 至 14 传入 CODABAR 会返回 9012007。

API

GtScanCodeOptions

GtStartScanOptions

包含 GtScanCodeOptions 的扫码、相机、反馈和 UI 参数，并增加：

GtScanUiOptions

颜色参数支持 #RRGGBB 和与 Android Color.parseColor 一致的 #AARRGGBB。

返回结果

GtScanResult 和 GtScanItem 的主要字段：

扫码页使用 scanArea 过滤相机识别结果；decodeImage 不按扫描区域过滤。

会话与权限状态

getScanState() 返回：idle、opening、running、paused、closing。

getCameraPermissionStatus() 与 requestCameraPermission() 的 status 返回：

• notDetermined：尚未请求。
• granted：已授权。
• denied：Android 已拒绝但仍可再次请求。
• permanentlyDenied：已永久拒绝，需要进入系统设置。
• restricted：系统限制或上下文不可用。

权限请求 API 本身成功不等于用户授权，应检查返回值的 granted。扫码页也会在需要时主动请求相机权限。

原生配置与隐私

插件自动声明：

• Android：android.permission.CAMERA、android.permission.VIBRATE。
• iOS：NSCameraUsageDescription、NSPhotoLibraryUsageDescription。

正式发布前应在应用配置中使用与你的业务一致的权限说明，并在隐私政策中说明相机、相册以及扫码结果的实际用途。

Android 使用 bundled ML Kit 模型，首次运行不需要下载识别模型，也不需要 INTERNET 权限。相册通过系统文档选择器读取用户主动选择的单张图片，不申请广泛存储权限。

Google 官方给出的 bundled 条码模型包体增量约为 2.4 MB；CameraX、ZXing、代码压缩和已有依赖还会影响最终 APK/AAB 大小，请以正式构建产物为准。iOS 仅使用系统 Framework，不内置第三方识别模型。

注意事项

• 同一时间只允许一个全屏扫码会话，重复启动返回 9012005。
• setTorch、setZoom 和 switchCamera 只在扫码页已打开时有效；无会话返回 9012006。
• 前置摄像头通常没有闪光灯；内置扫码页会自动隐藏闪光灯按钮，直接调用 setTorch 则会失败并返回原生原因。
• 控制 API 的成功表示控制请求已被原生相机接受，不承诺硬件状态同步完成。
• 用户点击返回或取消属于正常交互，但通过 fail 返回 9012010，业务通常可静默处理。
• iOS 的 Vision 不提供原始条码字节和 ML Kit 同级的结构化内容类型，相关字段按上文降级。
• 请至少使用一台 Android 真机和一台 iPhone 验证权限、旋转、前后摄像头、相册和连续扫码，再将插件市场平台标记改为支持。

错误码