flutter-visual-effects

Flutter ビジュアルエフェクト

意図するマテリアルや光学的な挙動を、エフェクトパッケージをデザインシステムとして扱うことなく、保守しやすい Flutter のレンダリングスタックへ反映します。

スコープ

エフェクトの忠実度、レイヤーの合成、ぼかしと屈折の実装、シェーダーまたは CustomPainter の選択、エフェクトのグループ化、プラットフォーム／バックエンドのフォールバック、レンダリング後のエフェクト検証を担当します。

製品でそのエフェクトを使うべきかどうかは flutter-ui-design に引き継ぎます。タイミング、振り付け、スプリング、Hero、中断時の挙動は flutter-animation に、計測されたジャンクの診断は flutter-performance に、ネイティブビューやプラットフォームチャネルは flutter-platform-integration に引き継ぎます。

事前確認

1. pubspec.yaml、Flutter／Dart の制約、対応プラットフォーム、有効なグラフィックパッケージ、対象サーフェス周辺のレンダリングコードを調べます。
2. 同等のコンテンツ、背景、状態、ビューポートで、提供されたリファレンスを調べます。背景に依存するエフェクトの証拠として、孤立した半透明の四角形だけでは不十分です。
3. 重要な光学的挙動を明らかにします。ぼかし、色合い、エッジのハイライト、奥行き、屈折、形状のブレンド、グロー、ノイズ、応答性のある変形などです。
4. 必要なプラットフォーム範囲、許容できる忠実度の低下、アクセシビリティ上のフォールバック、代表的なハードウェアでプロファイルを実行できるかを確認します。
5. プロジェクトの現在のレンダリング方法と依存関係を起点にします。既存のエフェクト実装で十分なものは維持し、好みの違いだけを理由にコアコードや別のパッケージへ置き換えないでください。

思想ではなく根拠に基づいて選択する

1. テーマやフォールバック動作も含め、プロジェクトですでに使われている十分なソリューションやパッケージを再利用します。
2. Flutter コアで明確に表現できるシンプルなエフェクトには、デコレーション、グラデーション、マスク、シャドウ、CustomPainter、クリップした BackdropFilter を使います。既存の背景ではなく、特定の子だけをフィルタリングする場合は ImageFiltered を使います。
3. 複雑で一般的な機能について、プロジェクトの SDK、レンダラー、プラットフォーム、ライセンス、保守状況、パフォーマンスの制約を満たし、実装リスクを大幅に減らせる場合は、保守されているパッケージを使います。
4. エフェクトが製品固有である場合、採用可能なパッケージでは忠実度やプラットフォーム要件を満たせない場合、または制御性が保守コストに見合うと計測で確認できた場合は、カスタムフラグメントシェーダーまたはレンダラーを使います。
5. ネイティブのレンダリングそのものが要件である場合に限り、ネイティブ連携を使います。それ以外のすべての対応対象でも、定義済みの動作を維持してください。

選定記録には、確認済みの既存ソリューション、コア／パッケージ／カスタム／ネイティブの選択が忠実度を保つ最小の方法である理由、その選択を覆す根拠を明記する必要があります。デモがリファレンスに似ているというだけでパッケージを追加せず、十分に保守されている依存関係が成熟した基盤を提供しているなら、それを自前で実装しないでください。

エフェクトパッケージや共有レンダラーがすでに存在する場合、コードを提案する前に、その pubspec／ロックファイルのエントリー、ソースでの使用状況、テーマの契約、対応ターゲット、フォールバックを明示的に確認してください。変更前の安定したフィクスチャを維持し、変更後は同じコンテンツとビューポートで比較します。スクリーンショットやプロファイル計測値には、計画済みか実測済みかを明記してください。確認の結果、パッケージで十分な場合は、並行するレンダラーに置き換えず、そのパッケージを拡張してください。

通常のコアマテリアル実装では、選定記録に次の内容を明記します。BackdropFilter はサーフェスの背後に描画済みのコンテンツをサンプリングすること、ImageFiltered は所有する単一の子をフィルタリングすること、エフェクトパッケージは追加しないこと、装飾レイヤーにはセマンティクスも押下・ホバー・フォーカスの操作性も持たせないことです。

実装上の不変条件

• フィルターは有用な最小範囲にクリップします。範囲を限定しないバックドロップフィルターは、表示されている表面よりもはるかに広いシーンを処理する場合があります。
• ガラス表現は複数のレイヤーで構成します。サンプリングした背景、調整可能なぼかしまたは屈折、色味、境界線／ハイライト、そして読みやすいコンテンツの順です。不透明度を調整するだけではガラス表現になりません。
• 光学効果はセマンティクスとヒットテストの背後に配置します。装飾用または読み取り専用のレイヤーには、押下、ホバー、フォーカス、インタラクティブな発光のような操作可能な要素の外観を持たせないでください。それらを持たせるのは実際のコントロールだけです。
• SDK とコンポジションで可能な場合は、共有の効果レイヤーを再利用またはグループ化します。スクロールする各行の背後に、独立したライブぼかしやシェーダーを配置しないでください。
• 効果の設定はセマンティックに基づいて一元管理し、対応していないレンダラー、透明度の低減、高コントラスト、性能が制限されたハードウェア向けに、不透明または低コストな代替手段を用意します。
• 形状が変化しても、安定した識別情報を維持します。アニメーションの時間は所有者が制御し、効果レイヤーはその状態から形状とユニフォームを導出します。
• Apple ネイティブのマテリアルとピクセル単位で一致すると主張しないでください。再現した移植可能な特性と、近似したネイティブの光学的動作を報告してください。

条件付きで参照する資料

• SwiftUI、Liquid Glass、Material、PhaseAnimator、または matched-geometry の参照表現を Flutter で再現する必要がある場合は、iOS effect translation を参照してください。
• カスタム GLSL、FragmentProgram、背景の歪み、効果パッケージ、レンダラー互換性、または GPU コストが対象となる場合は、shaders, packages, and performance を参照してください。

検証

明るいテーマと暗いテーマで、比較的シンプルな背景と要素の多い背景の両方に効果をレンダリングします。通常、高コントラスト、不透明または低コストなフォールバックの各テストケースを比較する際は、ビューポート、コンテンツ、効果の形状、インタラクションの状態を同じに保ちます。該当する場合は、インタラクティブな状態または形状が変化した状態をキャプチャします。読みやすさ、クリッピング、エッジのアーティファクト、スクロールの動作、テキストの拡大、高コントラスト、動きの低減、利用可能な透明度低減の経路を確認します。

ゴールデンテストでは、決定論的な形状と描画結果を固定できます。ただし、プラットフォームのコンポジション、システムクローム、またはバックエンド固有のシェーダーに関する主張には、デバイスのスクリーンショットが必要です。負荷の高いぼかし、シェーダー、または継続的にアニメーションする効果は、代表的なハードウェアでプロファイルモードを使用してプロファイリングします。デバッグモードでの結果を一般化せず、テストしたレンダラー、デバイスのクラス、シーン、フォールバックを報告してください。

ソース

• カスタム描画とグラフィックス
• フラグメントシェーダーの作成と使用
• BackdropFilter
• ImageFilter