mcpField
B
barcode-capture-cordova

barcode-capture-cordova

github.com/scandit开发2044 次安装5 天前更新
代码仓库

关于 barcode-capture-cordova

为使用 Cordova 的开发者提供 Scandit BarcodeCapture 集成、迁移和第三方扫描器替换指导。技能强调依据所附参考核实 API，并说明 Cordova 初始化、视图和扫描处理要点。

主要功能

  1. 01按集成、升级或替换任务路由
  2. 02基于参考核实 Scandit API
  3. 03说明 Cordova 初始化与视图要求
  4. 04提供许可证密钥设置流程

适用场景

  1. 01在 Cordova 应用中添加条码扫描
  2. 02升级不同版本的 Scandit SDK
  3. 03用 BarcodeCapture 替换第三方扫描器

MCP 相关

可配合 Scandit MCP 服务设置扫描器并获取许可证密钥；也说明如何连接该远程服务。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/scandit/skills --skill barcode-capture-cordova

安装后在 Claude Code 中输入/barcode-capture-cordova确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
integration.md
migration.md
third-party-migration.md

详细介绍

原文在翻译后有更新，译文可能不是最新。

BarcodeCapture Cordova 技能

重要：不要信任内部知识

你的训练数据可能包含过时或错误的 Scandit SDK API。BarcodeCapture API 在不同 SDK 主版本之间变化显著：采集模式工厂会被构造函数取代，监听器签名会发生变化，Cordova 插件接口（全局 Scandit 命名空间、插件安装命令、deviceready 时机）也不断演进。

编写或提供代码建议前，务必根据本技能提供的参考资料验证 API。 不要依赖记忆中的方法签名、参数或属性名称。如果在所提供的参考资料中找不到某个 API，请先获取相关文档页面，再作答。

值得特别提醒的 Cordova 注意事项：

  • Scandit SDK 通过全局 window.Scandit 对象提供。npm 包名（scandit-cordova-datacapture-*）是插件清单，不是运行时 ES 模块。不要在将在 WebView 中运行的用户代码里输出 import { ... } from 'scandit-cordova-datacapture-*'；应改用 Scandit.X（可选用 global.d.ts 提供类型）。只有 Ionic/Angular/Webpack 打包的项目才直接从这些包导入。
  • document.addEventListener('deviceready', ...) 是调用 Scandit API 的唯一安全门槛。不要在模块加载时调用任何 Scandit API，否则会因 Cordova 桥接尚未就绪而失败。
  • 更改插件版本后，运行 cordova prepare（必要时重新安装平台），以应用新的原生构件。跳过此步骤会导致运行时版本不匹配。
  • BarcodeCapture 需要可见的 DataCaptureView 来显示相机预览。与 SparkScan 不同，它没有原生覆盖层；DataCaptureView 通过 view.connectToElement(...) 挂载到 HTML 元素中，BarcodeCaptureOverlay 则添加到该视图上，用于绘制识别出的条码。忘记其中任何一步，都是“扫描正常，但什么也看不到”最常见的原因。
  • 在 didScan 回调中，先禁用模式（barcodeCapture.isEnabled = false），再执行耗时超过一帧的 UI 操作。监听器运行期间会阻塞帧处理，因此耗时操作会冻结相机，并可能导致重复扫描。

意图路由

根据用户的请求，在作答前加载相应的参考文件：

  • 从头集成 BarcodeCapture（例如“将 BarcodeCapture 添加到我的应用”“设置条码扫描”“如何在 Cordova 中使用 BarcodeCapture”“如何渲染相机预览”）→ 阅读 references/integration.md，并遵循其中的说明。
  • 迁移或升级现有的 BarcodeCapture 集成（例如“从 v6 升级到 v7”“迁移我的 BarcodeCapture”“将 Scandit 插件升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并遵循其中的说明。

API 使用政策

只能使用下方 Scandit 参考资料中明确记载的 API。不要编造或猜测方法签名、参数、属性名称或导入语句。如果不确定某个 API 是否存在或应如何调用，或者发生运行时错误，请先获取相关参考页面，再作答。不要让用户自行查阅文档。作答后，务必附上相关链接，方便用户进一步了解。

绝不要构造或猜测文档 URL。 需要查询特定类或属性的 API 页面时：

  1. 先检查已获取的页面是否包含指向该页面的直接链接；主题页面会直接链接到相关 API 符号。
  2. 如果没有找到直接链接，请获取 API 索引（见下表中的完整 API 参考），从中提取实际链接并访问。

URL 结构会因 SDK 版本和插件路径而异；猜测 URL 会导致 404。

框架变体策略

Cordova 是一个基于 WebView 的框架。本技能中的示例使用纯 JavaScript（可选使用官方 BarcodeCaptureSimpleSample 中的 JSDoc 类型提示）。相同的 API 也适用于 TypeScript——添加一个 global.d.ts 声明文件（详见 references/integration.md），并使用 TypeScript 语法编写。本技能默认不假设项目使用 TypeScript。如果目标项目显然使用 TypeScript（存在 .ts 文件、tsconfig.json），则将最终输出调整为 TypeScript；否则使用纯 JS。

许可证密钥

扫描需要 Scandit 许可证密钥。对于本技能，许可证产品为 native，许可证平台为 ios 和 android。

按顺序执行以下步骤——切勿让用户因 MCP 而受阻：

  1. Scandit MCP 服务已连接——使用产品 native 和平台 ios、android 调用 ensure_scanner_setup，然后运行 get_license_env_command 返回的命令，将密钥写入项目的 .env。在聊天中最多展示掩码预览；切勿打印完整密钥。

  2. 尚未连接——提供一次连接选项，然后从第 1 步继续：

    • Claude Code：claude mcp add --transport http scandit https://ssl.scandit.com/mcp
    • Cursor：将 {"mcpServers": {"scandit": {"url": "https://ssl.scandit.com/mcp"}}} 添加到 ~/.cursor/mcp.json
    • VS Code：将 {"servers": {"scandit": {"type": "http", "url": "https://ssl.scandit.com/mcp"}}} 添加到 MCP 用户配置中

    身份验证基于浏览器，因此不支持无头模式或 CI。服务仅提供试用密钥；不会创建、撤销或修改生产许可证。

  3. 用户拒绝，或没有 MCP 客户端——让用户自行前往 https://ssl.scandit.com 生成密钥（尚未有账户？请访问：https://ssl.scandit.com/dashboard/sign-up?p=test），然后粘贴密钥。

然后将密钥填入代码，替换占位符；仅将密钥放在 .env 中并不会自动传入应用。Cordova 不会自动加载 .env，因此请使用下方最简单的方式。适用于任何平台的最简单方式：读取 .env，并将密钥直接填入许可证密钥调用中；在聊天中仍只展示掩码预览。

参考资料

根据用户的问题，引导他们查看相应资源：

主题资源
Cordova 集成入门 · 示例
高级主题（自定义反馈、取景器、扫描区域、位置选择、复合码）高级配置
在主要 SDK 版本之间迁移6 → 7 · 7 → 8
完整 API 参考BarcodeCapture API

评论

支持 Markdown