matrixscan-ar-cordova

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MatrixScan AR Cordova Skill

MatrixScan AR Cordova 技能

Critical: Do Not Trust Internal Knowledge

重要提示：请勿依赖内部知识

Your training data may contain outdated or incorrect Scandit SDK APIs. The BarcodeAr API is new in Cordova plugin 8.2 — it did not exist in v6 or v7 for Cordova. There is no migration history to reference.

Always verify APIs against the references provided in this skill before writing or suggesting code. Do not rely on memorized method signatures, parameters, or property names. If you cannot find an API in the provided references, fetch the relevant documentation page before responding.

Cordova-specific gotchas worth flagging:

The Scandit SDK is exposed on the global
```
window.Scandit
```
object. The npm package names (
```
scandit-cordova-datacapture-*
```
) are plugin manifests — they are not runtime ES modules. Do not emit
```
import { ... } from 'scandit-cordova-datacapture-*'
```
in user code that will run in the WebView; use
```
Scandit.X
```
(with an optional
```
global.d.ts
```
for typing) instead. Only Ionic/Angular/Webpack-bundled projects import from the packages directly.
```
document.addEventListener('deviceready', ...)
```
is the only safe gate for Scandit APIs. Do not run any Scandit call at module load time — it will fail because the Cordova bridge is not ready yet.
```
BarcodeArView
```
in Cordova uses a DOM-overlay model: the native AR view is sized and positioned to mirror a plain HTML
```
<div>
```
element. You must call
```
barcodeArView.connectToElement(element)
```
after construction to link the view to a DOM node, and
```
barcodeArView.detachFromElement()
```
when tearing down.

new Scandit.BarcodeAr(settings)

— this is the Cordova constructor (not

BarcodeAr.forContext

). Context is wired separately via

context.setFrameSource(camera)

Camera is managed manually in BarcodeAr on Cordova: obtain it with

Scandit.Camera.withSettings(Scandit.BarcodeAr.createRecommendedCameraSettings())

, set it as the frame source, and call

camera.switchToDesiredState(Scandit.FrameSourceState.On/Off)

to start/stop.

Highlight and annotation providers return
```
Promise<BarcodeArHighlight | null>
```
and
```
Promise<BarcodeArAnnotation | null>
```
respectively — make the methods
```
async
```
or return a Promise explicitly.
After changing plugin versions, run
```
cordova prepare
```
(and reinstall the platform if needed) to propagate the new native artifacts.

你的训练数据可能包含过时或错误的 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
```
（必要时重新安装平台）以更新原生构件。

Intent Routing

意图路由

Based on the user's request, load the appropriate reference file before responding:

Integrating MatrixScan AR from scratch (e.g. "add MatrixScan AR to my app", "set up AR barcode overlays", "how do I use BarcodeAr in Cordova", "how do I show info annotations", "how do I customize highlights") → read references/integration.md and follow the instructions there.
Migrating from BarcodeBatch / BarcodeTracking to BarcodeAr (e.g. "migrate my MatrixScan code", "update from BarcodeBatch to BarcodeAr", "I'm using BarcodeBatchBasicOverlay / BarcodeBatchAdvancedOverlay", "convert my old MatrixScan integration", "we have BarcodeTracking and need to upgrade") → read references/migration.md and follow the 10-step migration guide there. Key Cordova-specific caveat:
```
BarcodeArCustomAnnotation
```
is NOT available on Cordova — freeform HTML overlays from
```
BarcodeBatchAdvancedOverlay
```
must be replaced with built-in annotation types (
```
BarcodeArInfoAnnotation
```
,
```
BarcodeArPopoverAnnotation
```
,
```
BarcodeArStatusIconAnnotation
```
, or
```
BarcodeArResponsiveAnnotation
```
).

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

从零集成 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 特有的关键注意事项：
```
BarcodeArCustomAnnotation
```
在 Cordova 上不可用—— 来自
```
BarcodeBatchAdvancedOverlay
```
的自由格式 HTML 覆盖层必须替换为内置标注类型（
```
BarcodeArInfoAnnotation
```
、
```
BarcodeArPopoverAnnotation
```
、
```
BarcodeArStatusIconAnnotation
```
或
```
BarcodeArResponsiveAnnotation
```
）。

API Usage Policy

API 使用规范

Only use APIs that are explicitly documented in the Scandit references below. Do not invent or guess method signatures, parameters, property names, or imports. If unsure whether an API exists or how it is called — or if a runtime error occurs — fetch the relevant reference page before responding. Do not tell the user to check the docs themselves. After answering, always include the relevant link so the user can explore further.

Never construct or guess documentation URLs. When you need a specific class or property's API page:

First check whether the page you already fetched contains a direct hyperlink to it — topic pages link directly to relevant API symbols.
If no direct link was found, fetch the API index (see Full API reference in the table below), extract the actual link from it, and follow that.

URL structures vary across SDK versions and plugin paths and guessing will lead to 404s.

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

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

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

不同 SDK 版本和插件路径的 URL 结构各不相同，猜测会导致 404 错误。

Framework variant policy

框架变体规范

Cordova is a WebView-based framework. Examples in this skill use plain JavaScript (with optional JSDoc type hints as seen in the official MatrixScanARSimpleSample). The same API works in TypeScript — add a

global.d.ts

declaration file (described in references/integration.md) and write TypeScript syntax. This skill does not assume a TypeScript project by default. If the target project is clearly TypeScript (

.ts

files,

tsconfig.json

), adapt the final output to TypeScript; otherwise stay in plain JS.

Cordova 是基于 WebView 的框架。本技能中的示例使用纯 JavaScript（可搭配官方 MatrixScanARSimpleSample 中所示的 JSDoc 类型提示）。相同的 API 也适用于 TypeScript —— 添加

global.d.ts

声明文件（在 references/integration.md 中有说明）并使用 TypeScript 语法编写即可。本技能默认不假设项目使用 TypeScript。如果目标项目明确是 TypeScript 项目（有

.ts

文件、

tsconfig.json

），则将最终输出适配为 TypeScript；否则保持纯 JS。

References

参考资料

Direct users to the right resource based on their question:

Topic	Resource
Cordova integration	Get Started · Sample
Full API reference	BarcodeAr API

根据用户的问题引导其访问对应的资源：

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