更新记录

1.0.1（2026-06-14）

chore：更新说明文档

1.0.0（2026-06-13）

无 UI 的渲染层组件（renderless component）极简的方式接入安卓PDA扫码

平台兼容性

uni-app(4.52)

SeuicScan 激光扫码组件

简介

SeuicScan 是一个无 UI 的渲染层组件（renderless component），封装了 Seuic 扫码枪的 Android 广播接收逻辑。组件通过监听 Android 系统广播来捕获扫码枪扫描到的条码数据，并以 Vue 事件形式向外传递。

适用设备：Seuic（赛睿）品牌的 PDA 扫码枪设备。

适用场景

• 需要接收 Seuic 扫码枪广播的页面

API

Props

Events

Expose（通过 ref 调用）

// 手动开始扫码监听
start(): void

// 手动停止扫码监听
stop(): void

// 扫码是否正在运行（只读）
isRunning: Ref<boolean>

使用方式

模式一：自动启停（autoStart = true，默认）

适用于不需要精确控制启停时机的简单场景。组件挂载时自动开始监听，卸载时自动停止。

<template>
  <view>
    <SeuicScan @scan="handleScan" />
  </view>
</template>

<script lang="ts" setup>
import SeuicScan from '@/components/SeuicScan/SeuicScan.vue'

function handleScan(data: { code: string }) {
  console.log('扫码结果:', data.code)
  // 处理扫码数据...
}
</script>

模式二：手动启停（autoStart = false，推荐）

推荐在页面中使用此模式，结合 uni-app 的 onShow / onHide 生命周期，确保页面可见时才监听扫码，切到后台时自动停止，避免资源浪费和串数据问题。

<template>
  <PageLayout>
    <SeuicScan ref="scannerRef" :autoStart="false" @scan="handleScan" />
    <!-- 页面内容 -->
  </PageLayout>
</template>

<script lang="ts" setup>
import { ref, onUnmounted } from 'vue'
import { onShow, onHide } from '@dcloudio/uni-app'
import SeuicScan from '@/components/SeuicScan/SeuicScan.vue'

const scannerRef = ref<InstanceType<typeof SeuicScan> | null>(null)

function handleScan(data: { code: string }) {
  console.log('扫码结果:', data.code)
  // 处理扫码数据...
}

onShow(() => {
  scannerRef.value?.start()
})

onHide(() => {
  scannerRef.value?.stop()
})

onUnmounted(() => {
  scannerRef.value?.stop()
})
</script>

模式三：自定义广播参数

适用于非 Seuic 品牌的扫码枪设备，可通过 Props 传入自定义的广播 Action 和键值名称。

<SeuicScan
  :autoStart="false"
  broadcast-action="com.example.scanner.BROADCAST"
  scanner-data-key="barcode_data"
  @scan="handleScan"
/>

工作原理

┌─────────────────────────────────────────────────┐
│                  Seuic PDA 设备                    │
│                                                   │
│  ┌──────────┐    Android 广播     ┌───────────┐  │
│  │  扫码枪   │ ─────────────────→ │ Broadcast  │  │
│  │  硬件模块  │   scannerdata     │  Receiver  │  │
│  └──────────┘                    └─────┬─────┘  │
│                                       │          │
│                              emit('scan', {code})│
│                                       │          │
│                              ┌────────▼───────┐  │
│                              │  父组件 @scan   │  │
│                              │  handleScan()  │  │
│                              └────────────────┘  │
└─────────────────────────────────────────────────┘

1. initScan() — 获取 Android 主 Activity 的上下文，创建 IntentFilter 并设置要监听的广播 Action，实现 BroadcastReceiver 接口。
2. startScan() — 调用 main.registerReceiver(receiver, filter) 注册广播接收器，开始监听。
3. 扫码枪扫描到条码后，系统发送广播 → onReceive 回调被触发 → 从 Intent 中提取 scannerDataKey 对应的值 → 通过 emit('scan', { code }) 传给父组件。
4. stopScan() — 调用 main.unregisterReceiver(receiver) 注销接收器，停止监听。

平台兼容性

组件内部通过 // #ifdef APP-PLUS 条件编译守卫，在非 APP 平台不会执行任何逻辑，不会报错。

注意事项

1. 广播常量依赖：组件的默认 broadcastAction 和 scannerDataKey 依赖于 Seuic 扫码服务的广播约定。如果设备系统升级或更换扫码枪品牌，需确认参数是否匹配。

2. 单实例使用：同一页面只需使用一个 <SeuicScan> 组件实例。多次注册同一个广播接收器可能导致重复接收。

3. 生命周期管理：推荐使用 autoStart: false + onShow/onHide 手动控制，确保：

   • 页面不可见时不监听（省电、避免后台串数据）
   • 多页面切换时，只有当前可见页面的组件在监听

4. 与摄像头扫码共存：本组件专用于激光扫码枪（硬件触发），与 uni.scanCode() 摄像头扫码互不冲突，可在同一页面并存使用。

5. 条件编译：组件的核心逻辑包裹在 // #ifdef APP-PLUS 中，非 APP 平台打包时这些代码不会包含在内，不影响包体积。