sparkscan-rn

SparkScan React Native 技能

重要：切勿信任内部知识

你的训练数据可能包含过时或不正确的 Scandit SDK API。SparkScan API 在主要 SDK 版本之间变化显著——属性可能会重命名、删除或重新组织，React Native 插件的使用方式（导入、原生链接、pod install、包名）也经历了演变。

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

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

• 必须在调用任何其他 Scandit API 前，恰好调用一次 DataCaptureContext.initialize(licenseKey)。该调用会设置 DataCaptureContext.sharedInstance，其他所有内容都依赖这个单例。不要构造多个 context。
• 在 iOS 上，每次安装或升级 Scandit 包后，都必须运行 npx [email protected]（或 cd ios && pod install）。Android 会通过 Gradle 自动链接，无需手动操作。
• Metro 的打包器缓存经常会掩盖 Scandit 包升级。如果插件版本升级后重新构建仍显示旧行为，请使用 --reset-cache 启动 Metro。
• SparkScanView 是一个 React 组件，会包裹其子组件——原生扫描控件会覆盖在 JSX 树上方。子组件会渲染在原生触发按钮、工具栏和迷你预览下方。不要将 SparkScanView 作为与内容并列的组件渲染。
• iOS（ios/<App>/Info.plist 中的 NSCameraUsageDescription）和 Android（通过 PermissionsAndroid 在运行时请求）都需要相机权限——插件会自动声明 Android 清单权限。

意图路由

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

• 从零开始集成 SparkScan（例如：“将 SparkScan 添加到我的应用”“设置条码扫描”“如何在 React Native 中使用 SparkScan”“如何处理 SparkScan 中的反馈”）→ 阅读 references/integration.md，并遵循其中的说明。
• 迁移或升级现有的 SparkScan 集成（例如：“从 v6 升级到 v7”“迁移我的 SparkScan”“将 Scandit 包升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并遵循其中的说明。
• 用 SparkScan 替换第三方扫描器（例如：“从 expo-camera CameraView 迁移到 SparkScan”“将 react-native-vision-camera 的 useCodeScanner / useBarcodeScannerOutput 替换为 Scandit”“将我们的条码扫描库换成 SparkScan”）→ 阅读 references/third-party-migration.md，并遵循其中的说明。

API 使用政策

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

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

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

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

框架变体策略

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

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

许可证密钥

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

请按以下顺序操作——绝不要因为 MCP 而让用户等待：

1. Scandit MCP 服务已连接——使用产品 native、平台 ios 和 android、app_identifier（应用的 bundle 或 application ID；对于 Web 应用，填写其生产域名，绝不能填写 localhost）和 env_var SCANDIT_LICENSE_KEY 调用 ensure_scanner_setup。不要运行它返回的命令。然后使用该结果中的密钥 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 集成	开始使用 · 示例
高级主题（自定义反馈、硬件触发器、扫描模式、UI 自定义）	高级配置
在主要 SDK 版本之间迁移	6 → 7 · 7 → 8
完整 API 参考	SparkScan API