id-capture-capacitor

ID Capture Capacitor 技能

重要：不要信任内部知识

你的训练数据可能包含过时或错误的 Scandit ID Capture API。ID Capture API 在 v7 → v8 版本交界处进行了重构（scannerType 属性更名为 scanner，并改为包装器；独立的 AamvaBarcodeVerifier 已移除，改用设置标志；此外还新增了多个验证 API）。Capacitor 插件接口（包名、命令式的 DataCaptureView + connectToElement 模式、显式调用 initializePlugins() 启动）也与 iOS、Android、web、Flutter、React Native 和 Cordova SDK 不同。

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

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

• 必须显式初始化插件。 Capacitor 不会自动初始化——请在应用启动时、创建 DataCaptureContext 或其他任何内容之前，调用一次 await ScanditCaptureCorePlugin.initializePlugins()。跳过这一步会导致原生桥接未连接，并产生晦涩的“plugin not implemented”错误。
• 视图是连接到 <div> 的命令式类，不是自定义元素。 没有 <data-capture-view> HTML 标签，Scandit 也没有提供 React/Vue/Angular 组件。请使用 DataCaptureView.forContext(context) 创建视图，并通过 view.connectToElement(divElement) 将其附加到普通的 <div id="..."> 上。离开页面时，使用 view.detachFromElement() 将其分离。
• DataCaptureContext.initialize(licenseKey) 会返回上下文。 请获取返回值：const context = DataCaptureContext.initialize('<key>');。示例中没有 sharedInstance 模式——请保留对返回上下文的引用。
• 相机使用 Camera.withSettings(...) 构造，而不是 Camera.default + applySettings。 使用 Camera.withSettings(IdCapture.createRecommendedCameraSettings()) 构造已针对 ID Capture 预先配置的相机。Flutter/RN 风格的 Camera.default 不符合 Capacitor 示例的惯用写法。
• 枚举成员名称采用 PascalCase，传输值采用 camelCase（与 RN 的 TypeScript 约定相同）。请使用 IdCaptureRegion.Us、IdImageType.CroppedDocument、IdSide.Front、RejectionReason.Timeout、IdAnonymizationMode.FieldsAndImages、IdFieldType.DocumentNumber、IdLayoutStyle.Rounded、FrameSourceState.On / .Off、AamvaBarcodeVerificationStatus.Authentic。切勿使用 Dart/Flutter 中的小写形式。
• CapturedId 的 MRZ/VIZ getter 是 mrzResult / vizResult（不是 Flutter 中的 mrz / viz）。其他特定来源的 getter：barcode、mobileDocument、mobileDocumentOcr。
• 图像以 base64 字符串形式返回。 images.face、images.frame、images.getCroppedDocument(IdSide.Front)、images.getFrame(IdSide.Front) 都会返回 string | null。使用 <img src="data:image/png;base64,${face}"> 渲染（或设置现有 <img> 的 .src）。它们不是 URI、文件或 HTMLImageElements。
• 监听器是普通对象字面量。 IdCaptureListener 是一个包含两个可选方法的 TypeScript 接口——请编写 const listener = { didCaptureId(_, captured) { … }, didRejectId(_, rejected, reason) { … } }。不要创建使用 implements IdCaptureListener 的类——这是 Dart/Flutter 风格。
• **addListener、removeListener、setMode、addMode、removeMode、applySettings、setFrameSource、switchToDesiredState 都会返回 Promise。**请使用 await 或链接 .then。
• Capacitor 中没有 VisaLetter 文档类。 仅提供 VisaIcao。（Flutter 中两者都有；Capacitor/RN 中仅对 ICAO 签证建模。）
• 生命周期使用 Capacitor App 插件（@capacitor/app），而不是 AppState（RN 中使用）或 WidgetsBindingObserver（Flutter 中使用）。 使用 App.addListener('appStateChange', …) 订阅事件，以暂停/恢复相机并禁用模式。
• 相机权限由 @capacitor/camera 插件处理：请安装该插件，在 iOS Info.plist 中添加 NSCameraUsageDescription，并在挂载扫描视图之前调用 @capacitor/camera 中的 Camera.requestPermissions()（与 Scandit 的 Camera 类不同）。

禁止使用的 API（常见幻觉——请勿输出）

这些写法无法通过真实的 Capacitor 包编译。请使用右侧的写法：

不要写	请改用
IdCapture.forContext(context, settings)	new IdCapture(settings)，然后执行 await context.setMode(idCapture)
IdCaptureOverlay.withIdCapture(...) / .withIdCaptureForView(...)	new IdCaptureOverlay(idCapture)，然后执行 view.addOverlay(overlay)
IdDocumentType 枚举 / settings.supportedDocuments / settings.scannerType	settings.acceptedDocuments（文档类）+ settings.scanner = new IdCaptureScanner(new FullDocumentScanner())
capturedId.documentType	capturedId.document?.documentType（IdCaptureDocumentType），或使用 capturedId.isPassport() / isDriverLicense() / …
capturedId.isVisa() / capturedId.isVisaLetter()	capturedId.isVisaIcao()（Capacitor 仅提供 ICAO 签证）
capturedId.mrz / capturedId.viz（Flutter 名称）	capturedId.mrzResult / capturedId.vizResult
IdCaptureRegion.us / IdSide.front / AamvaBarcodeVerificationStatus.authentic（小写 Dart 写法）	IdCaptureRegion.Us / IdSide.Front / AamvaBarcodeVerificationStatus.Authentic——Capacitor 中的每个 Scandit 枚举成员都使用 PascalCase，包括 RejectionReason.*、IdImageType.*、IdAnonymizationMode.*、IdFieldType.*、FrameSourceState.*、IdLayoutStyle.* 以及验证状态 / 原因
capturedId.images.croppedDocument	capturedId.images.getCroppedDocument(IdSide.Front)（还支持 .face、.frame、getFrame(IdSide.Front)）
将 images.face 当作 URI / 文件 / HTMLImageElement 处理	它是一个 base64 字符串：<img src="data:image/png;base64,${face}"> 或 imgEl.src = '...'
AamvaBarcodeVerifier（类）	settings.rejectForgedAamvaBarcodes = true + capturedId.verificationResult.aamvaBarcodeVerification
DrivingLicenseCategory.categoryCode	DrivingLicenseCategory.code（以及 dateOfIssue / dateOfExpiry）
<data-capture-view> 自定义元素或 <IdCaptureView> React 风格组件	DataCaptureView.forContext(context) + view.connectToElement(document.getElementById('...'))
Camera.default（RN/Flutter 惯用写法）	Camera.withSettings(IdCapture.createRecommendedCameraSettings())
启动时跳过 ScanditCaptureCorePlugin.initializePlugins()	在调用任何其他 Scandit API 之前，始终执行 await ScanditCaptureCorePlugin.initializePlugins();
调用 idCapture.addListener(...) 时不使用 await（启动时存在竞态）	await idCapture.addListener(listener)——removeListener、setMode、applySettings、setFrameSource、switchToDesiredState 也同样如此

产品指导

只要用户在做设计决策，而不只是询问 API 问题，就应用以下规则。

• 只接受实际需要的文档。 范围较窄的 acceptedDocuments 列表（例如仅包含 new DriverLicense(IdCaptureRegion.Us)）比对所有文档类型使用 IdCaptureRegion.Any 更快、更准确。不要默认选择“全部”，而应先询问用户预期支持哪些文档和地区。
• 选择与所需数据相匹配的扫描器。 new FullDocumentScanner() 会自动读取正反两面（最适合大多数身份证件／驾驶执照用例）。new SingleSideScanner(barcode, machineReadableZone, visualInspectionZone) 会读取单面中你启用的区域——当你只需要美国驾驶执照背面的 PDF417 条码，或只需要护照的 MRZ 时，就使用它。对于移动驾驶执照／mDL，请使用 MobileDocumentScanner。
• 处理 didRejectId，不要只处理 didCaptureId。 拒绝原因（RejectionReason.Timeout、NotAcceptedDocumentType、DocumentExpired、DocumentVoided、ForgedAamvaBarcode 等）能让用户了解扫描未成功的原因。生产环境中的集成必须向用户显示相应消息。
• 默认匿名化不需要的字段。 IdCaptureSettings.anonymizationMode 和针对各字段的 addAnonymizedField 可确保受监管的数据（例如文档图像、敏感字段）不会出现在结果中，除非你选择保留它们。建议仅保留满足用例所需的最少数据。
• 非 ID Capture 问题转交给 data-capture-sdk skill。 如果用户询问其他 Scandit 产品（Barcode Capture、SparkScan、MatrixScan、Label Capture 等），或询问如何在产品之间进行选择，请转交给 data-capture-sdk skill，而不是猜测。

意图路由

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

• 从头集成 ID Capture（例如“在我的 Capacitor 应用中添加 ID 扫描”“扫描护照／驾驶执照”“读取 MRZ”“提取持证人的姓名和出生日期”）→ 阅读 references/integration.md 并遵循其中的说明。
• 三种附加功能之一（“拒绝已作废／取消的身份证件”“检测打孔／作废的执照”“解码欧洲驾驶执照背面”“读取车辆类别”“验证 AAMVA 条码／检测伪造的美国执照”）→ 阅读 references/supplementary-modules.md。
• 迁移或升级现有 ID Capture 集成（“将 ID Capture 升级到最新 SDK”“从 v7 迁移到 v8”“我的 scannerType 代码无法编译了”“AamvaBarcodeVerifier 不见了”“ID Capture 在不同版本之间有哪些变化”）→ 阅读 references/migration.md。
• 在 Capacitor 之上将 ID Capture 接入宿主 UI 框架（“如何在 Ionic Angular 中实现？”“展示 Ionic React 的生命周期”“我使用的是 Vue 3／Composition API”“在 ngAfterViewInit／useEffect／onMounted 中的哪个位置启动／停止摄像头？”“路由切换时的页面生命周期”“用于 data-capture-view div 的 @ViewChild”）→ 阅读 references/framework-recipes.md。Scandit 代码本身与 references/integration.md 中的代码相同；此文件仅展示各框架所需的生命周期衔接代码。

API 使用政策

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

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

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

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

框架变体政策

references/integration.md 中的示例使用 TypeScript／纯 JS（不包含特定框架的绑定）。官方的 IdCaptureSimpleSample 使用 JS 编写，并在 DOMContentLoaded 之后运行。如果目标项目基于 Capacitor 使用框架（Ionic Angular、Ionic React 或 Vue 3），请参阅 references/framework-recipes.md 中的生命周期框架——Scandit 调用保持不变；区别仅在于接入位置。不要仅为了 ID Capture 引入新框架。

许可证密钥

扫描需要 Scandit 许可证密钥。对于此技能，许可证产品为 native，许可证平台为 ios 和 android。

请按以下顺序操作——不要因 MCP 阻塞用户：

1. 已连接 Scandit MCP 服务——调用 ensure_scanner_setup，指定产品 native、平台 ios 和 android、app_identifier（应用的 bundle ID 或 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 返回的密钥，或用户粘贴或提供的密钥，替换占位符——聊天中仍然只显示经过遮蔽的预览。不要在项目、文件或环境中搜索密钥。

参考资料

根据用户的问题，引导他们查阅相应资源：

主题	资源
Capacitor 集成	开始使用 · 示例 (IdCaptureSimpleSample)
进阶主题（匿名化、验证、扫描器、覆盖层）	进阶配置
在主要 SDK 版本之间迁移	7 → 8
完整 API 参考	ID Capture API