更新记录

1.6.0（2026-10-10）

• 优化 Android 相机分析分辨率、中心对焦测光和 ML Kit 智能变焦速度，提升远距离小码识别能力
• 优化 Android 和 iOS 单码跨帧确认，达到确认次数后立即返回，不再固定等待完整确认时间窗
• 优化 iOS 相机会话清晰度及中心连续对焦测光
• 缩短默认扫码确认时间、自动变焦延迟和步进间隔，并提高默认最大变焦倍率
• 新增 scanResolution 扫描分辨率等级配置，支持 low、medium 和 high，不支持目标尺寸时自动回退

1.5.1（2026-09-18）

• 修复 iOS 云打包编译错误的问题

1.5.0（2026-09-15）

• 新增 captureImage 扫码图片回传能力，支持相机和相册识别结果输出临时 JPEG 路径
• 新增 captureImageMode、imageQuality 和 imageMaxWidth，支持返回码区裁剪图或完整原图并控制压缩参数
• 扫码结果新增 imagePath、imageFormat、imageWidth 和 imageHeight，可配合逐码异步校验上传后端复核
• 新增 manualSelectTipText 配置项，支持自定义或隐藏多码手动选择提示文案
• 修复 iOS 相机扫码使用 captureImageMode: 'code' 时，二维码裁剪图片宽度异常、内容显示不完整的问题

平台兼容性

uni-app(3.8.5)

uni-app x(3.8.5)

其他

s-scan 原生扫码插件

s-scan 提供接近微信扫码的全屏体验，重点覆盖原生多码点选、远距自动变焦、相册多码识别、连续扫码逐码异步校验和可扩展底部操作，可用于设备绑定、商品条码识别、票券核销、批量盘点等场景。

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

功能特性

• 支持二维码、常见条形码、DataMatrix、PDF417。
• 支持 scanCode(options) 回调写法和 scanCodeAsync(options) Promise 写法。
• 支持自定义标题、提示文案、提示背景色、扫描线颜色和手电筒激活色。
• 支持相机扫码和相册图片识别。
• 支持返回与扫码结果对应的临时 JPEG 图片，可上传后端复核。
• 支持同时识别多个码时手动点选目标码。
• 支持连续扫码和逐码异步校验，适合批量盘点、批量核销等场景。
• 支持自定义底部按钮、按钮顺序和点击事件，可配置本地、Base64 或 HTTPS 在线图标。
• 支持自定义按钮先关闭原生扫码页再回调，业务可安全跳转到手动输入等页面。
• 支持业务代码主动关闭当前扫码页。
• 支持扫码成功后的震动和 Beep 提示音。
• 支持 onlyFromCamera、success、fail、complete 等 uni.scanCode 常用字段。

安装说明

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

import { scanCode, scanCodeAsync, completeScan, closeScan } 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'],
  stripAimPrefix: true,
  vibrate: false,
  beep: false,
  manualSelect: true,
  manualSelectTipText: '点击绿点选择要打开的页面',
  scanConfirmTimeout: 250,
  scanResolution: 'medium',
  scanLineColor: '#07C160',
  flashlightActiveColor: '#07C160',
  autoZoom: true,
  autoZoomMode: 'smart',
  autoZoomDelay: 400,
  autoZoomRange: [1, 2.5],
  autoZoomStep: 0.3,
  autoZoomInterval: 200,
  pinchZoom: true,
  showFlashlight: true,
  showAlbum: true,
  bottomButtons: [
    { id: 'flashlight', type: 'flashlight', text: '手电筒' },
    {
      id: 'manualInput',
      type: 'custom',
      text: '手动输入',
      icon: 'https://img.icons8.com/ios-filled/100/ffffff/keyboard.png',
      closeOnClick: true,
    },
    { id: 'album', type: 'album', text: '相册' },
  ],
  bottomButtonsHorizontalPadding: 52,
  useSystemPhotoPicker: false,
  continuous: false,
  validateEachScan: false,
  deduplicate: false,
  showSuccessTip: true,
  successTipText: '扫描成功',
  failureTipText: '验证失败',
  processingTipText: '处理中…',
  scanInterval: 1200,
  onlyFromCamera: false,
  onBottomButtonClick(event) {},
  success(res) {},
  fail(err) {},
  complete(res) {},
})

自定义底部按钮

传入 bottomButtons 后，数组将替代 showFlashlight 和 showAlbum 生成的默认布局，并按照数组顺序显示最多 4 个有效按钮。多个按钮使用类似 CSS justify-content: space-between 的方式排列，bottomButtonsHorizontalPadding 用于设置两侧留白。flashlight 和 album 使用插件内置行为，custom 通过 onBottomButtonClick 交给业务处理。

scanCode({
  bottomButtons: [
    { id: 'flashlight', type: 'flashlight', text: '手电筒' },
    {
      id: 'manualInput',
      type: 'custom',
      text: '手动输入',
      icon: 'https://img.icons8.com/ios-filled/100/ffffff/keyboard.png',
      closeOnClick: true,
    },
    { id: 'help', type: 'custom', icon: 'https://example.com/icons/help.png' },
    { id: 'album', type: 'album', text: '相册' },
  ],
  bottomButtonsHorizontalPadding: 40,
  onBottomButtonClick(event) {
    if (event.id === 'manualInput' && event.closed) {
      uni.navigateTo({ url: '/pages/manual-input/manual-input' })
    }
  },
  fail(err) {
    if (err.errCode === 1300004 && err.reason === 'bottomButton') return
    console.log('扫码失败', err)
  },
})

closeOnClick 仅作用于 custom 按钮，默认为 false。设为 true 时，插件会停止相机、关闭原生扫码页、结束本次扫码调用，最后触发 onBottomButtonClick；业务跳转不会被扫码页遮挡。普通扫码会以 1300004 结束，并附带 reason: 'bottomButton' 和 buttonId；连续扫码则先返回当前汇总结果，再触发按钮事件。

图标支持 /static/...、App 本地文件路径、data:image/...;base64,... 和 HTTPS URL。推荐使用透明背景的 96 × 96 PNG，原生端会按约 28 dp/pt 等比显示。在线图标异步加载，不阻塞相机启动；custom 按钮未配置图标或图标加载失败时显示 text 的第一个字符，text 也为空时不绘制内容；flashlight 和 album 未配置图标时仍使用内置图形。默认不加载 HTTP 明文地址。

底部按钮字段

onBottomButtonClick 返回 { id, type, closed, active? }。closed 表示回调前扫码页是否已经关闭；手电筒按钮还会通过 active 返回当前开关状态。

返回扫码图片

设置 captureImage: true 后，相机扫码和相册识别都会将对应图片编码为 JPEG，并在单次结果中返回应用缓存目录下的本地绝对路径。默认裁剪当前选中码的区域并保留识别留白；多码点选时，返回的是用户所选候选码对应的图片。

scanCode({
  continuous: true,
  validateEachScan: true,
  captureImage: true,
  captureImageMode: 'code',
  imageQuality: 80,
  imageMaxWidth: 1600,
  onScan(res) {
    if (!res.imagePath) {
      completeScan(res.scanId, { success: false, message: '扫码图片生成失败' })
      return
    }
    uni.uploadFile({
      url: 'https://example.com/api/verify-code-image',
      filePath: res.imagePath,
      name: 'image',
      formData: {
        clientResult: String(res.result),
        scanType: res.scanType,
      },
      success(response) {
        const data = JSON.parse(response.data)
        completeScan(res.scanId, {
          success: data.code === 0,
          message: data.message || (data.code === 0 ? '核验成功' : '核验失败'),
        })
      },
      fail() {
        completeScan(res.scanId, { success: false, message: '网络异常，请重试' })
      },
    })
  },
})

captureImageMode 支持 code 和 full：code 返回码区裁剪图，适合上传识别；full 返回完整相机帧或相册图片。输出格式固定为 JPEG，imageQuality 会限制到 1 至 100，imageMaxWidth 最小为 1。Android 相机回传时还会根据 imageMaxWidth 选择取帧清晰度，取帧目标宽度限制在 640 至 2560。图片生成失败不会影响扫码成功，结果中不会出现 imagePath。

图片路径是临时缓存路径，不应持久化保存。插件会在下次开启图片回传扫码时清理超过 24 小时的缓存图片，系统也可能提前清理应用缓存；收到回调后应尽快通过 uni.uploadFile 上传。

imagePath 应原样传给 uni.uploadFile。在 App iOS 中，WebView 无法直接通过 file:// 显示应用缓存目录的绝对路径；如需赋给 <image> 预览，应先使用 plus.io.resolveLocalFileSystemURL 和 plus.io.FileReader.readAsDataURL 读取为 Data URL。示例项目已封装该转换，Android 仍直接使用本地路径。

连续扫码

开启 continuous 后，扫码页不会在识别成功后自动关闭。默认每次识别到结果都会触发 success；用户关闭扫码页时，会再返回一次当前已识别结果列表。配置 onScan 后，只有业务校验通过的单次结果才会触发 success。

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

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

如需在连续扫码中让相同内容只回调并汇总一次，可设置 deduplicate: true。默认 false，相同码再次识别时仍会触发回调，并保留在关闭页面时返回的汇总列表中。

连续扫码成功后默认会显示轻量的“扫描成功”提示，可通过 showSuccessTip: false 关闭，也可以通过 successTipText 自定义提示文案；scanInterval 用于设置两次自动连续扫码回调之间的最小间隔，单位毫秒，默认 1200。用户手动点选多码结果时不受该间隔限制。

连续扫码时从相册选取图片识别成功后，会触发一次 success 回调并继续停留在扫码页；用户关闭扫码页时才会返回已识别内容数组。

逐码异步校验

连续扫码需要先请求后端确认当前码时，需同时设置 validateEachScan: true 并传入 onScan。识别到码后，扫码页会暂停识别并显示“处理中…”，直到业务调用 completeScan；随后会显示业务返回的成功或失败提示，再恢复扫码。普通连续扫码不要开启 validateEachScan，识别后会直接触发 success 并继续扫描。

等待文案可通过 processingTipText 自定义。校验回执未传 message 时，成功提示使用 successTipText，失败提示使用 failureTipText。三个字段传入空字符串或纯空白时都会使用各自的默认文案。

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

scanCode({
  continuous: true,
  validateEachScan: true,
  successTipText: '核验成功',
  failureTipText: '核验失败',
  processingTipText: '正在核验…',
  onScan(res) {
    uni.request({
      url: 'https://example.com/api/verify-code',
      method: 'POST',
      data: { code: res.result },
      success(response) {
        const passed = response.data.code === 0
        completeScan(res.scanId, {
          success: passed,
          message: passed ? '核验成功' : response.data.message || '核验失败',
        })
      },
      fail() {
        completeScan(res.scanId, { success: false, message: '网络异常，请重试' })
      },
    })
  },
  success(res) {
    if (Array.isArray(res.result)) {
      console.log('校验通过的扫码汇总', res.result)
      return
    }
    console.log('本次校验通过', res.result)
  },
})

completeScan(res.scanId, { success, message }) 的规则：

• success: true：显示绿色提示，将当前码加入连续扫码汇总，并触发一次 success。
• success: false：显示红色提示，不加入汇总，也不触发 success，提示后可重新扫描。
• message 可省略；成功时使用 successTipText，失败时使用 failureTipText。
• showSuccessTip: false 时不显示逐码结果提示，收到回执后立即恢复扫码。

业务必须在接口成功、业务失败和网络异常分支中都调用一次 completeScan。未调用时扫码页会继续保持暂停，避免产生并发校验请求；相同 scanId 重复调用只处理第一次。等待校验时仍可关闭扫码页，尚未完成校验的码不会进入汇总结果。

主动关闭扫码页

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

const closed = closeScan()
console.log('是否已发起关闭', closed)

closeScan() 会关闭当前正在运行的扫码页，并返回 boolean 表示是否存在可关闭的扫码页。普通扫码会触发取消失败回调，错误码为 1300004；连续扫码会和用户点关闭按钮一样，返回当前已识别结果数组。

参数说明

AIM 码制前缀

stripAimPrefix 默认为 true，相机扫码和相册识别都会移除结果开头且与实际识别类型匹配的 AIM 标识。设为 false 时返回解码器的原始内容。插件支持过滤的前缀家族如下，其中 n 表示一位数字修饰符：

过滤只处理结果开头的 3 个字符，不会替换正文中出现的相似文本；前缀家族与原生识别类型不匹配时也会保留原内容。

返回值

type ScanCodeSuccess = {
  scanId: number
  result: string | string[]
  scanType: string
  rawScanType?: string
  fromAlbum?: boolean
  imagePath?: string
  imageFormat?: 'jpeg'
  imageWidth?: number
  imageHeight?: number
  charSet?: string
}

错误码

权限配置

Android 插件已声明以下权限：

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

Android 默认使用与旧版本一致的厂商图库选择方式，并按系统版本申请相册读取权限。设置 useSystemPhotoPicker: true 后，会按能力依次尝试系统照片选择器和标准文档选择器，这两种方式无需运行时相册读取授权；均不可用时回退到旧图库。个别定制 ROM 在旧图库模式下仍可能显示应用选择器。

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

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

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

注意事项

• 本插件仅支持 App Android 和 App iOS，H5 和小程序端不会启用原生扫码能力。
• 当 content 为空字符串时，扫码页不会显示提示文字，也不会显示提示背景。
• onlyFromCamera 为 true 时会隐藏相册入口；如果同时设置了 showAlbum: true，仍以 onlyFromCamera 为准。
• bottomButtons 一旦传入就接管底部布局；显式传入空数组会隐藏全部底部按钮。onlyFromCamera: true 仍会过滤数组中的 album 按钮。
• 在线按钮图标仅默认支持 HTTPS，使用 Android 明文 HTTP 或放宽 iOS ATS 需要由业务项目自行承担并配置安全策略。
• useSystemPhotoPicker 仅影响 Android 相册入口，默认为 false；设为 true 可优先使用系统照片/文档选择器，降低厂商图库应用选择弹窗的出现概率。
• captureImage 默认关闭。开启后会增加一次取帧、裁剪、JPEG 编码和缓存写入，图片完成前扫码结果回调会短暂等待。
• 图片文件保存在应用缓存目录的 s-scan-images 子目录，返回不带 file:// 前缀的本地绝对路径，可直接传给 App 端 uni.uploadFile。
• scanResolution 的 Android 期望尺寸依次约为 640×480、1280×720、1920×1080，iOS 使用对应相机会话预设。high 有利于远距离小码，但会增加单帧处理耗时、内存、功耗和发热；低端机或连续扫码可使用 low，一般场景建议保留 medium。
• captureImage 返回图片的实际像素不会超过相机提供的扫描帧，imageMaxWidth 只限制输出宽度，不会反向提高扫描分辨率。
• Android 的 smart 模式保留 ML Kit 智能缩放判断：没有智能建议时不会主动放大；收到建议后，插件会在 autoZoomDelay 结束后快速平滑过渡到建议倍率，autoZoomRange 仍用于限制倍率范围，autoZoomStep: 0 可关闭倍率变化。progressive 模式不等待智能建议，会按 autoZoomStep 和 autoZoomInterval 主动渐进到最大倍率。iOS 没有 ML Kit 同等能力，smart 会回退到 progressive。
• autoZoom 开启时会先保持原始倍率识别 autoZoomDelay 毫秒。识别到有效内容或用户开始双指缩放时，会立刻停止本次扫码会话的自动变焦及正在执行的过渡。
• 远距离小码建议将 autoZoomDelay 设为 300～500、autoZoomStep 设为 0.25～0.35、autoZoomInterval 设为 150～250。过小的步长配合过长的间隔，会显著延长 iOS 和 Android progressive 模式到达目标倍率的时间。
• pinchZoom 开启后，用户双指缩放会优先使用手动倍率，本次扫码中 autoZoom 不会继续覆盖用户设置。
• 相机扫码会在 scanConfirmTimeout 时间窗内进行跨帧确认；关闭多码选择时，单码达到确认次数会立即返回，无需等满时间窗。开启 manualSelect 且收集到多个候选时显示多码箭头。EAN、UPC、ITF 等数字一维码使用更严格的确认次数，以降低暗光、模糊和反光导致的瞬时误码。
• 多码选择的箭头位置来自原生识别框坐标。相机识别会冻结摄像头画面；相册图片识别到多个码时会显示原图。两种来源都会将左上角按钮变为“取消”，由用户点选目标码。
• 连续扫码模式下，插件不会自动关闭扫码页；相册识别成功后会继续停留在扫码页，用户点左上角关闭时会返回已识别内容数组。
• Android 相册识别依赖系统照片选择器、文档提供方或兼容图库返回图片 URI；部分定制 ROM 的选择器如果不返回可读取的标准 URI，可能无法识别。