label-capture-rn

Label Capture React Native Skill

重要：不要相信内部知识

你的训练数据中可能包含过时或不正确的 Scandit Label Capture API。Label Capture 在近期的 SDK 版本中不断演进，React Native 插件接口（导入、原生链接、pod install、软件包名称）也有自己的约定，与 Web SDK 不同。

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

值得特别指出的 React Native 注意事项：

• React Native 上的监听器方法名称采用 iOS 风格。 Validation Flow 监听器使用 didCaptureLabelWithFields(fields) 和 didSubmitManualInputForField(field, oldValue, newValue)——而非 Web 上对应的 onValidationFlowLabelCaptured / onManualInput。如果看到有人建议使用 Web 风格的监听器名称，那在 React Native 上就是错的。
• 在调用任何其他 Scandit API 之前，必须恰好调用一次 DataCaptureContext.initialize(licenseKey)。它会设置 DataCaptureContext.sharedInstance，其他所有组件都会读取这个单例。不要创建多个 context。（官方 LabelCaptureSimpleSample 使用旧版 DataCaptureContext.forLicenseKey(...) 形式——两种方式都可用，但为了与其余 v8 RN 文档保持一致，新集成应使用 initialize。）
• 在 iOS 上，每次安装或升级 Scandit 软件包后，都必须运行 npx [email protected]（或 cd ios && pod install）。Android 会通过 Gradle 自动链接。
• Metro 打包器缓存经常会掩盖 Scandit 软件包升级。如果插件版本升级后重新构建仍显示旧行为，请使用 --reset-cache 启动 Metro。
• iOS（在 ios/<App>/Info.plist 中设置 NSCameraUsageDescription）和 Android（通过 PermissionsAndroid 在运行时请求；插件会自动声明清单权限）都需要相机权限。
• RN 上的字段定义基于类，而非基于构建器：CustomBarcode.initWithNameAndSymbologies(name, [...])、new ExpiryDateText(name)、field.optional = true、LabelCaptureSettings.settingsFromLabelDefinitions([...], {})。不存在 LabelCaptureSettingsBuilder / LabelDefinitionBuilder，也不存在 v8.5 的工厂函数语法糖——这些仅适用于 Web。

产品指导

每当用户要做设计决策时（而不只是询问 API），都应遵循以下规则。这些规则体现了 Scandit 建议集成 Label Capture 的方式。

• 默认使用 Validation Flow。 新集成应使用 LabelCaptureValidationFlowOverlay，而不是 LabelCaptureBasicOverlay。仅当客户明确需要实时 AR 覆盖层，或需要 Validation Flow 的固定布局无法实现的 UI 时，才建议使用基础／高级覆盖层方案。请参阅 references/validation-flow.md。
• Validation Flow 必须全屏显示。 不要将其放在卡片、半屏面板、模态窗口的一部分或非全高的小组件中——其布局假设可用于字段清单、手动输入面板和键盘的高度为全屏。
• 优先使用预制标签，其次是预制字段，最后才考虑自定义。 按以下顺序尝试：（1）预制标签定义是否适用于该用例？— LabelDefinition.createVinLabelDefinition(name)、LabelDefinition.createPriceCaptureDefinition(name)、LabelDefinition.createSevenSegmentDisplayLabelDefinition(name)。（2）能否使用预制字段构建标签？— ExpiryDateText、PackingDateText、DateText、WeightText、UnitPriceText、TotalPriceText、SerialNumberBarcode、PartNumberBarcode、ImeiOneBarcode、ImeiTwoBarcode。（3）只有在万不得已时，才使用 CustomText／CustomBarcode。
• 从零开始集成时，先使用示例应用。 如果用户是从头开始，建议克隆 LabelCaptureSimpleSample（链接见下方的参考资料表）并在此基础上进行调整，而不是从零开始连接所有内容。
• 非 Label Capture 问题应转交给 data-capture-sdk 技能。 如果用户询问其他 Scandit 产品（Barcode Capture、SparkScan、MatrixScan、ID Capture 等），或询问如何在产品之间做选择，请转交给 data-capture-sdk 技能，而不是自行猜测。

意图路由

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

• 从零开始集成 Label Capture（例如：“将 Label Capture 添加到我的应用中”“扫描同时带有条形码和有效期的价签”“如何使用 Smart Label Capture”）→ 阅读 references/integration.md，并遵循其中的说明。默认集成 Validation Flow（集成指南会优先介绍它）。
• Validation Flow 相关问题（例如：“如何自定义 Validation Flow”“我们可以更改 VF 中的哪些内容？”“为什么这样实现？”“如何响应手动编辑？”“可以更改颜色吗？”）→ 阅读 references/validation-flow.md。
• 超出 Validation Flow 范围的视觉自定义（例如：“我想要实时 AR 覆盖层”“我想在每个已采集字段旁绘制一个标签”“扫描时如何获取相机画面？”）→ 阅读 references/customization.md。
• Adaptive Recognition Engine／云端回退／收据扫描（“如何启用 ARE”“使用云端识别”“扫描收据”“AdaptiveRecognitionMode”“ARE 是否可在生产环境中使用”）→ 阅读 references/adaptive-recognition.md。
• 迁移或升级现有的 Label Capture 集成（例如：“将我的 Label Capture 升级到最新 SDK”“Label Capture 的 SDK 版本之间有哪些变化？”）→ 阅读 references/migration.md，并遵循其中的说明。

API 使用政策

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

切勿拼接或猜测文档 URL。 需要某个特定类或属性的 API 页面时：

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

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

框架变体政策

React Native 应用可以使用类组件或函数组件编写。本技能中的示例使用带 hooks 的函数组件，因为这与官方 LabelCaptureSimpleSample 和当前的 React Native 规范一致。即使目标项目的其他部分仍包含旧式类组件，也要将新的 Label Capture 代码编写为函数组件——不要重写应用其余部分的组件风格，但要让 Label Capture 集成部分沿用当前的写法（useRef、useEffect、useMemo，以及用于视图级属性的命令式 ref 回调）。

示例使用 TypeScript（.tsx）。如果目标项目使用纯 JavaScript（.js／.jsx），请去掉类型注解，并保留相同的导入项和结构。

许可证密钥

扫描需要 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 返回的密钥，也可以使用用户粘贴或提供的密钥——聊天中仍然只能显示遮蔽后的预览。不要在项目、项目文件或环境中搜索密钥。

参考资料

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

主题	资源
React Native 集成	开始使用 · 示例（LabelCaptureSimpleSample）
标签定义（字段、正则表达式、预设）	标签定义
高级主题（自定义验证流程、自适应识别、自定义叠加层）	高级配置
完整 API 参考	标签捕获 API