更新记录

1.0.1（2026-06-05）

• 更新使用文档

1.0.0（2026-06-05）

• 首次发布 s-scan 原生扫码插件，提供 scanCode 和 scanCodeAsync 两种调用方式。
• 新增 App Android 原生扫码能力，基于 CameraX 预览和 ML Kit 识别二维码、条形码、DataMatrix、PDF417。
• 新增 App iOS 原生扫码能力，基于 AVFoundation 实现相机扫码和图片识别。
• 新增接近微信体验的全屏扫码界面，支持绿色扫描线动画、手电筒按钮、相册入口和自定义标题/提示文案。
• 新增多码手动选择能力，同时识别多个码时可冻结预览并显示绿色箭头，由用户点选目标码。
• 新增连续扫码模式，识别成功后不自动关闭扫码页，可持续回调每次扫码结果。
• 新增扫码成功后的震动和提示音开关，可按业务场景控制反馈效果。
• 新增温和自动缩放能力，提升远距离或较小码的识别体验。
• 完善 uni.scanCode 常用字段兼容，包括 scanType、onlyFromCamera、success、fail、complete 等。
• 补充中文使用文档、参数说明、返回值说明、错误码说明、权限配置说明和示例页面。

平台兼容性

uni-app(3.7.9)

uni-app x(3.7.9)

s-scan 原生扫码插件

s-scan 是一个 UTS 原生扫码插件，支持 App Android 和 App iOS。插件提供接近微信扫码的全屏体验，包含实时扫码、相册识别、手电筒、多码点选、连续扫码、震动和提示音等能力，可用于设备绑定、商品条码识别、票券核销、二维码登录等场景。

重点提示：本插件是 UTS 原生插件，本地运行和真机调试前需要先制作并使用自定义调试基座。直接使用标准基座运行时，原生扫码能力不会被打包进 App，可能出现插件不存在、调用失败或无响应等情况。

功能特性

• 支持二维码、常见条形码、DataMatrix、PDF417。
• 支持 scanCode(options) 回调写法和 scanCodeAsync(options) Promise 写法。
• 支持自定义标题、提示文案、提示背景色、扫描线颜色和手电筒激活色。
• 支持相机扫码和相册图片识别。
• 支持同时识别多个码时手动点选目标码。
• 支持连续扫码，适合批量盘点、批量核销等场景。
• 支持扫码成功后的震动和 Beep 提示音。
• 支持 onlyFromCamera、success、fail、complete 等 uni.scanCode 常用字段。

安装说明

1. 在插件市场导入本插件到项目。
2. 确认项目已包含 uni_modules/s-scan 目录。
3. 在需要扫码的页面中按下面示例导入并调用。

import { scanCode, scanCodeAsync } from '@/uni_modules/s-scan'

基础用法

回调写法

import { scanCode } from '@/uni_modules/s-scan'

scanCode({
  title: '扫码',
  content: '将二维码或条形码放入屏幕内',
  scanType: ['qrCode', 'barCode'],
  success(res) {
    console.log('扫码结果', res.result)
  },
  fail(err) {
    console.log('扫码失败', err.errCode, err.errMsg)
  },
  complete(res) {
    console.log('扫码完成', res)
  },
})

Promise 写法

import { scanCodeAsync } from '@/uni_modules/s-scan'

try {
  const res = await scanCodeAsync({
    title: '扫码',
    content: '将二维码或条形码放入屏幕内',
  })
  console.log('扫码结果', res.result)
} catch (err) {
  console.log('扫码失败', err.errCode, err.errMsg)
}

完整配置

scanCode({
  title: '设备扫码',
  titleStyle: {
    color: '#FFFFFF',
    fontSize: 18,
  },
  content: '请扫描设备机身二维码',
  contentStyle: {
    color: '#FFFFFF',
    fontSize: 15,
    backgroundColor: '#66000000',
  },
  scanType: ['qrCode', 'barCode'],
  vibrate: false,
  beep: false,
  manualSelect: true,
  scanLineColor: '#07C160',
  flashlightActiveColor: '#07C160',
  autoZoom: true,
  showFlashlight: true,
  showAlbum: true,
  continuous: false,
  onlyFromCamera: false,
  success(res) {},
  fail(err) {},
  complete(res) {},
})

连续扫码

开启 continuous 后，扫码页不会在识别成功后自动关闭。每次识别到结果都会触发 success；用户关闭扫码页时，会再返回一次当前已识别结果列表。

scanCode({
  continuous: true,
  success(res) {
    if (Array.isArray(res.result)) {
      console.log('本次连续扫码汇总', res.result)
      return
    }
    console.log('单次扫码结果', res.result)
  },
})

使用 scanCodeAsync 开启连续扫码时，Promise 会在用户关闭扫码页并返回汇总结果后 resolve。

参数说明

返回值

type ScanCodeSuccess = {
  result: string | string[]
  scanType: string
  rawScanType?: string
  fromAlbum?: boolean
  charSet?: string
}

错误码

权限配置

Android 插件已声明以下权限：

• android.permission.CAMERA
• android.permission.VIBRATE
• android.permission.READ_EXTERNAL_STORAGE
• android.permission.READ_MEDIA_IMAGES

iOS 需要在 manifest.json 中配置相机和相册用途说明：

{
  "NSCameraUsageDescription": "需要使用相机扫描二维码或条形码",
  "NSPhotoLibraryUsageDescription": "需要访问相册以识别图片中的二维码或条形码"
}

示例工程已内置以上配置，接入业务项目时请按项目实际文案调整。

注意事项

• 本插件仅支持 App Android 和 App iOS，H5 和小程序端不会启用原生扫码能力。
• 当 content 为空字符串时，扫码页不会显示提示文字，也不会显示提示背景。
• onlyFromCamera 为 true 时会隐藏相册入口；如果同时设置了 showAlbum: true，仍以 onlyFromCamera 为准。
• 多码选择的箭头位置来自原生识别框坐标。识别到多个候选码时，插件会短暂聚合候选、冻结摄像头画面，并将左上角按钮变为“取消”，由用户点选目标码。
• 连续扫码模式下，插件不会自动关闭扫码页；用户点左上角关闭时会返回已识别内容数组。
• Android 相册识别依赖系统图库返回图片 URI；部分定制 ROM 的图库如果不返回标准图片 URI，可能无法识别。