更新记录

1.0.0（2026-08-08）

SL-ScanBridge 是面向 Android uni-app / uni-app x 场景的扫码枪统一接入插件。插件把 PDA Broadcast、USB HID、蓝牙 HID、2.4G 接收器和模拟键盘扫码输入统一为一套 API，业务页面通过 onScan() 获取扫码结果，不需要维护隐藏 input、焦点抢占或多个厂商广播适配逻辑。

插件适合 WMS、仓储、ERP、MES、进销存、物流、快递、PDA 拣货、库存盘点、入库、出库、订单复核、门店盘点、固定资产管理、生产管理等需要高频扫码的企业场景。

当前 V1.0 已完成 UTS 源码、uni-app Demo 页面、Android 原生测试 Demo、API 文档、测试报告、设备兼容性报告、HBuilderX CLI 编译验证、Android 真机 Demo 安装启动验证、ADB 模拟 Broadcast 端到端验证。Harmony 设备已完成 Demo UI 前端编译和未签名 HAP 生成验证。真实 USB HID、蓝牙 HID、2.4G HID 和各厂商 PDA 真实扫码仍需目标设备继续验证。 建议购买前先使用 DCloud 插件试用功能，在目标 PDA / 扫码枪设备上完成兼容性验证。不同厂商及不同固件版本的广播参数可能存在差异，插件支持自定义 Broadcast Action / DataKey。

平台兼容性

uni-app(5.23)

SL-ScanBridge 插件使用说明

本文档用于 DCloud 插件市场“插件使用说明”上传项，格式为 Markdown。

1. 插件用途

SL-ScanBridge 用于在 Android uni-app / uni-app x 项目中统一监听扫码枪结果，支持 PDA 广播扫码、USB HID、蓝牙 HID、2.4G HID 接收器和模拟键盘扫码输入。

业务页面通过一套 API 获取扫码结果，不需要维护隐藏 input、焦点抢占或多个厂商广播适配逻辑。

2. 支持平台

支持：

• Android uni-app Vue2 / Vue3。
• uni-app x Android 需按项目环境继续验证。

不支持：

• iOS。
• HarmonyOS 扫码监听。
• H5。
• 小程序。

当前 Harmony 状态仅为 Demo UI 前端编译和未签名 HAP 生成验证，不包含 Harmony 原生扫码监听能力。

3. 安装和引入

将插件导入项目后，在需要监听扫码的页面中引入：

import {
  startScan,
  stopScan,
  onScan,
  offScan,
  getScanStatus,
  getDeviceInfo
} from '@/uni_modules/sl-scan-bridge'

4. 快速开始

最简单的用法是使用 auto 模式，让插件自动处理 HID 和 Broadcast 场景：

import { startScan, stopScan, onScan, offScan } from '@/uni_modules/sl-scan-bridge'

const handleScan = (res) => {
  console.log('扫码内容：', res.code)
  console.log('来源：', res.source)
}

onScan(handleScan)

startScan({
  mode: 'auto'
})

// 页面卸载时停止监听
// stopScan()
// offScan(handleScan)

5. 推荐生命周期写法

在页面显示时注册监听，在页面卸载或不再需要扫码时移除监听：

import { onLoad, onUnload } from '@dcloudio/uni-app'
import { startScan, stopScan, onScan, offScan } from '@/uni_modules/sl-scan-bridge'

const handleScan = (res) => {
  uni.showToast({
    title: res.code,
    icon: 'none'
  })
}

onLoad(() => {
  onScan(handleScan)
  startScan({
    mode: 'auto',
    duplicateInterval: 500
  })
})

onUnload(() => {
  offScan(handleScan)
  stopScan()
})

6. HID 扫码枪用法

USB 扫码枪、蓝牙扫码枪、2.4G 接收器扫码枪通常以键盘输入方式工作，可使用 hid 模式：

startScan({
  mode: 'hid',
  keyInterval: 50,
  inputTimeout: 100,
  duplicateInterval: 500,
  trim: true,
  endKeys: ['Enter', 'Tab']
})

常用参数说明：

如果扫码枪可以配置后缀，建议配置为 Enter 或 Tab。

7. PDA Broadcast 用法

PDA 广播扫码需要先在设备系统或厂商扫描工具里配置广播 Action 和数据字段，再在插件中填写对应参数：

startScan({
  mode: 'broadcast',
  broadcast: {
    action: 'com.xxx.SCAN',
    dataKey: 'barcode'
  }
})

如果不确定厂商使用哪个字段，可以配置备用字段：

startScan({
  mode: 'broadcast',
  broadcast: {
    action: 'com.xxx.SCAN',
    dataKey: 'barcode',
    extraKeys: ['code', 'scanData', 'barcode_string'],
    charset: 'UTF-8'
  }
})

8. 厂商 Profile

插件提供常见厂商 Profile 预设，用于减少配置量：

startScan({
  mode: 'broadcast',
  manufacturer: 'zebra'
})

可按项目选择的厂商值包括：

• generic
• zebra
• honeywell
• urovo
• newland
• seuic
• idata

注意：厂商 Profile 是常见预设，不代表所有真实型号已验证。正式商用前，需要在目标 PDA 型号上确认 Action、dataKey 和系统扫描设置。

9. 扫码结果

扫码成功后，onScan 回调返回统一结构：

interface ScanResult {
  code: string
  source: 'hid' | 'broadcast'
  manufacturer?: string
  deviceModel?: string
  barcodeType?: string
  timestamp: number
  raw?: object | null
}

示例：

onScan((res) => {
  if (!res.code) return

  console.log('条码：', res.code)
  console.log('来源：', res.source)
  console.log('时间：', res.timestamp)
})

10. 状态和设备信息

获取当前监听状态：

const status = getScanStatus()
console.log(status.started, status.mode, status.listenerCount)

获取设备信息：

const deviceInfo = getDeviceInfo()
console.log(deviceInfo.manufacturer, deviceInfo.model, deviceInfo.androidVersion)

11. ADB 模拟 Broadcast 测试

如果需要先验证 Broadcast 通路，可以使用 ADB 发送模拟广播：

adb shell am broadcast -a com.sl.scan.TEST --es barcode "6923450657713"

对应插件配置：

startScan({
  mode: 'broadcast',
  broadcast: {
    action: 'com.sl.scan.TEST',
    dataKey: 'barcode'
  },
  debug: true
})

12. 常见问题

没有收到扫码结果

请检查：

• 是否已调用 onScan 注册回调。
• 是否已调用 startScan 启动监听。
• PDA 广播 Action 是否与设备系统配置一致。
• PDA 广播数据字段是否与 dataKey 一致。
• HID 扫码枪是否处于键盘输入模式。
• 页面是否在扫码前已经卸载或调用了 stopScan。

HID 扫码结果不完整

可适当增大：

inputTimeout: 150
keyInterval: 80

同时建议给扫码枪配置 Enter 或 Tab 后缀。

重复扫码被过滤

默认 duplicateInterval 为 500ms，同一条码在 500ms 内重复上报会被过滤。如业务需要连续扫同一条码，可设置：

duplicateInterval: 0

厂商 PDA 不能直接使用预设

不同型号或系统版本可能使用不同 Action / dataKey。请在厂商扫描设置中确认广播参数，或改用自定义 Broadcast 配置。

13. 使用限制

• 当前版本仅面向 Android。
• 不包含摄像头扫码、OCR、NFC、RFID。
• 不包含账号系统、云服务或后台管理。
• HarmonyOS 扫码监听未实现，不能按 Harmony 扫码插件发布。
• USB HID、蓝牙 HID、2.4G HID 和真实 PDA 型号建议在目标设备上完成真机验证。

14. 权限和数据说明

插件仅声明 android.permission.VIBRATE，用于扫码成功后的可选振动反馈。

插件不采集、不上传、不存储扫码数据。扫码结果仅通过调用方应用内的 onScan 回调返回，由业务项目自行处理。