@nokecy/qc-ui-components 0.0.0-stage → 2.0.0-beta.1

package/dist/esm/scanCollect/ScanFeedbackInput.js

@@ -0,0 +1,107 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+var _excluded = ["result", "sound", "flashDuration"];
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
+function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
+import { CheckCircleFilled, CloseCircleFilled } from '@ant-design/icons';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import FullScreenAlert from "../fullScreenAlert/index";
+import ScanInput from "./ScanInput";
+import { playScanSound } from "./scanSound";
+
+/** 一次扫码的结果。每次扫码传入新对象即重新触发一次边缘闪动；结果文字保留到下一次传入。 */
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+/** 反馈区预留高度：徽标出现、消失都不推动页面其余内容。 */
+var BADGE_HEIGHT = 48;
+
+/**
+ * 扫码输入框 + 反馈整体组件（规范 §11.1）：
+ * 输入框下方预留固定高度的图标+文字徽标（语义色，保留到下一次扫码），
+ * 屏幕边缘闪动约 1.2 秒后收起，可选提示音。
+ * 边缘闪动层相对最近的定位祖先铺满，宿主需要整屏效果时把它放进整页容器即可。
+ *
+ * @author nokecy
+ */
+var ScanFeedbackInput = function ScanFeedbackInput(_ref) {
+  var _result$message;
+  var result = _ref.result,
+    _ref$sound = _ref.sound,
+    sound = _ref$sound === void 0 ? false : _ref$sound,
+    _ref$flashDuration = _ref.flashDuration,
+    flashDuration = _ref$flashDuration === void 0 ? 1200 : _ref$flashDuration,
+    inputProps = _objectWithoutProperties(_ref, _excluded);
+  // 每次拿到新的 result 递增，作为闪动层的 key 使其重新挂载、从头计时。
+  var _useState = useState({
+      id: 0,
+      active: false
+    }),
+    _useState2 = _slicedToArray(_useState, 2),
+    flash = _useState2[0],
+    setFlash = _useState2[1];
+  var first = useRef(true);
+  useEffect(function () {
+    // 首次渲染时的 result 视为历史结果（徽标显示），不闪、不响。
+    if (first.current) {
+      first.current = false;
+      return;
+    }
+    if (!result) return;
+    setFlash(function (prev) {
+      return {
+        id: prev.id + 1,
+        active: true
+      };
+    });
+    if (sound) playScanSound(result.type);
+  }, [result]); // eslint-disable-line react-hooks/exhaustive-deps
+  var onFlashChange = useCallback(function (active) {
+    return setFlash(function (prev) {
+      return _objectSpread(_objectSpread({}, prev), {}, {
+        active: active
+      });
+    });
+  }, []);
+  var isError = (result === null || result === void 0 ? void 0 : result.type) === 'error';
+  return /*#__PURE__*/_jsxs("div", {
+    className: "scanFeedbackInput",
+    children: [/*#__PURE__*/_jsx(ScanInput, _objectSpread({}, inputProps)), /*#__PURE__*/_jsx("div", {
+      className: "scanFeedbackBadge",
+      role: "status",
+      "aria-live": "polite",
+      style: {
+        minHeight: BADGE_HEIGHT,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 8,
+        fontSize: 20,
+        fontWeight: 700,
+        color: result ? isError ? 'var(--ant-color-error, red)' : 'var(--ant-color-success, green)' : undefined
+      },
+      children: result ? /*#__PURE__*/_jsxs(_Fragment, {
+        children: [isError ? /*#__PURE__*/_jsx(CloseCircleFilled, {}) : /*#__PURE__*/_jsx(CheckCircleFilled, {}), /*#__PURE__*/_jsx("span", {
+          children: (_result$message = result.message) !== null && _result$message !== void 0 ? _result$message : isError ? '失败' : '成功'
+        })]
+      }) : null
+    }), result ? /*#__PURE__*/_jsx(FullScreenAlert, {
+      active: flash.active,
+      type: result.type,
+      duration: flashDuration,
+      showIcon: false,
+      onChange: onFlashChange
+    }, flash.id) : null]
+  });
+};
+export default ScanFeedbackInput;

package/dist/esm/scanCollect/ScanInput.d.ts

@@ -0,0 +1,21 @@
+import type { InputProps } from 'antd';
+import React from 'react';
+export interface ScanInputProps extends Omit<InputProps, 'value' | 'defaultValue' | 'onChange' | 'onPressEnter'> {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string | undefined) => void;
+    /** 回车时拿到输入框里的原文；之后输入框清空并回焦，等下一枪 */
+    onPressEnter?: (value: string | undefined) => void;
+    /** 允许 Ctrl+C / Ctrl+V 与右键菜单。默认禁止，逼着走扫码，防止手工粘贴错码 */
+    allowPaste?: boolean;
+}
+/**
+ * 扫码输入框（Formily 受控，可直接作 schema 的 x-component）。
+ *
+ * 回车后**清空并回焦**：清空不回焦的话，操作员每扫完一枪都得用鼠标点回这个框，
+ * 第二枪根本打不进去，只会被当成扫码枪坏了。
+ *
+ * @author nokecy
+ */
+declare const ScanInput: React.FC<ScanInputProps>;
+export default ScanInput;

package/dist/esm/scanCollect/ScanInput.js

@@ -0,0 +1,81 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+var _excluded = ["onPressEnter", "allowPaste", "onKeyDown", "onContextMenu", "value", "defaultValue", "onChange"];
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
+function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
+import { Input } from '@nokecy/formily-antd';
+import { useControllableValue } from 'ahooks';
+import React, { useRef } from 'react';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 扫码输入框（Formily 受控，可直接作 schema 的 x-component）。
+ *
+ * 回车后**清空并回焦**：清空不回焦的话，操作员每扫完一枪都得用鼠标点回这个框，
+ * 第二枪根本打不进去，只会被当成扫码枪坏了。
+ *
+ * @author nokecy
+ */
+var ScanInput = function ScanInput(props) {
+  var onPressEnterProp = props.onPressEnter,
+    _props$allowPaste = props.allowPaste,
+    allowPaste = _props$allowPaste === void 0 ? false : _props$allowPaste,
+    onKeyDownProp = props.onKeyDown,
+    onContextMenuProp = props.onContextMenu,
+    _value = props.value,
+    _defaultValue = props.defaultValue,
+    _onChange = props.onChange,
+    rest = _objectWithoutProperties(props, _excluded);
+  var _useControllableValue = useControllableValue(props),
+    _useControllableValue2 = _slicedToArray(_useControllableValue, 2),
+    state = _useControllableValue2[0],
+    setState = _useControllableValue2[1];
+  var inputRef = useRef(null);
+  var onKeyDown = function onKeyDown(e) {
+    if (!allowPaste && e.ctrlKey && (e.key === 'c' || e.key === 'v' || e.keyCode === 67 || e.keyCode === 86)) {
+      e.preventDefault();
+    }
+    onKeyDownProp === null || onKeyDownProp === void 0 || onKeyDownProp(e);
+  };
+  var onContextMenu = function onContextMenu(e) {
+    if (!allowPaste) e.preventDefault();
+    onContextMenuProp === null || onContextMenuProp === void 0 || onContextMenuProp(e);
+  };
+  var onPressEnter = function onPressEnter() {
+    onPressEnterProp === null || onPressEnterProp === void 0 || onPressEnterProp(state);
+    setState(undefined);
+
+    // 放到下一个宏任务：回调若打开了弹窗，此时焦点已经交给弹窗，就不该再抢回来。
+    // 只有焦点还留在本框、或掉到 body 上时才回焦。
+    setTimeout(function () {
+      var _inputRef$current;
+      var el = (_inputRef$current = inputRef.current) === null || _inputRef$current === void 0 ? void 0 : _inputRef$current.input;
+      if (!(el !== null && el !== void 0 && el.isConnected)) return;
+      var active = document.activeElement;
+      if (active === el || active === document.body || active === null) {
+        var _inputRef$current2, _inputRef$current2$fo;
+        (_inputRef$current2 = inputRef.current) === null || _inputRef$current2 === void 0 || (_inputRef$current2$fo = _inputRef$current2.focus) === null || _inputRef$current2$fo === void 0 || _inputRef$current2$fo.call(_inputRef$current2);
+      }
+    }, 0);
+  };
+  return /*#__PURE__*/_jsx(Input, _objectSpread(_objectSpread({}, rest), {}, {
+    ref: inputRef,
+    value: state,
+    onChange: function onChange(e) {
+      return setState(e !== null && e !== void 0 && e.target ? e.target.value : e);
+    },
+    onKeyDown: onKeyDown,
+    onContextMenu: onContextMenu,
+    onPressEnter: onPressEnter
+  }));
+};
+export default ScanInput;

package/dist/esm/scanCollect/focus.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 扫码框回焦。
+ *
+ * 采集岗一小时扫几百枪，扫码框丢了焦点，下一枪就打到别处去了。但焦点也不能乱抢：
+ * 扫错一枪弹出确认框时把光标夺回扫码框，操作员就没法在弹窗里操作。
+ *
+ * @author nokecy
+ */
+/**
+ * 当前焦点能否让给扫码框。
+ *
+ * 能让：焦点在 body 上（被点掉了）、已在扫码框里，或停在页面上的按钮上——
+ * 点完「开始采集」焦点留在按钮上，扫码枪的回车会直接再按一次这个按钮（变成「停止采集」）。
+ * 不能让：焦点在浮层里，或在页面上别的输入框里（操作员正在手工填写）。
+ */
+export declare const canTakeFocus: (target: Element, active: Element | null) => boolean;
+/**
+ * 延时把焦点交给 id 为 `id` 的元素（Formily 字段的 id 就是字段名）。
+ * 延时是为了等提交后的弹窗、重渲染先落地，再判断焦点该不该抢。
+ */
+export declare function focusOn(id: string, delay?: number): void;
+/** 让 id 为 `id` 的元素失焦。 */
+export declare function blurOn(id: string): void;

package/dist/esm/scanCollect/focus.js

@@ -0,0 +1,47 @@
+/**
+ * 扫码框回焦。
+ *
+ * 采集岗一小时扫几百枪，扫码框丢了焦点，下一枪就打到别处去了。但焦点也不能乱抢：
+ * 扫错一枪弹出确认框时把光标夺回扫码框，操作员就没法在弹窗里操作。
+ *
+ * @author nokecy
+ */
+
+/** 弹窗、抽屉、气泡、下拉等浮层：焦点在这些容器里时不抢。 */
+var OVERLAY_SELECTOR = '[role="dialog"], .ant-modal-wrap, .ant-drawer, .ant-popover, .ant-select-dropdown, .ant-picker-dropdown, .ant-dropdown';
+var isButtonLike = function isButtonLike(el) {
+  return el.matches('button, a[href], [role="button"]');
+};
+
+/**
+ * 当前焦点能否让给扫码框。
+ *
+ * 能让：焦点在 body 上（被点掉了）、已在扫码框里，或停在页面上的按钮上——
+ * 点完「开始采集」焦点留在按钮上，扫码枪的回车会直接再按一次这个按钮（变成「停止采集」）。
+ * 不能让：焦点在浮层里，或在页面上别的输入框里（操作员正在手工填写）。
+ */
+export var canTakeFocus = function canTakeFocus(target, active) {
+  if (!active || active === document.body || active === target || target.contains(active)) return true;
+  if (active.closest(OVERLAY_SELECTOR)) return false;
+  return isButtonLike(active);
+};
+
+/**
+ * 延时把焦点交给 id 为 `id` 的元素（Formily 字段的 id 就是字段名）。
+ * 延时是为了等提交后的弹窗、重渲染先落地，再判断焦点该不该抢。
+ */
+export function focusOn(id) {
+  var delay = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 300;
+  setTimeout(function () {
+    var el = document.getElementById(id);
+    if (!(el !== null && el !== void 0 && el.isConnected)) return;
+    if (!canTakeFocus(el, document.activeElement)) return;
+    el.focus();
+  }, delay);
+}
+
+/** 让 id 为 `id` 的元素失焦。 */
+export function blurOn(id) {
+  var _document$getElementB;
+  (_document$getElementB = document.getElementById(id)) === null || _document$getElementB === void 0 || _document$getElementB.blur();
+}

package/dist/esm/scanCollect/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 扫码采集的通用部件：扫码输入框、串行提交队列、请求时序门、扫码框回焦。
+ * 只含与业务无关的交互机制；采集规则、权限、锁定解锁等留在业务页。
+ *
+ * @author nokecy
+ */
+export { default as ScanInput } from './ScanInput';
+export type { ScanInputProps } from './ScanInput';
+export { default as ScanFeedbackInput } from './ScanFeedbackInput';
+export type { ScanFeedbackInputProps, ScanResult } from './ScanFeedbackInput';
+export { playScanSound } from './scanSound';
+export type { ScanSoundType } from './scanSound';
+export { default as usePromiseQueue } from './usePromiseQueue';
+export type { PromiseQueue, PromiseQueueOptions, QueueTask } from './usePromiseQueue';
+export { createRequestGate } from './requestGate';
+export type { RequestGate } from './requestGate';
+export { blurOn, canTakeFocus, focusOn } from './focus';

package/dist/esm/scanCollect/index.js

@@ -0,0 +1,12 @@
+/**
+ * 扫码采集的通用部件：扫码输入框、串行提交队列、请求时序门、扫码框回焦。
+ * 只含与业务无关的交互机制；采集规则、权限、锁定解锁等留在业务页。
+ *
+ * @author nokecy
+ */
+export { default as ScanInput } from "./ScanInput";
+export { default as ScanFeedbackInput } from "./ScanFeedbackInput";
+export { playScanSound } from "./scanSound";
+export { default as usePromiseQueue } from "./usePromiseQueue";
+export { createRequestGate } from "./requestGate";
+export { blurOn, canTakeFocus, focusOn } from "./focus";

package/dist/esm/scanCollect/requestGate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 请求时序门：每次发请求取一个序号，回执时只认最新序号。
+ *
+ * 扫码采集页上「回车解析工单」与「切换工序取清单」都是异步的，先发的请求可能后到，
+ * 把新结果覆盖成旧结果（例如减配清单被上一张工单的空清单冲掉）。回执前问一句 `isCurrent(id)`，
+ * 不是最新的就丢弃。`invalidate()` 让所有在途请求作废（回车、失焦、卸载、重置时调用）。
+ *
+ * @author nokecy
+ */
+export interface RequestGate {
+    /** 发请求前取号 */
+    next: () => number;
+    /** 回执时判断这个号是否仍是最新 */
+    isCurrent: (id: number) => boolean;
+    /** 作废所有在途请求 */
+    invalidate: () => void;
+}
+export declare const createRequestGate: () => RequestGate;

package/dist/esm/scanCollect/requestGate.js

@@ -0,0 +1,24 @@
+/**
+ * 请求时序门：每次发请求取一个序号，回执时只认最新序号。
+ *
+ * 扫码采集页上「回车解析工单」与「切换工序取清单」都是异步的，先发的请求可能后到，
+ * 把新结果覆盖成旧结果（例如减配清单被上一张工单的空清单冲掉）。回执前问一句 `isCurrent(id)`，
+ * 不是最新的就丢弃。`invalidate()` 让所有在途请求作废（回车、失焦、卸载、重置时调用）。
+ *
+ * @author nokecy
+ */
+
+export var createRequestGate = function createRequestGate() {
+  var seq = 0;
+  return {
+    next: function next() {
+      return ++seq;
+    },
+    isCurrent: function isCurrent(id) {
+      return id === seq;
+    },
+    invalidate: function invalidate() {
+      seq += 1;
+    }
+  };
+};

package/dist/esm/scanCollect/scanSound.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 扫码提示音：用 WebAudio 合成，不依赖音频资源文件。
+ * AudioContext 是模块级单例——浏览器限制同一页面可创建的上下文数量，且需要在用户手势后才能出声，
+ * 每次扫码都 new 一个既浪费也会被拒绝。
+ *
+ * @author nokecy
+ */
+export type ScanSoundType = 'success' | 'error';
+/**
+ * 播放一次扫码提示音。静默失败：没有 WebAudio、上下文被浏览器挂起且无法恢复时直接忽略，不影响采集流程。
+ * @returns 是否已提交播放
+ */
+export declare function playScanSound(type: ScanSoundType): boolean;
+/** 仅测试用：丢弃共享上下文。 */
+export declare function resetScanSoundForTest(): void;

package/dist/esm/scanCollect/scanSound.js

@@ -0,0 +1,84 @@
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+/**
+ * 扫码提示音：用 WebAudio 合成，不依赖音频资源文件。
+ * AudioContext 是模块级单例——浏览器限制同一页面可创建的上下文数量，且需要在用户手势后才能出声，
+ * 每次扫码都 new 一个既浪费也会被拒绝。
+ *
+ * @author nokecy
+ */
+
+var sharedContext;
+
+/** 取（或创建）共享的 AudioContext；环境不支持 WebAudio 时返回 undefined。 */
+function getAudioContext() {
+  var _window$AudioContext;
+  if (sharedContext) return sharedContext;
+  var Ctor = typeof window === 'undefined' ? undefined : (_window$AudioContext = window.AudioContext) !== null && _window$AudioContext !== void 0 ? _window$AudioContext : window.webkitAudioContext;
+  if (!Ctor) return undefined;
+  try {
+    sharedContext = new Ctor();
+  } catch (_unused) {
+    return undefined;
+  }
+  return sharedContext;
+}
+
+/** 每种结果的音符序列：[频率 Hz, 起点 s, 时长 s]。成功一声高短音；失败两声低音，听感上与成功明显不同。 */
+var TONES = {
+  success: [[880, 0, 0.12]],
+  error: [[220, 0, 0.18], [220, 0.26, 0.18]]
+};
+
+/**
+ * 播放一次扫码提示音。静默失败：没有 WebAudio、上下文被浏览器挂起且无法恢复时直接忽略，不影响采集流程。
+ * @returns 是否已提交播放
+ */
+export function playScanSound(type) {
+  var ctx = getAudioContext();
+  if (!ctx) return false;
+  try {
+    var _ctx$resume;
+    if (ctx.state === 'suspended') void ((_ctx$resume = ctx.resume) === null || _ctx$resume === void 0 ? void 0 : _ctx$resume.call(ctx));
+    var now = ctx.currentTime;
+    var _iterator = _createForOfIteratorHelper(TONES[type]),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var _step$value = _slicedToArray(_step.value, 3),
+          frequency = _step$value[0],
+          offset = _step$value[1],
+          length = _step$value[2];
+        var osc = ctx.createOscillator();
+        var gain = ctx.createGain();
+        osc.type = type === 'error' ? 'square' : 'sine';
+        osc.frequency.value = frequency;
+        // 起止做短包络，避免爆音。
+        gain.gain.setValueAtTime(0.0001, now + offset);
+        gain.gain.exponentialRampToValueAtTime(0.2, now + offset + 0.01);
+        gain.gain.exponentialRampToValueAtTime(0.0001, now + offset + length);
+        osc.connect(gain);
+        gain.connect(ctx.destination);
+        osc.start(now + offset);
+        osc.stop(now + offset + length + 0.02);
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    return true;
+  } catch (_unused2) {
+    return false;
+  }
+}
+
+/** 仅测试用：丢弃共享上下文。 */
+export function resetScanSoundForTest() {
+  sharedContext = undefined;
+}

package/dist/esm/scanCollect/usePromiseQueue.d.ts

@@ -0,0 +1,34 @@
+/** 队列里的一个任务：返回 Promise 或普通值都可以，同步抛错按失败处理。 */
+export type QueueTask<T = any> = () => T | Promise<T>;
+export interface PromiseQueueOptions {
+    /**
+     * 任务失败后丢弃后面还没开始的任务，丢弃条数计入 `skipped`。
+     * 连续扫码时第一枪报错，后面排着的几枪多半是同一个问题，接着跑只会刷出一串报错。
+     */
+    abortOnError?: boolean;
+}
+export interface PromiseQueue<T = any, E = any> {
+    /** 已成功任务的返回值，按完成顺序 */
+    result: T[];
+    /** 已失败任务的错误，按完成顺序 */
+    errors: E[];
+    /** 还没完成的任务（含正在执行的那个）；`queue.length > 0` 即「还有活没干完」 */
+    queue: QueueTask<T>[];
+    /** 等同 `queue.length`，用于遮罩上的「还有 N 条待完成」 */
+    pending: number;
+    /** `abortOnError` 时因前面失败而丢弃的任务数，累计到 `reset()` */
+    skipped: number;
+    /** 追加任务；同一时刻连续追加也会按顺序全部执行 */
+    addQueue: (task: QueueTask<T>) => void;
+    /** 丢弃还没开始的任务，并清空 result、errors、skipped（正在执行的任务照常跑完） */
+    reset: () => void;
+}
+/**
+ * 串行任务队列：扫码采集「扫一枪排一条，一条一条提交」。
+ *
+ * 扫码枪比服务端快，连续扫的条码必须排队按顺序提交，否则后端会并发处理同一张工单。
+ * 任务返回非 Promise（如扫码枪空回车时回调直接 return）或同步抛错都不会卡住队列。
+ *
+ * @author nokecy
+ */
+export default function usePromiseQueue<T = any, E = any>(options?: PromiseQueueOptions): PromiseQueue<T, E>;