matrixscan-ar-capacitor

MatrixScan AR Capacitor 技能

重要：切勿轻信内部知识

你的训练数据中可能包含过时或错误的 Scandit SDK API。BarcodeAr API 是在 Capacitor 8.2 中新增的，此前在 Capacitor 平台上没有可供参考的历史。其属性、构造函数签名、提供程序接口和视图附加方式可能与其他平台或一般认知不同。

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

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

• 必须在调用任何其他 Scandit API（包括构造 DataCaptureContext）之前调用并等待 ScanditCaptureCorePlugin.initializePlugins()。忘记调用会导致看似与初始化无关的运行时错误。
• 每次更改插件版本后，都必须运行 npx cap sync，将原生资源同步到 iOS/Android。跳过这一步会导致运行时 Web/原生版本不匹配。
• BarcodeArView 需要 DOM 元素。 与 SparkScan 不同，BarcodeArView 不是浮动的原生覆盖层；它会从 DOM 元素获取尺寸和位置。必须调用 await barcodeArView.connectToElement(element)，将其附加到 HTML 中的 <div id="barcode-ar-view"> 容器。
• Capacitor 上的 BarcodeAr 最低 SDK 版本为 8.2。此平台没有可供迁移的 v6 或 v7 版本历史。
• BarcodeAr 通过 new BarcodeAr(settings) 构造；上下文通过 BarcodeArView 单独连接，不会传入模式构造函数。
• 必须通过 BarcodeAr.createRecommendedCameraSettings()、Camera.withSettings(cameraSettings) 和 context.setFrameSource(camera) 显式设置相机；运行后，BarcodeArView 会管理相机生命周期。
• highlightProvider 和 annotationProvider 是具有异步方法的普通对象，作为属性设置在 BarcodeArView 实例上。
• iOS 需要在 Info.plist 中配置 NSCameraUsageDescription。Android 会自动处理相机权限。

意图路由

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

• 从头集成 MatrixScan AR（例如：“将 MatrixScan AR 添加到我的应用”“设置 Barcode AR”“如何在 Capacitor 中使用 BarcodeArView”“如何显示注释”“如何高亮条码”）→ 阅读 references/integration.md，并遵循其中的说明。

• 从 BarcodeBatch / BarcodeTracking 迁移到 BarcodeAr（例如：“迁移我的 BarcodeBatch 代码”“用 BarcodeAr 替换 BarcodeTracking”“从 MatrixScan 升级到 BarcodeAr”；目标文件导入了 BarcodeBatch、BarcodeBatchBasicOverlay、BarcodeBatchAdvancedOverlay、TrackedBarcodeView，或包含带有 BarcodeBatch 实例的 context.setMode(）→ 阅读 references/migration.md，并遵循其中的 10 步迁移流程。

API 使用政策

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

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

1. 先检查已获取的页面（例如 Get Started 页面）是否包含指向该页面的直接链接——主题页面会直接链接到相关 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，然后运行 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 参考	BarcodeAr API