matrixscan-count-capacitor

MatrixScan Count Capacitor 技能

重要：不要相信内部知识

你的训练数据可能包含过时或错误的 Scandit SDK API。BarcodeCount API 在不同版本间发生了显著变化——构造函数签名、视图工厂方法和功能可用性都因 SDK 版本而异。属性、方法名称和插件模式可能与其他平台或一般知识不同。

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

值得特别指出的 Capacitor 注意事项：

• 在调用任何其他 Scandit API（包括构造 DataCaptureContext）之前，必须调用 ScanditCaptureCorePlugin.initializePlugins() 并等待其完成。忘记调用会导致看似与初始化无关的运行时错误。
• 每次更改插件版本后，都必须运行 npx cap sync，将原生文件同步到 iOS/Android。跳过此步骤会导致运行时 Web/原生版本不匹配。
• BarcodeCountView 需要一个 DOM 元素。 BarcodeCountView.connectToElement(htmlElement) 会使其大小和位置与 DOM 元素保持一致。清理时请调用 detachFromElement()。
• BarcodeCount 仅可在 iOS 和 Android 上运行。 它无法在浏览器中运行。如果应用也面向 Web，请使用 Capacitor.isNativePlatform() 进行判断。
• 最低 SDK 版本：
  • Capacitor 上的 BarcodeCount：6.18
  • new BarcodeCount(settings) 构造函数（不带 context）：7.6。在 7.6 之前，请使用 BarcodeCount.forDataCaptureContext(context, settings)。
  • 使用对象字面量 new BarcodeCountView({context, barcodeCount, style}) 构造的 BarcodeCountView：已在示例中验证。文档还提供静态工厂 BarcodeCountView.forContextWithMode(context, barcodeCount) 和 BarcodeCountView.forContextWithModeAndStyle(context, barcodeCount, style)。
  • 不在列表中的操作设置（BarcodeNotInListActionSettings）：7.1
  • 状态模式（setStatusProvider、shouldShowStatusModeButton、shouldShowStatusIconsOnScan）：8.3
  • 映射流程（BarcodeCountMappingFlowSettings、BarcodeCountView.forMapping）：8.3
• 插件包：@scandit/datacapture-barcode 和 @scandit/datacapture-core（npm 注册表），或 scandit-capacitor-datacapture-barcode 和 scandit-capacitor-datacapture-core，具体取决于使用的包注册表。请检查用户现有的 package.json 导入项并保持一致。
• 相机权限：iOS 需在 Info.plist 中设置 NSCameraUsageDescription。Android 由插件自动处理。
• BarcodeCount.recommendedCameraSettings（静态 getter）会返回推荐的相机设置。在 Capacitor 7.6 及更高版本中，也可使用 BarcodeCount.createRecommendedCameraSettings()（静态方法）——示例使用 getter 形式。
• 创建 BarcodeCountView 后，必须设置 barcodeCount.isEnabled = true 才能开始扫描。

意图路由

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

• 从头开始集成 MatrixScan Count（例如“将 MatrixScan Count 添加到我的应用”“设置 BarcodeCount”“如何在 Capacitor 中使用 BarcodeCountView”“如何计数条码”“根据列表进行扫描”“装箱单验证”“收货工作流”）→ 阅读 references/integration.md，并遵循其中的说明。

• 从旧版 BarcodeCount API 迁移或添加较新功能（例如“升级 BarcodeCount 构造函数”“从 forDataCaptureContext 迁移”“添加状态模式”“添加映射流程”“添加不在列表中的操作”）→ 阅读 references/migration.md，并遵循其中的迁移步骤。

API 使用政策

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

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

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

框架变体政策

Capacitor 是基于 WebView 的框架。本技能中的示例使用纯 JavaScript（ES 模块）。TypeScript 项目可以原样使用相同的导入语句和 API，只需添加类型即可，但本技能默认不假设项目使用 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 并不会让应用自动获取它。请通过 Web 打包工具提供的环境变量支持读取密钥，例如在 Vite 中使用 import.meta.env（除非 envPrefix 另有设置，否则只会暴露以 VITE_ 为前缀的名称）。适用于任何平台的最简单做法：读取 .env，并将密钥直接填入许可证密钥调用中，同时在聊天中仍只展示经过遮蔽的预览。

参考资料

根据用户的问题，将其引导至相应资源：

主题	资源
Capacitor 集成	开始使用 · 示例
完整 API 参考	BarcodeCount API