Flutter ウィジェットのプレビュー

目次

• プレビューガイドライン
• 制限事項への対応
• ワークフロー
• 例

プレビューガイドライン

Flutter ウィジェットプレビューアを使用して、ウィジェットをリアルタイムで、アプリケーション全体のコンテキストから分離した状態でレンダリングします。

• 対象要素: @Preview アノテーションを、トップレベル関数、クラス内のスタティックメソッド、または必須引数がなく Widget または WidgetBuilder を返すパブリックウィジェットコンストラクタ/ファクトリに適用します。
• インポート: プレビューアノテーションにアクセスするために、常に package:flutter/widget_previews.dart をインポートしてください。
• カスタムアノテーション: Preview クラスを拡張して、複数のウィジェット全体に共通のプロパティ（例：テーマ、ラッパー）を注入するカスタムアノテーションを作成します。
• 複数の設定: 単一の対象に複数の @Preview アノテーションを適用して、複数のプレビューインスタンスを生成します。または、MultiPreview を拡張して、共通のマルチプレビュー設定をカプセル化します。
• ランタイム変換: カスタム Preview または MultiPreview クラスの transform() メソッドをオーバーライドして、ランタイムでプレビュー設定を動的に変更します（例：動的な値に基づいて名前を生成する場合、これは const コンテキストでは不可能です）。

制限事項への対応

ウィジェットプレビューアが Web 環境で実行されるため、プレビュー可能なウィジェットを作成する際は、以下の制約を遵守してください。

• ネイティブ API を使用しない: ネイティブプラグインまたは dart:io や dart:ffi の API を使用しないでください。dart:io または dart:ffi に対する推移的な依存関係を持つウィジェットは、呼び出し時に例外をスローします。条件付きインポートを使用して、プレビューモードでこれらをモックするか、バイパスしてください。
• アセットパス: dart:ui の fromAsset API を経由してロードされるアセットには、パッケージベースのパス（例：assets/my_image.png ではなく packages/my_package_name/assets/my_image.png）を使用してください。
• パブリックコールバック: プレビューアノテーションに提供されるすべてのコールバック引数がパブリックで定数であることを確認して、コード生成要件を満たしてください。
• 制約: ウィジェットが無制約の場合、@Preview アノテーションの size パラメータを使用して明示的な制約を適用します。プレビューアはデフォルトでウィジェットをビューポートの約半分に制約します。

ワークフロー

ウィジェットプレビューを作成する

新しいウィジェットプレビューを実装するときに、このチェックリストをコピーして追跡してください。

• package:flutter/widget_previews.dart をインポートします。
• 有効な対象を特定します（トップレベル関数、スタティックメソッド、または引数なしのパブリックコンストラクタ）。
• @Preview アノテーションをその対象に適用します。
• 必要に応じてプレビューパラメータ（name、group、size、theme、brightness など）を設定します。
• 複数のウィジェットに同じ設定を適用する場合、設定を Preview を拡張するカスタムクラスに抽出します。

プレビューと交互作用する

ウィジェットプレビューアを起動して対話するために、適切な条件付きワークフローに従ってください。

サポートされている IDE（Android Studio、IntelliJ、Flutter 3.38+ を備えた VS Code）を使用している場合:

1. IDE を起動します。ウィジェットプレビューアが自動的に起動します。
2. サイドバーの「Flutter Widget Preview」タブを開きます。
3. 左下の「Filter previews by selected file」を切り替えて、現在のアクティブファイル外のプレビューを表示したい場合は、切り替えます。

コマンドラインを使用している場合:

1. Flutter プロジェクトのルートディレクトリに移動します。
2. flutter widget-preview start を実行します。
3. 自動的に開いた Chrome 環境を表示します。

フィードバックループ：プレビュー反復処理

1. ウィジェットコードまたはプレビュー設定を変更します。
2. ウィジェットプレビューアの自動更新を監視します。
3. グローバル状態（例：スタティック初期化子）が変更された場合：右下のグローバルホットリスタートボタンをクリックします。
4. ローカルウィジェット状態のみをリセットする必要がある場合：特定のプレビューカード上の個別ホットリスタートボタンをクリックします。
5. IDE/CLI コンソールでエラーを確認 → 修正 → 繰り返します。

例

基本的なプレビュー

import 'package:flutter/widget_previews.dart';
import 'package:flutter/material.dart';

@Preview(name: 'My Sample Text', group: 'Typography')
Widget mySampleText() {
  return const Text('Hello, World!');
}

ランタイム変換を使用したカスタムプレビュー

import 'package:flutter/widget_previews.dart';
import 'package:flutter/material.dart';

final class TransformativePreview extends Preview {
  const TransformativePreview({
    super.name,
    super.group,
  });

  PreviewThemeData _themeBuilder() {
    return PreviewThemeData(
      materialLight: ThemeData.light(),
      materialDark: ThemeData.dark(),
    );
  }

  @override
  Preview transform() {
    final originalPreview = super.transform();
    final builder = originalPreview.toBuilder();
    
    builder
      ..name = 'Transformed - ${originalPreview.name}'
      ..theme = _themeBuilder;

    return builder.toPreview();
  }
}

@TransformativePreview(name: 'Custom Themed Button')
Widget myButton() => const ElevatedButton(onPressed: null, child: Text('Click'));

MultiPreview の実装

import 'package:flutter/widget_previews.dart';
import 'package:flutter/material.dart';

/// ライトモードとダークモードのプレビューを自動的に作成します。
final class MultiBrightnessPreview extends MultiPreview {
  const MultiBrightnessPreview({required this.name});

  final String name;

  @override
  List<Preview> get previews => const [
        Preview(brightness: Brightness.light),
        Preview(brightness: Brightness.dark),
      ];

  @override
  List<Preview> transform() {
    final previews = super.transform();
    return previews.map((preview) {
      final builder = preview.toBuilder()
        ..group = 'Brightness'
        ..name = '$name - ${preview.brightness!.name}';
      return builder.toPreview();
    }).toList();
  }
}

@MultiBrightnessPreview(name: 'Primary Card')
Widget cardPreview() => const Card(child: Padding(padding: EdgeInsets.all(8.0), child: Text('Content')));