NocoBase ScanInput 组件详解表单内嵌二维码/条形码扫码输入框的完整实现【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobaseScanInput是 NocoBase client-v2 提供的带扫码按钮的 AntdInput组件用于在表单字段中直接完成二维码、条形码扫描并回填值。它优先调用移动端原生window.JsBridge.invoke({ action: scan })无 JSBridge 时自动降级为浏览器摄像头扫码界面内置 HTML5 全屏扫码器支持从相册选图识别。读完本文你将掌握ScanInput的引入方式、在表单中的用法、全部 API 参数语义、底层扫码链路JsBridge 优先 → 摄像头 → 相册图片以及浏览器权限与 HTTPS 环境约束并能直接将其应用到自己的 NocoBase 插件表单中。一、组件定位与适用场景ScanInput位于nocobase/client-v2包属于表单共享组件其本质是带扫码按钮的 AntdInput。典型应用场景包括扫码录入设备编号、SN 序列号、订单号等一维/二维编码在移动端如 PWA、企业微信/钉钉 WebView中调用系统原生扫码能力在 PC 浏览器中通过摄像头或相册图片完成识别。从源码结构看组件由三部分组成packages/core/client-v2/src/components/form/ScanInput文件职责ScanInput.tsx对外暴露的输入框组件负责扫码按钮、JsBridge 调用与全屏扫码器编排CodeScanner.tsx全屏扫码 UI黑色遮罩 取景框 相册按钮基于html5-qrcode渲染useCodeScanner.ts扫码核心逻辑 Hook摄像头启停、视频帧抽帧、jsQR / ZXing-WASM 解码、图片多尺寸解码ScanBox.tsx取景框视觉组件zxingWasmDecoder.ts基于 ZXing-WASM 的二维码解码封装主要服务 iOS Safari 场景types.tsCodeFormatsToSupport类型即Html5QrcodeSupportedFormats[]组件入口在 index.ts同时导出了CodeScanner、ScanInput与类型因此你既可以组合使用ScanInput也可以只用底层的CodeScanner。二、基本用法在表单字段中嵌入扫码输入2.1 最小示例在 React 组件中直接引入并使用import { ScanInput } from nocobase/client-v2; import { Form } from antd; Form.Item namecode label{t(Code)} ScanInput placeholder{t(Scan or input code)} / /Form.ItemScanInput与普通 AntdInput的用法一致可直接放入Form.Item作为表单控件提交时code字段的值即为手动输入或扫码得到的文本。2.2 受控用法与 onChange 的双重形态官方交互示例位于 docs/cn/shared-components/_demos/scan-input.tsx展示了受控模式下的典型写法import React, { useState } from react; import { ScanInput } from nocobase/client-v2; import { Space, Typography } from antd; export default function ScanInputDemo() { const [value, setValue] useState(); return ( Space directionvertical style{{ width: 360 }} ScanInput value{value} placeholderScan or input code onChange{(next) { if (typeof next string) { setValue(next); } else { setValue(next.target.value); } }} / Typography.Text typesecondary Current value: {value || -} /Typography.Text /Space ); }注意onChange的回调参数有两种形态需要分支处理扫码成功时传入string识别出的文本手动输入时传入React.ChangeEventHTMLInputElement原始输入事件。这一行为在源码 ScanInput.tsx 中有明确对应handleScanSuccess直接调用onChange?.(text)而handleInputChange调用onChange?.(event)。三、API 参数详解3.1 组件专属参数参数类型默认值说明disableManualInputbooleanfalse是否禁用手动输入开启后输入框只读readOnlyenableScanboolean-保留参数当前组件始终渲染扫码按钮formatsToSupportHtml5QrcodeSupportedFormats[]内置常用二维码和条形码格式限定识别格式onChange(value: string \| ChangeEventHTMLInputElement) void-扫码成功时传字符串手动输入时传原始事件其余参数全部继承 AntdInput的InputPropsplaceholder、disabled、value、suffix、readOnly、onFocus等组件类型定义见 ScanInput.tsxexport type ScanInputProps OmitInputProps, onChange { disableManualInput?: boolean; enableScan?: boolean; formatsToSupport?: CodeFormatsToSupport; onChange?: (value: string | React.ChangeEventHTMLInputElement) void; };3.2 默认支持的识别格式DEFAULT_CODE_FORMATS定义于 useCodeScanner.ts内置了 12 种常用格式export const DEFAULT_CODE_FORMATS: CodeFormatsToSupport [ Html5QrcodeSupportedFormats.QR_CODE, Html5QrcodeSupportedFormats.CODE_128, Html5QrcodeSupportedFormats.CODE_39, Html5QrcodeSupportedFormats.CODE_93, Html5QrcodeSupportedFormats.CODABAR, Html5QrcodeSupportedFormats.EAN_13, Html5QrcodeSupportedFormats.EAN_8, Html5QrcodeSupportedFormats.ITF, Html5QrcodeSupportedFormats.UPC_A, Html5QrcodeSupportedFormats.UPC_E, Html5QrcodeSupportedFormats.DATA_MATRIX, Html5QrcodeSupportedFormats.PDF_417, ];覆盖了二维码QR_CODE、DATA_MATRIX、PDF_417与常见一维条形码CODE_128/39/93、EAN-13/8、ITF、UPC-A/E、Codabar。如需限定识别范围可通过formatsToSupport传入html5-qrcode的枚举值数组传入后该数组会透传给Html5Qrcode实例的formatsToSupport配置见 useCodeScanner.ts。3.3 关键交互行为扫码按钮始终渲染enableScan为保留参数不影响渲染按钮带Scan to input的 Tooltip 与aria-label。disabled与disableManualInput互不干扰字段disabled时扫码按钮一并禁用而仅开启disableManualInput时输入框只读但扫码按钮仍可点击——对应测试用例 ScanInput.test.tsx 中 keeps scan available when manual input is disabled。点击扫码按钮不会抢焦点源码通过suppressInputFocusRef标记 onPointerDownCapture上preventDefault/stopPropagation并主动blur()输入框避免移动端键盘弹出遮挡扫码界面onFocus在此场景下不会被触发有对应测试 opens scanner on pointer down without focusing the input。四、扫码链路从 JsBridge 到浏览器摄像头openScanner的逻辑ScanInput.tsx遵循原生优先、浏览器兜底的策略点击/按下扫码按钮pointerdown与click两条路径都做了拦截读取window.JsBridge若存在invoke方法则调用jsBridge.invoke({ action: scan }, callback)进入移动端原生扫码否则将scanVisible置为true渲染CodeScanner全屏扫码器进入浏览器摄像头扫码。JsBridge 回调的数据可以是字符串也可以是{ url, text, value }对象getJsBridgeScanText会依次取url → text → valueScanInput.tsx。测试用例 ScanInput.test.tsx 中模拟了JsBridge.invoke返回{ url: BRIDGE-CODE }的场景验证最终onChange收到字符串BRIDGE-CODE且不再打开浏览器扫码器。五、底层 CodeScanner 全屏扫码器CodeScannerCodeScanner.tsx是独立可复用的全屏扫码组件通过ReactDOM.createPortal渲染到document.bodyCodeScanner formatsToSupport{formatsToSupport} visible{scanVisible} onClose{() setScanVisible(false)} onScanSuccess{handleScanSuccess} /其 UI 与能力包括全屏黑色遮罩居中放大预览固定渲染宽度SCANNER_RENDER_WIDTH 1280按视口比例缩放左上角关闭按钮底部提供相册按钮取景框ScanBox尺寸由getCodeScanBoxSize计算宽不超过视口 90%上限 1152px、高不超过视口 70%上限 540px相机可用性检测打开时先调用Html5Qrcode.getCameras()无摄像头或权限被拒会弹出错误提示NotFoundError→ No camera device detected、NotAllowedError→ 未授权提示并自动关闭相册图片识别支持上传图片识别超过 10MBMAX_CODE_IMAGE_SIZE会提示先压缩扫码成功或失败后自动关闭/提示。相关组件文档CodeScanner 提供只使用底层全屏扫码器的用法见 scan-input.md 相关链接。5.1 摄像头扫码的双解码器设计useCodeScanneruseCodeScanner.ts同时启用两套解码通道这是为兼容 Safari/iOS 所做的特殊设计html5-qrcode 主通道scannerInstance.start({ facingMode: environment }, ...)以 8fps 帧率、1920×1080理想分辨率启动摄像头回调即识别结果jsQR 抽帧辅助通道startLiveQrScan以LIVE_QR_SCAN_INTERVAL 120ms为间隔从video抽帧绘制到 canvas用jsQR解码。iOS Safari 上改为IOS_ZXING_SCAN_INTERVAL 200ms且改用 ZXing-WASMscanQrVideoFrameWithZxingWasm解码并限制帧尺寸最大 1280×720以规避 iOS 上 html5-qrcode 的兼容问题连续对焦增强enableContinuousFocus检测摄像头是否支持focusMode: continuous支持则应用该约束改善扫码对焦体验。5.2 相册图片的多尺寸、多变换解码上传图片时scanFileWithJsQR/scanFileV2组件会先按[3200, 2400, 1600, 1000]尺寸梯度缩放生成多个图像变体再对每个变体依次应用 7 组对比度/阈值变换QR_SCAN_IMAGE_TRANSFORMS最后用jsQR解码从而显著提升模糊、反光、偏色图片的识别成功率。Safari 浏览器优先走 jsQR 通道失败后回退到html5-qrcode的scanFileV2保证条形码上传在 Safari 中仍然可用。六、在表单中的完整接入示例结合上述 API一个只扫码、不允许手动输入的字段可以这样写import { ScanInput } from nocobase/client-v2; import { Form, Button } from antd; import { Html5QrcodeSupportedFormats } from html5-qrcode; const formats [ Html5QrcodeSupportedFormats.QR_CODE, Html5QrcodeSupportedFormats.CODE_128, Html5QrcodeSupportedFormats.EAN_13, ]; export function ScanOnlyForm() { const [form] Form.useForm(); const handleSubmit async () { const { code } await form.validateFields(); console.log(scanned / entered code:, code); }; return ( Form form{form} onFinish{handleSubmit} layoutvertical style{{ width: 360 }} Form.Item namecode label设备编码 rules{[{ required: true, message: 请扫码或输入编码 }]} ScanInput placeholder扫码或手动输入 disableManualInput{false} formatsToSupport{formats} / /Form.Item Button typeprimary htmlTypesubmit提交/Button /Form ); }若业务要求设备编码只能由扫码产生把disableManualInput设为true即可让输入框只读扫码按钮仍然可用。七、注意事项与排障清单:::warning 注意 浏览器扫码依赖摄像头权限和 HTTPS 环境。本地调试或移动端 WebView 中遇到权限问题时优先检查浏览器权限、协议和 JSBridge 注入情况。 :::结合实际源码给出以下排障顺序移动端 WebView 扫码无反应优先检查宿主 App 是否注入了window.JsBridge且其invoke({ action: scan })回调是否返回了可识别的字符串/对象url/text/value浏览器摄像头打不开检查页面协议是否为https://getUserMedia在非安全上下文不可用、浏览器站点权限中是否允许摄像头访问提示未授权使用摄像头NotAllowedError引导用户在浏览器地址栏/设置中重新授权提示未检测到摄像头NotFoundError确认设备存在可用摄像头扫码识别率低可适当缩小formatsToSupport范围、保证码面平整清晰或优先使用相册图片识别。八、总结ScanInput是 NocoBase 表单体系中一个开箱即用的扫码输入组件API 完全兼容 AntdInput通过disableManualInput可一键切换扫码专用模式底层按移动端 JsBridge 原生扫码 → 浏览器摄像头 → 相册图片三级链路降级并针对 iOS Safari 做了 ZXing-WASM 双解码器兜底。对于需要在 NocoBase 插件或业务表单中快速接入条码/二维码录入的开发者直接引入nocobase/client-v2的ScanInput即可无需自行封装摄像头与解码逻辑如需更底层的控制也可以单独复用CodeScanner组件参见 code-scanner 文档。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考