更新记录

1.0.0（2026-10-26）

首个版本：广播参数化配置（商米/新大陆/iData/霍尼韦尔/优博讯/斑马 DataWedge 常见默认参数）、统一扫码事件格式、重复过滤与节流（默认全关）、最近事件缓冲、模拟扫码（simulated 标记严格区分）、Android 13+ RECEIVER_EXPORTED 适配、防接收器泄漏、32 项核心逻辑自动化测试。

平台兼容性

uni-app

szhzy-pdabridge PDA 扫码广播统一监听插件

面向仓库管理（WMS）、制造执行（MES）、ERP、固定资产管理与仓库盘点系统的 Android PDA 扫码统一接入 UTS 插件。

各 PDA 厂商的扫码结果广播格式互不相同，本插件通过 Broadcast Action + DataKey 两个参数即可统一接入：一次配置，后续业务代码以统一格式消费扫码事件（内容 / 时间 / 来源标识 / 事件 ID），不再为每个厂商写一套监听逻辑。零权限、零依赖、不依赖任何厂商 SDK 与自建服务器，扫码结果分发全部在设备本地完成。

内置常见厂商参考配置（商米 / 新大陆 / iData / 霍尼韦尔 / 优博讯 / 斑马 DataWedge），并提供调试模式与模拟扫码入口。附带完整的仓库入库扫码演示工程。

⚠️ 购买前必读

1. 本插件仅支持 Android App 平台（面向传统 uni-app Vue3 项目开发；uni-app x 端按兼容模式编写但未实测）。iOS、鸿蒙、Web、小程序均不支持。
2. 适用于支持「广播输出」模式的 PDA / 扫码设备（绝大多数主流 Android PDA 品牌均支持，通常需在厂商扫码设置或工具中开启广播输出）。不支持仅支持键盘模拟输出（HID）的设备做全局监听——键盘模式的接入方式与限制见下文专章。
3. 诚实的验证状态：核心逻辑（配置校验、重复过滤、节流、事件格式）经过 32 项自动化测试；各品牌 PDA 真机广播接收未经作者逐一验证（插件内厂商参数为公开资料整理的常见默认值），购买后请先用 Demo 工程在你的设备上实测，不适配可联系作者处理。
4. 模拟扫码与真实硬件事件严格区分：simulateScan 注入的事件带 simulated: true 标记，用于无硬件时验证业务交互，不代表真实设备行为。
5. 付费版授权与打包规则（DCloud 市场机制）：本插件为付费插件，由插件市场自动加密——普通授权版买家不可见插件源码，需要阅读或修改源码请购买源码授权版；加密插件仅支持云端传统打包，不支持离线打包与安心打包；试用版仅可用于打包自定义基座调试，不能用于正式发布；授权绑定 AppID 与包名，购买后更换任一信息需重新购买授权。

环境要求

真机运行提示：UTS 插件不能在 HBuilderX 标准基座上直接运行。导入插件后，请在 HBuilderX 中执行「运行 → 运行到手机或模拟器 → 制作自定义基座」，基座制作完成后选择「使用自定义基座运行」；正式打包请使用云打包。

快速开始

1. 安装

通过 HBuilderX 将插件导入项目 uni_modules 目录即可，无需申请权限、无需修改 manifest.json。

2. 配置并启动监听

import {
  startListening, stopListening, configure, getStatus,
  destroy, simulateScan, getRecentEvents, getVendorPresets
} from '@/uni_modules/szhzy-pdabridge'

// ① 启动监听（PDA 需先在厂商设置中开启「广播输出」模式）
const res = startListening({
  action: 'com.sunmi.scanner',      // 你的 PDA 扫码广播 Action
  dataKey: 'data',                  // 承载条码内容的 Extra 字段名
  duplicateFilterMs: 0,             // 重复过滤窗口毫秒（0=不过滤，默认值）
  throttleMs: 0,                    // 节流毫秒（0=不节流，默认值）
  debug: false                      // 调试模式（记录最近事件）
}, (event) => {
  // ② 统一格式的扫码事件（连续扫码时每次触发）
  console.log(event.content)        // 条码内容
  console.log(event.timestamp)      // 事件时间（毫秒时间戳）
  console.log(event.source)         // 来源标识（广播 Action）
  console.log(event.eventId)        // 事件 ID（S{时间戳}-{序号}）
  console.log(event.simulated)      // 是否模拟事件（真实硬件事件恒为 false）
})

if (!res.ok) {
  console.error(`[${res.code}] ${res.message}`)
}

3. 组件卸载时销毁（防泄漏，务必执行）

UTS 层无法感知 Vue 组件生命周期，请在页面/组件卸载钩子中调用 destroy()：

import { onUnmounted } from 'vue'
import { destroy } from '@/uni_modules/szhzy-pdabridge'

onUnmounted(() => {
  destroy()   // 注销广播接收器 + 清理事件回调 + 重置全部状态
})

插件同时内置兜底：App 前台 Activity 销毁时自动注销广播接收器。两层机制确保不出现接收器重复注册与内存泄漏。

API 参考

所有同步 API 返回 UTSJSONObject 统一信封 { ok, code, message, ...业务字段 }，不通过 Promise reject 抛业务错误。

startListening(options, onScan)

启动扫码广播监听（连续扫码事件监听入口）。

* options 传 null 时沿用 configure() 已保存的配置；首次启动必须提供 action 与 dataKey。

返回：{ ok, code, message, listening, action, dataKey, duplicateFilterMs, throttleMs, debug }

重复调用安全：内部先注销旧接收器再注册新接收器，绝不出现接收器重复注册；新回调替换旧回调。

stopListening()

停止监听并清理事件回调（配置保留，可再次 startListening 复用）。幂等：未监听时同样返回成功。

configure(options)

更新配置（字段缺省沿用当前值）。监听中支持热更新：自动按新 Action 重新注册接收器，无需先停止。返回值含 reapplied 字段标识是否触发热更新。

destroy()

销毁插件会话：注销接收器、清理回调、重置配置与全部统计。返回销毁前的状态快照（stats 字段）。

getStatus()

获取当前状态与统计（同步）：

{
  listening: boolean,          // 是否监听中
  action: string,              // 当前 Action
  dataKey: string,             // 当前 DataKey
  duplicateFilterMs: number,   // 重复过滤窗口
  throttleMs: number,          // 节流窗口
  debug: boolean,              // 调试模式
  startedAt: number,           // 本次监听启动时间（毫秒，未启动为 0）
  delivered: number,           // 已放行事件总数
  duplicateDropped: number,    // 重复过滤丢弃数
  throttleDropped: number,     // 节流丢弃数
  unmatchedBroadcasts: number, // 收到目标 Action 广播但 dataKey 未命中次数
  pluginVersion: string
}

unmatchedBroadcasts 持续增长说明 Action 配对了、dataKey 配错了——这是排查厂商参数最直接的指标。

getRecentEvents()

获取最近 20 条扫码事件记录（调试面板数据源），每条含：eventId / content / timestamp / source / simulated / delivered / dropReason。被过滤策略丢弃的事件不触发回调，但会记录在此，便于验证过滤行为。

simulateScan(content)

模拟扫码入口（无硬件时验证业务交互）。走与真实广播完全相同的过滤管道；事件 source 为 "simulated"、simulated 为 true，与真实硬件事件严格区分。返回 { ok, delivered, event }，delivered=false 时说明事件被过滤策略丢弃（dropReason 为 duplicate / throttled）。

getVendorPresets()

获取常见厂商广播参数参考配置（见下文配置指南）。

getPluginVersion()

获取插件版本号。

错误码

厂商广播参数配置指南

参数怎么来

1. 查厂商文档或扫码设置工具：PDA 的「扫描设置 / Scanner Settings / DataWedge」等应用中，广播输出模式会标明 Action 与 Extra 字段名；
2. 用本插件调试模式反查：按预设 Action 启动监听，扫码后看 getStatus() 的 unmatchedBroadcasts——增长说明 Action 对了但 dataKey 错了（或反之不增长也无事件则 Action 不对）；
3. 参考下表常见默认值（均为公开集成资料整理，以设备实测为准）：

以上条目可通过 getVendorPresets() 在运行时获取。再次强调：参考配置不构成已逐一真机适配的承诺，不同机型/固件可能不同。

同一 Action 多个 Extra 字段

部分厂商广播附带多个字段（条码内容、码制、时间等）。本插件只按 dataKey 提取条码内容；如需码制等其他信息，建议向厂商确认字段名后在业务层扩展。

重复过滤与节流语义

判定顺序：重复过滤先于节流（同内容同窗口优先判 duplicate）。

重要语义：中间夹了其他条码后，同一条码再扫不会被判重复（A→B→A 快速交替全部放行）——过滤目标是硬件连击，不是人工交替扫码。

时间倒流防御：事件时间戳不递增（<= 上次放行时间）时按窗口内处理（判重复），防御时钟异常。

Android 13+ 注册说明

Android 13（API 33）起，动态注册广播接收器必须显式声明导出行为。PDA 扫码广播由厂商扫码服务（独立应用）发出，本插件在 API 33+ 上以 RECEIVER_EXPORTED 方式注册（低版本走传统注册），开发者无需任何额外处理。此行为已按官方规范实现，未经真机逐一验证（见购买前必读）。

键盘模拟模式（HID）接入示例与限制

部分 PDA（或外接扫码枪）工作在键盘输出（HID）模式：扫码内容以按键序列输入到当前获得焦点的输入框，通常以回车结尾。此模式的正确接入方式是输入框级监听：

<template>
  <!-- 该输入框获得焦点时，键盘模式扫码内容会输入到这里，回车触发 confirm -->
  <input
    v-model="code"
    placeholder="点击此处后用 PDA 扫码"
    confirm-type="done"
    @confirm="onScanInput" />
</template>

<script setup>
import { ref } from 'vue'
const code = ref('')
function onScanInput() {
  const content = code.value.trim()
  if (content) {
    // 与广播监听事件走同一业务处理函数
    handleScan(content)
    code.value = ''
  }
}
</script>

限制（务必知悉）：

• 依赖输入焦点：页面切换、键盘收起、焦点移出输入框后扫码内容丢失；
• 属于输入框 UI 级监听，不是原生全局 HID 监听——本插件不提供、也不虚报全局键盘钩子能力；
• 适用于「扫码枪跟随页面输入框」的简单场景；需要全局免焦点监听时，请在 PDA 设置中切换为广播输出模式并使用本插件广播监听 API。

调试模式与模拟扫码

开启 debug: true 后（或直接调用 getRecentEvents()），插件保留最近 20 条扫码事件记录，每条含：

• 事件时间（timestamp，毫秒时间戳）
• 扫码内容（content）
• 扫码来源（source：广播 Action / simulated）
• 去重情况（delivered 是否放行 + dropReason 丢弃原因：duplicate / throttled）

配合 simulateScan(content) 可在无 PDA 硬件时完整验证：监听启动 → 事件分发 → 重复过滤 → 业务清单更新 的全链路。Demo 工程的「调试面板」即此能力的界面化展示。

常见问题

Q：启动成功但扫码没反应？ 按顺序排查：① PDA 扫码设置中是否已开启「广播输出」模式（很多设备默认键盘模式）；② Action 是否正确（换厂商预设试试）；③ getStatus() 的 unmatchedBroadcasts 是否增长——增长说明广播收到了但 dataKey 配错；④ 仍无事件则 Action 不对，查厂商文档。

Q：一次扫码触发了多次事件？ 这是硬件连击（部分机型单次扫描发多条广播）。设置 duplicateFilterMs: 500 左右即可过滤。

Q：能同时监听多个 Action 吗？ 当前版本单会话监听一个 Action（覆盖绝大多数 PDA 场景，一台设备通常只有一种广播输出）。多 Action 并行监听在版本路线图中。

Q：页面返回后再进入，需要重新 startListening 吗？ stopListening() 或 destroy() 后需要。监听中页面跳转（未销毁组件）则持续有效。

Q：支持 uni-app x 吗？ API 统一以 UTSJSONObject 交互，代码按兼容模式编写；但当前仅在传统 uni-app（Vue3）上完成设计与逻辑级验证，uni-app x 端未实测（市场平台声明中标注为不确定）。

技术支持

• 使用问题与设备适配反馈请通过插件市场页面联系作者；
• 反馈时请提供：PDA 品牌型号、厂商扫码设置截图（广播输出配置）、getStatus() 返回值、HBuilderX 版本与调用代码片段。

更新记录

见 changelog.md。授权条款见 license.md。