matrixscan-ar-cordova

MatrixScan AR Cordova 技能

重要：不要相信内部知识

你的训练数据中可能包含过时或不正确的 Scandit SDK API。BarcodeAr API 是 Cordova 插件 8.2 中新增的，在 Cordova v6 或 v7 中并不存在。没有可供参考的迁移历史。

编写或建议代码前，务必根据此技能提供的参考资料验证 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 方法，因为此时 Cordova 桥尚未就绪，调用会失败。
• Cordova 中的 BarcodeArView 使用DOM 覆盖层模型：原生 AR 视图的大小和位置会与普通 HTML <div> 元素保持一致。构造后必须调用 barcodeArView.connectToElement(element) 将视图关联到 DOM 节点；销毁时调用 barcodeArView.detachFromElement()。
• new Scandit.BarcodeAr(settings) 是 Cordova 的构造函数（不是 BarcodeAr.forContext）。上下文需单独通过 context.setFrameSource(camera) 进行关联。
• Cordova 上的 BarcodeAr 需要手动管理相机：使用 Scandit.Camera.withSettings(Scandit.BarcodeAr.createRecommendedCameraSettings()) 获取相机，将其设为帧源，并调用 camera.switchToDesiredState(Scandit.FrameSourceState.On/Off) 启动或停止相机。
• 高亮提供程序和注释提供程序分别返回 Promise<BarcodeArHighlight | null> 和 Promise<BarcodeArAnnotation | null>，因此请将方法设为 async，或显式返回 Promise。
• 更改插件版本后，运行 cordova prepare（必要时重新安装平台），以应用新的原生组件。

意图路由

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

• 从头集成 MatrixScan AR（例如“将 MatrixScan AR 添加到我的应用”“设置 AR 条码覆盖层”“如何在 Cordova 中使用 BarcodeAr”“如何显示信息注释”“如何自定义高亮”）→ 阅读 references/integration.md，并遵循其中的说明。

• 从 BarcodeBatch / BarcodeTracking 迁移到 BarcodeAr（例如“迁移我的 MatrixScan 代码”“从 BarcodeBatch 更新到 BarcodeAr”“我在使用 BarcodeBatchBasicOverlay / BarcodeBatchAdvancedOverlay”“转换我的旧 MatrixScan 集成”“我们在使用 BarcodeTracking，需要升级”）→ 阅读 references/migration.md，并遵循其中的 10 步迁移指南。需特别注意 Cordova 特有的限制：Cordova 不支持 BarcodeArCustomAnnotation，因此必须将 BarcodeBatchAdvancedOverlay 中的自由格式 HTML 覆盖层替换为内置注释类型（BarcodeArInfoAnnotation、BarcodeArPopoverAnnotation、BarcodeArStatusIconAnnotation 或 BarcodeArResponsiveAnnotation）。

API 使用政策

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

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

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

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

框架变体政策

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

许可证密钥

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

请按以下顺序操作——绝不要让用户因 MCP 而无法继续：

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，指定产品 native、平台 ios 和 android、app_identifier（应用的 bundle 或 application id；对于 Web，填写其生产域名，绝不能是 localhost），以及 env_var SCANDIT_LICENSE_KEY。不要运行它返回的命令。然后使用该结果中的密钥 id，或从 list_license_keys 获取的 id，调用 get_license_key；如果 list_license_keys 显示该密钥不是试用密钥，请先征求用户同意再获取。聊天中最多只能显示掩码预览；绝不要输出完整密钥。

2. 未连接——只告知用户一次：他们可以在自己的 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 返回的密钥，或用户粘贴或提供的密钥——聊天中仍只显示掩码预览。不要在项目、文件或环境中搜索密钥。

参考资料

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

主题	资源
Cordova 集成	入门指南 · 示例
完整 API 参考	BarcodeAr API