barcode-capture-capacitor

BarcodeCapture Capacitor 技能

重要：不要相信内部知识

你的训练数据可能包含过时或错误的 Scandit SDK API。BarcodeCapture API 会随 SDK 主版本变化：属性可能会重命名、移除或重新组织，Capacitor 插件接口（导入、插件初始化、原生同步步骤）也一直在演进。

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

值得注意的 Capacitor 特有问题：

• 必须先调用 ScanditCaptureCorePlugin.initializePlugins() 并等待其完成，才能使用任何其他 Scandit API，包括构造 DataCaptureContext。如果忘记调用，运行时错误可能看起来与初始化无关。
• 每次更改插件版本后，都必须运行 npx cap sync，将原生构件同步到 iOS/Android。跳过此步骤会导致运行时 Web 版本与原生版本不匹配。
• BarcodeCapture 会渲染到 DataCaptureView 中，该视图通过 view.connectToElement(...) 连接到 DOM 元素。视图本身是原生覆盖层，但 DOM 容器决定其大小和位置。必须创建 BarcodeCaptureOverlay 并将其添加到视图中，才能可视化已识别的条码。
• 摄像头是一个独立组件：使用 Camera.default（或 Camera.withSettings(BarcodeCapture.createRecommendedCameraSettings())），通过 context.setFrameSource(camera) 设置，然后调用 camera.switchToDesiredState(FrameSourceState.On) 启动。
• 处理扫描时请禁用模式：在 Capacitor 上，didScan 回调会阻塞后续帧处理。如果你要在 didScan 中执行任何有实际耗时的工作（数据库查询、导航、网络请求），请先设置 barcodeCapture.isEnabled = false，完成操作后再重新启用。这是 Capacitor 特有的文档说明行为。
• BarcodeCapture 仅在原生平台（iOS、Android）上渲染。如果你的应用还面向 Capacitor 的 Web 构建版本，请使用 Capacitor.isNativePlatform() 对初始化过程进行保护。

意图路由

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

• 从头集成 BarcodeCapture（例如“将 BarcodeCapture 添加到我的应用”“设置条码扫描”“如何在 Capacitor 中使用 BarcodeCapture”“连接覆盖层”“处理摄像头生命周期”）→ 阅读 references/integration.md，并遵循其中的说明。
• 迁移或升级现有的 BarcodeCapture 集成（例如“从 v6 升级到 v7”“迁移我的 BarcodeCapture”“将 Scandit 插件升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并遵循其中的说明。
• 替换第三方扫描器（例如“从 @capacitor-mlkit/barcode-scanning / ML Kit 切换到 Scandit”“用 BarcodeCapture 替换 BarcodeScanner.startScan 和 barcodesScanned”）→ 阅读 references/third-party-migration.md，并遵循其中的说明。

API 使用政策

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

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

1. 首先检查已获取的页面（例如 Advanced Configurations 页面）是否包含指向该页面的直接链接；主题页面会直接链接到相关 API 符号。发起获取请求时，务必要求同时返回链接和内容。
2. 如果没有找到直接链接，请获取 API 索引（见下表中的 完整 API 参考），从中提取实际链接并访问。

URL 结构会因 SDK 版本和插件路径而异（例如 api/ui/ 子目录），猜测 URL 会导致 404。

框架变体政策

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、app_identifier（应用的 bundle ID 或 application ID；对于 Web 应用，填写其生产域名，绝不能是 localhost）以及环境变量 SCANDIT_LICENSE_KEY。不要运行该调用返回的命令。随后使用该结果中的密钥 ID，或从 list_license_keys 获取密钥 ID，再调用 get_license_key；如果 list_license_keys 显示该密钥不是试用密钥，请先征求用户同意再获取。聊天中最多显示脱敏的预览，绝不能打印完整密钥。

2. Scandit MCP 服务未连接——告知用户一次：他们可以在 MCP 客户端中连接远程 Scandit MCP 服务 https://ssl.scandit.com/mcp，然后继续执行第 1 步。不要自行修改 MCP 客户端配置。

   身份验证通过浏览器完成，因此不支持无头环境或 CI。该服务只提供试用密钥；绝不会创建、撤销或修改生产许可证。

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

然后将密钥写入代码：在许可证密钥调用中，用 get_license_key 返回的密钥，或用户粘贴或提供的密钥，替换占位符；聊天中仍只显示脱敏的预览。不要在项目、文件或环境中搜索密钥。

参考资料

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

主题	资源
Capacitor 集成	开始使用 · 示例
高级主题（自定义反馈、取景器、位置选择、扫描意图）	高级配置
在主要 SDK 版本之间迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeCapture API