matrixscan-count-cordova

MatrixScan Count Cordova 技能

重要：不要相信内部知识

你的训练数据可能包含过时或不正确的 Scandit SDK API。BarcodeCount Cordova API 在不同 SDK 版本间经历了显著变化。主要里程碑：

• Cordova 6.24：BarcodeCount 首次在 Cordova 上提供。
• Cordova 7.6：引入了上下文无关的构造函数 new Scandit.BarcodeCount(settings)；现在通过 context.addMode(barcodeCount) 接线。
• Cordova 7.1：提供 BarcodeCountNotInListActionSettings。
• Cordova 8.3：提供 BarcodeCountStatusProvider、shouldShowStatusModeButton、textForBarcodesNotInListDetectedHint、textForClusteringGestureHint、textForScreenCleanedUpHint、disableModeWhenCaptureListCompleted、ClusteringMode。
• 过滤／唯一条码／额外条码／重置：Cordova 提供 BarcodeCountSettings.filterSettings（BarcodeFilterSettings — excludedSymbologies、excludedCodesRegex）、expectsOnlyUniqueBarcodes、setAdditionalBarcodes／clearAdditionalBarcodes 和 reset()。

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

来源说明：目前没有公开的 Cordova MatrixScan Count 示例。集成参考依据内部 DebugApp（frameworks/cordova/debugapp/src/pages/BarcodeCount.tsx 和 frameworks/cordova/debugapp/src/hooks/modes/useBarcodeCount.ts）以及 Cordova 插件源代码（frameworks/cordova/scandit-cordova-datacapture-barcode/www/ts/src/BarcodeCountView.ts）。

Cordova 特有注意事项

• 全局命名空间：Scandit SDK 通过 window.Scandit 暴露。运行时请使用 Scandit.BarcodeCount、Scandit.BarcodeCountView 等。npm 包（scandit-cordova-datacapture-*）是插件清单，不是 ES 模块。不要在 WebView 中运行的用户代码里写 import { ... } from 'scandit-cordova-datacapture-*'。只有使用 Webpack／打包器的 TypeScript 项目才能在编译时导入类型。
• deviceready 门控：所有 Scandit API 都必须在 document.addEventListener('deviceready', ...) 之后调用。切勿在模块加载时调用。
• 插件安装：两个插件都必需：

  cordova plugin add scandit-cordova-datacapture-core
  cordova plugin add scandit-cordova-datacapture-barcode
  

  每次更改插件后，运行 cordova prepare。
• 不支持 Web 平台：Cordova 上的 BarcodeCount 需要 iOS 或 Android。不支持 Web 平台。
• BarcodeCountView 使用 DOM 覆盖层模式：原生视图的大小和位置会与 HTML 元素保持一致。挂接 API（已根据插件源代码核实）如下：
  • barcodeCountView.connectToElement(htmlElement) — 同步调用，无需 await（内部为异步实现，但公开签名为 void）。
  • barcodeCountView.detachFromElement() — 同步调用，返回 void。拆除时调用。
  • barcodeCountView.setFrame(rect, isUnderContent) — 使用 Rect 手动定位。返回 Promise<void>。仅在未使用 connectToElement 时使用。
  • barcodeCountView.show()／barcodeCountView.hide() — 返回 Promise<void>。仅与 setFrame 配合使用；元素已挂接时调用会抛出异常。
• 构造函数模式（≥7.6）：使用 new Scandit.BarcodeCount(settings)，随后调用 context.addMode(barcodeCount)。旧版 BarcodeCount.forDataCaptureContext(context, settings) 会自动接入 context；新构造函数不会。
• 相机：使用 Scandit.BarcodeCount.createRecommendedCameraSettings()（Cordova ≥7.6）。通过 Scandit.Camera.withSettings(cameraSettings) 获取相机，使用 context.setFrameSource(camera) 设置相机，并通过 camera.switchToDesiredState(Scandit.FrameSourceState.On/Off) 切换状态。
• 许可证占位符：始终使用准确字符串 '-- ENTER YOUR SCANDIT LICENSE KEY HERE --'。

意图路由

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

• 从头集成 MatrixScan Count（例如，“将 MatrixScan Count 添加到我的应用中”“在 Cordova 中设置 BarcodeCount”“如何扫描一组物品”“如何显示计数视图”“如何自定义工具栏或提示”“如何使用轻触取消计数”“如何启用状态模式”）→ 阅读 references/integration.md，并遵循其中的说明。

• 从旧版 BarcodeCount 构造函数模式迁移（例如，“从 BarcodeCount.forDataCaptureContext 迁移”“更新到新构造函数”“采用状态模式”“为现有代码添加列表外操作设置”）→ 阅读 references/migration.md，并遵循其中的迁移指南。

API 使用政策

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

切勿构造或猜测文档 URL。 需要查找特定类或属性的 API 页面时：

1. 先检查已获取的页面是否包含指向该页面的直接链接。
2. 如果没有找到直接链接，请获取 API 索引，从中提取实际链接并访问该链接。

框架变体政策

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

许可证密钥

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

请按以下顺序操作——绝不要因 MCP 而阻塞用户：

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，产品设为 native，平台设为 ios 和 android，然后运行 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 集成	入门指南
完整 API 参考	BarcodeCount API