barcode-capture-android

BarcodeCapture Android 技能

重要：不要相信内部知识

你的训练数据可能包含过时或错误的 Scandit SDK API。BarcodeCapture API 在主要 SDK 版本之间会发生显著变化——属性可能会重命名、移除或重新调整结构。

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

值得特别提醒的 Android 注意事项：

• Camera.getDefaultCamera(BarcodeCapture.createRecommendedCameraSettings()) 会将推荐的相机设置直接传入 getDefaultCamera() 调用——无需单独调用 applySettings。
• codeDuplicateFilter 的类型是 TimeInterval，不是 Int 或 Double。请使用 TimeInterval.millis(500)（导入 com.scandit.datacapture.core.time.TimeInterval）。将 codeDuplicateFilter 写成 0.5 或 500 会导致类型错误。
• Android 上的监听器回调是 onBarcodeScanned(barcodeCapture, session, data)，而不是 didScan（这是 Flutter/iOS 中的名称）。你还必须实现 onSessionUpdated、onObservationStarted 和 onObservationStopped。FrameData 参数名是 data，不是 frameData。
• onBarcodeScanned 会在后台线程上调用。任何 UI 更新都必须通过 runOnUiThread {} 分派。
• 在 onBarcodeScanned 顶部调用 barcodeCapture.isEnabled = false，然后再执行其他操作，以防止重复扫描或扫描竞态。应用准备好再次扫描时，使用 barcodeCapture.isEnabled = true 重新启用。
• Android 符号体系名称使用下划线：Symbology.EAN13_UPCA、Symbology.CODE39、Symbology.INTERLEAVED_TWO_OF_FIVE——而不是驼峰命名。
• 在 onPause() 中关闭相机，并在 onResume() 中重新启用。应用进入后台时，相机不得处于活动状态。
• 首次扫描前，请在运行时请求 CAMERA 权限；仅在清单中声明权限并不足够。
• DataCaptureView.newInstance(this, dataCaptureContext) 会创建相机预览小组件。在 Activity 中，将其传给 setContentView(dataCaptureView)。在 Fragment 中，以编程方式将其添加到视图层级中。

意图路由

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

• 从头集成 BarcodeCapture、配置设置、自定义反馈、添加取景器、处理扫描，或在扫描后执行异步操作（例如“将 BarcodeCapture 添加到我的应用中”“设置条码扫描”“如何在 Android 中使用 BarcodeCapture”“筛除重复扫描”“关闭蜂鸣声”“添加取景器”“查询条码时禁用扫描”）→ 阅读 references/integration.md，并遵循其中的说明。
• 迁移或升级现有的 BarcodeCapture 集成（例如“从 v6 升级到 v7”“迁移我的 BarcodeCapture”“将 Scandit SDK 升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并遵循其中的说明。
• 用 BarcodeCapture 替换第三方条码扫描器（例如“用 BarcodeCapture 替换我的 ZXing 扫描器”“从 ML Kit 条码扫描迁移到 Scandit”“从 [library] 切换到 BarcodeCapture”）→ 阅读 references/third-party-migration.md，并遵循其中的说明。

API 使用政策

只能使用下方 Scandit 参考资料中明确记载的 API。不要编造或猜测方法签名、参数或属性名称。如果不确定某个 API 是否存在或如何调用，或出现编译错误，请先获取相关参考页面，再作答。不要让用户自己查阅文档。回答后，务必附上相关链接，方便用户进一步了解。

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

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

URL 结构可能有所不同（例如 api/ui/ 子目录），猜测 URL 会导致 404 错误。

许可证密钥

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

按以下顺序操作——切勿因 MCP 阻碍用户：

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

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

参考资料

根据用户的问题，为其提供相应的资源：

主题	资源
入门	入门 · 示例
高级主题（自定义反馈、取景器、位置选择、扫描意图、复合码）	高级配置
主版本 SDK 之间的迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeCapture API