パッケージの概要と技術基盤

flutter_confetti は、Flutterアプリケーションに動的な祝賀演出やインタラクションフィードバックを導入するためのオープンソースライブラリです。Dart言語で構築されており、パーティクルベースの描画アルゴリズムを用いて、GPUアクセラレーションに対応した高速な紙吹雪アニメーションをウィジェット階層に統合します。カスタマイズ性の高い設計により、色彩、物理挙動、再生タイミングを独自に定義することが可能です。

依存関係の統合手順

開発環境への導入は、プロジェクトの依存管理ファイルを通じて実施します。pubspec.yaml の該当セクションにパッケージ宣言を追記し、ターミナルから依存解決コマンドを実行することで、ローカルキャッシュへのダウンロードとインポート準備が完了します。バージョン指定はSemVer準拠の最新安定版を確認し、必要に応じて範囲指定を行ってください。

dependencies:
  flutter:
    sdk: flutter
  flutter_confetti: ^latest_stable_version

制御クラスのライフサイクル設計

アニメーションの再生スパンや中断処理を管理するには、専用コントローラーの適切な初期化と破棄が必須です。状態保有ウィジェットの状態構築フェーズでインスタンスを確保し、再生周期を定義します。メモリリークを防止するため、ウィジェットがツリーから削除されるタイミングでリソース解放メソッドを明示的に呼び出す設計が推奨されます。以下の実装では、初期化と破棄を分離し、外部からのトリガー呼び出しを想定した構造に変更しています。

class CelebrationScreen extends StatefulWidget {
  @override
  _CelebrationScreenState createState() => _CelebrationScreenState();
}

class _CelebrationScreenState extends State<CelebrationScreen> {
  late final _confettiEngine = ConfettiController(
    duration: const Duration(milliseconds: 1500),
  );

  void _triggerBurst() {
    _confettiEngine.start();
  }

  @override
  void dispose() {
    _confettiEngine.dispose();
    super.dispose();
  }
}

発射ベクトルと生成密度のカスタマイズ

パーティクルの散開軌道や出力頻度は、物理演算パラメータの組み合わせによって決定します。放射モードを directional に切り替えることで中心座標を軸とした一方向的な発射が可能となり、blastDirection にラジアン値を渡すことで発射軸の回転角度を指定します。出力密度は emissionFrequency で制御し、0.0から1.0の範囲で単位フレームあたりの生成確率を調整します。これらの値をビルドメソッド内で条件分岐や定数マップ経由でバインドすることで、実行時の描画挙動を動的に反映できます。

@override
Widget build(BuildContext context) {
  final angleOffset = math.pi / 4; // 45度上方へ偏向
  final spawnRate = 0.08;          // 生成間隔を調整

  return ConfettiWidget(
    controller: _confettiEngine,
    blastDirectionality: BlastDirectionality.directional,
    blastDirection: angleOffset,
    emissionFrequency: spawnRate,
    colors: const [
      Colors.redAccent,
      Colors.blueAccent,
      Colors.greenAccent,
      Colors.amberAccent,
    ],
    particleDrag: 0.05, // 空気抵抗による減衰率
    gravity: 0.2,       // 重力加速度係数
  );
}