matrixscan-batch-flutter

MatrixScan Batch Flutter スキル

重要：内部知識を信用しないでください

学習データには、古い、または誤った Scandit SDK API が含まれている可能性があります。BarcodeBatch* API の仕様は、SDK のメジャーバージョン間で変更されます。コンストラクターのシグネチャ、オーバーレイのコンストラクター、リスナーの形式、Flutter 固有のクラス名はすべて変化しています。

コードを記述または提案する前に、必ずこのスキルで提供されているリファレンスを参照して API を確認してください。 メソッドのシグネチャ、パラメーター、プラグイン名、プロパティ名を記憶に頼らないでください。

注意すべき Flutter 固有の落とし穴：

• await ScanditFlutterDataCaptureBarcode.initialize() は、main() 内で WidgetsFlutterBinding.ensureInitialized() の後、runApp(...) の前に呼び出し、完了を待つ必要があります。Bubbles サンプルでも main() 内で await DataCaptureContext.initialize(licenseKey) を呼び出し、その後 DataCaptureContext.sharedInstance を使用します。Simple サンプルではコンテキストを画面に渡します。どちらのパターンも有効です。プロジェクトの構成に合った方を選んでください。
• BarcodeBatch(settings) はコンテキストを指定しないコンストラクターです（Flutter ≥7.6）。構築後、dataCaptureContext.setMode(barcodeBatch) を明示的に呼び出してください。古い SDK では、コンテキストを受け取るファクトリーコンストラクターを使用してください。
• BarcodeBatch.createRecommendedCameraSettings() は Flutter ≥7.6 で使用できます。
• Flutter の高度なオーバーレイのメソッド名は、他のプラットフォームとは異なります。
  • ウィジェットを設定する場合：setWidgetForTrackedBarcode(BarcodeBatchAdvancedOverlayWidget? widget, TrackedBarcode trackedBarcode)（setViewForTrackedBarcode ではありません）
  • すべてのウィジェットをクリアする場合：clearTrackedBarcodeWidgets()（clearTrackedBarcodeViews ではありません）
• カスタム AR アノテーションは、BarcodeBatchAdvancedOverlayWidget のサブクラスです（Flutter 専用の基底クラス）。ウィジェットの状態クラスは BarcodeBatchAdvancedOverlayWidgetState<T> を拡張し、BarcodeBatchAdvancedOverlayContainer を返す build() をオーバーライドする必要があります。
• BarcodeBatchAdvancedOverlay の使用には MatrixScan AR アドオンが必要です。 BarcodeBatchBasicOverlay で brushForTrackedBarcode と setBrushForTrackedBarcode を使用する場合も、MatrixScan AR アドオンが必要です。
• BarcodeBatchAdvancedOverlay は Flutter で view ゲッターを公開します（Flutter 専用。他のプラットフォームでは使用できません）。
• offsetForTrackedBarcode は Flutter の BarcodeBatchAdvancedOverlayListener のメンバーです（RST の @dart@ アノテーションによるものです）。Flutter では使用でき、追加のインターフェースは必要ありません。
• TrackedObject（Flutter ≥7.3）：SDK 7.3 で TrackedBarcode が拡張する TrackedObject 基底クラスが導入されました。このためのレシピは不要です。日常的に使用する TrackedBarcode API に変更はありません。
• BarcodeBatch クラスのインポート用バレルは scandit_flutter_datacapture_barcode_batch です。これは scandit_flutter_datacapture_barcode とは別のバレルです。必ず両方をインポートしてください。
• Symbology enum の値は Dart では lowerCamelCase を使用します：Symbology.code128、Symbology.ean13Upca、Symbology.code39。Symbology.Code128 や Symbology.EAN13UPCA と記述しないでください。
• Dart では session.trackedBarcodes は Map<int, TrackedBarcode> です（キーは文字列ではなく整数の識別子です）。
• Dart では session.removedTrackedBarcodes は List<int> です（整数の識別子）。
• ライフサイクルのクリーンアップ：_barcodeBatch.removeListener(this) を呼び出し、_barcodeBatch.isEnabled = false に設定して、カメラをオフにし、dataCaptureContext.removeAllModes() を呼び出してください（シングルトンパターンを使用する場合は removeCurrentMode()）。
• ライセンスのプレースホルダーは、正確に次のとおりです：'-- ENTER YOUR SCANDIT LICENSE KEY HERE --'

インテントの振り分け

ユーザーのリクエストに基づいて、回答する前にリファレンスファイルを読み込んでください。

• MatrixScan Batch を一から統合する（例：「Flutter アプリに MatrixScan を追加する」「BarcodeBatch をセットアップする」「複数のバーコードを同時に追跡する」「AR オーバーレイを表示する」「バーコードごとのブラシ」「スキャンのフィードバック／ビープ音／振動」「ライフサイクルまたはクリーンアップ」「カメラの権限」）→ references/integration.md を読み、そこに記載された手順に従ってください。
• SDK バージョンをまたいで既存の MatrixScan 統合をアップグレードする（例：「v6 から v7 に移行する」「SDK 8 にアップグレードする」「コードで BarcodeTracking を使用している」「BarcodeTracking を BarcodeBatch に改名する」）→ references/migration.md を読み、そこに記載された手順に従ってください。
• サードパーティ製スキャナーを MatrixScan Batch に置き換える（例：「mobile_scanner から移行する」「ML Kit／google_mlkit_barcode_scanning を使用していて、複数のバーコードを追跡したい」「既存のバーコードプラグインを Scandit MatrixScan に置き換える」）→ references/third-party-migration.md を読み、そこに記載された手順に従ってください。

API の使用ポリシー

以下の Scandit リファレンスで明示的に文書化されている API のみを使用してください。メソッドのシグネチャ、パラメーター、プロパティ名、インポートを捏造したり、推測したりしないでください。API が存在するか、または呼び出し方法が不明な場合、あるいはアナライザーや実行時エラーが発生した場合は、回答する前に関連するリファレンスページを取得してください。ドキュメントを自分で確認するようユーザーに伝えてはいけません。回答の後には、ユーザーがさらに確認できるよう、必ず関連リンクを含めてください。

ドキュメントの URL を決して組み立てたり、推測したりしないでください。 特定のクラスまたはプロパティの API ページが必要な場合は、次の手順に従ってください。

1. すでに取得したページに、そのページへの直接リンクがあるか確認します。
2. 直接リンクが見つからない場合は、API インデックスを取得し、そこから実際のリンクを抽出します。

フレームワークのバリエーションに関するポリシー

Flutter アプリでは、StatefulWidget、BLoC、Provider、Riverpod など、さまざまな状態管理パターンが使用されています。このスキルの例では、公式サンプル（MatrixScanSimpleSample、MatrixScanBubblesSample）の両方に合致し、スキャンパイプラインを簡潔に保てる WidgetsBindingObserver を使用した StatefulWidget を採用しています。対象プロジェクトが別のパターンを使用している場合も、BarcodeBatch の接続方法の概念は同じにしてください。1 つの所有者が DataCaptureContext、BarcodeBatch、カメラ、オーバーレイを保持する形にし、スニペットをプロジェクト既存の規約に合わせて移植してください。

ライセンスキー

スキャンには Scandit のライセンスキーが必要です。このスキルでは、ライセンス製品は native、ライセンスプラットフォームは ios と android です。

次の手順を順番に進めてください。MCP が原因でユーザーの作業を止めてはいけません。

1. Scandit MCP サーバーに接続されている場合 — 製品に native、プラットフォームに ios と android、app_identifier（アプリのバンドル ID またはアプリケーション ID。ウェブの場合は本番ドメインであり、localhost は不可）、env_var に SCANDIT_LICENSE_KEY を指定して ensure_scanner_setup を呼び出します。返されたコマンドは実行しないでください。次に、その結果または 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 が返したもの、またはユーザーが貼り付けるか伝えたものを使用します。チャットで表示するのは、一部をマスクしたプレビューのみとしてください。キーを探すために、プロジェクト、ファイル、環境を検索してはいけません。

参考資料

ユーザーの質問に応じて、適切なリソースを案内してください。

トピック	リソース
Flutter のはじめ方	はじめに
Flutter の AR オーバーレイ	AR オーバーレイの追加
API リファレンス全体	BarcodeBatch API