mcpField
S
sparkscan-flutter

sparkscan-flutter

github.com/scandit开发2043 次安装5 天前更新
代码仓库

关于 sparkscan-flutter

sparkscan-flutter 是帮助开发者在 Flutter 应用中集成、升级或替换 SparkScan 的技能。它强调依据 Scandit 参考资料核实 API，并涵盖初始化、组件布局和许可密钥流程。

主要功能

  1. 01按任务加载集成或迁移指南
  2. 02要求依照文档核实 API
  3. 03说明 Flutter 初始化与组件布局
  4. 04提供 iOS 和 Android 权限注意事项
  5. 05指导 Scandit 许可密钥处理
  6. 06适配项目现有状态管理方式

适用场景

  1. 01从零集成 SparkScan 条码扫描
  2. 02升级不同主版本的 SparkScan
  3. 03用 SparkScan 替换第三方扫描器
  4. 04排查 Flutter 插件初始化问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/scandit/skills --skill sparkscan-flutter

安装后在 Claude Code 中输入/sparkscan-flutter确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
integration.md
migration.md
third-party-migration.md

详细介绍

SparkScan Flutter 技能

重要：不要相信内部知识

你的训练数据中可能包含过时或不正确的 Scandit SDK API。SparkScan API 在不同主版本的 SDK 之间变化显著：属性可能会重命名、移除或重构，Flutter 插件接口（导入、插件初始化、pub 包）也经历了演变。

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

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

  • 必须在 main() 中、runApp(...) 之前，并且在 WidgetsFlutterBinding.ensureInitialized() 之后调用并等待 await ScanditFlutterDataCaptureBarcode.initialize()。如果忘记这一步，会产生一个看似与初始化无关的平台通道错误。
  • SparkScanView 是一个 Flutter StatefulWidget，它会包装一个子 Widget；它并不是纯原生覆盖层。子 Widget 会显示在原生扫描控件的下方。不要指示用户将 SparkScanView 与常规 Widget 树分开堆叠。
  • 每次更改软件包版本后，都必须运行 flutter pub get。在 iOS 上，Podfile 会解析传递依赖；除非用户使用自定义设置，否则无需手动安装 Pod。
  • iOS（在 ios/Runner/Info.plist 中配置 NSCameraUsageDescription）和 Android（通过 permission_handler 在运行时请求）都需要相机权限；该插件会自动声明 Android 清单权限。

意图路由

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

  • 从头集成 SparkScan（例如“将 SparkScan 添加到我的应用”“设置条码扫描”“如何在 Flutter 中使用 SparkScan”“如何处理 SparkScan 中的反馈”）→ 阅读 references/integration.md，并遵循其中的说明。
  • 迁移或升级现有的 SparkScan 集成（例如“从 v6 升级到 v7”“迁移我的 SparkScan”“将 Scandit 软件包升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并遵循其中的说明。
  • 用 SparkScan 替换第三方扫描器（例如“从 mobile_scanner 迁移”“用 Scandit 替换 google_mlkit_barcode_scanning”“将现有条码插件换成 SparkScan”）→ 阅读 references/third-party-migration.md，并遵循其中的说明。

API 使用政策

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

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

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

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

框架变体策略

Flutter 应用采用多种状态管理模式（StatefulWidget、BLoC、Provider、Riverpod）。此技能中的示例使用 BLoC 模式，因为它与官方的 ListBuildingSample 一致，能将扫描流程与 widget 树清晰分离，并且与相机生命周期配合良好。如果目标项目已经使用其他模式（Provider、Riverpod、GetX、纯 StatefulWidget），请保持 SparkScan 接入方式的概念不变（由一个所有者持有 DataCaptureContext 和 SparkScan，并向 UI 提供扫描事件），将代码片段移植到项目现有的约定中——不要重写项目的状态管理。

许可证密钥

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

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

  1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，指定产品 native、平台 ios 和 android、app_identifier（应用的 bundle 或 application ID；对于 Web，使用其生产域名，绝不要使用 localhost）以及 env_var SCANDIT_LICENSE_KEY。不要运行它返回的命令。然后使用密钥 ID 调用 get_license_key，该 ID 可以从此结果或 list_license_keys 中获取；如果 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 返回的密钥，或用户粘贴或提供的密钥——聊天中仍只显示经过遮蔽的预览。不要搜索项目、其文件或环境以查找密钥。

参考资料

根据用户的问题，将其引导至相应的资源：

主题资源
Flutter 集成开始使用 · 示例
高级主题（自定义反馈、硬件触发器、扫描模式、UI 自定义）高级配置
主 SDK 版本间的迁移6 → 7 · 7 → 8
完整 API 参考SparkScan API

评论

支持 Markdown