第３回【Flutter Widget解説】SearchBar & SearchAnchor：ユーザーに使いやすい検索UIを実装する方法

【Flutter Widget解説】SearchBar & SearchAnchor：ユーザーに使いやすい検索UIを実装する方法

Flutter公式YouTube「Widget of the Week」は、Flutterの便利なWidgetを短時間で紹介するシリーズです。
今回はSearchBarとSearchAnchorについて、要点を整理しながら使い方を解説します。

📺 元動画：SearchBar & SearchAnchor (Widget of the Week #7)

---

💡 SearchBarとは？

• Material Designに準拠した検索バーコンポーネント
• ユーザーがアプリ内コンテンツを検索できるUIを提供
• 主な特徴
  • leading（先頭アイコン）やヒントテキストの表示
  • デザインカスタマイズ（背景色・影・高さ・形状・パディングなど）
  • ユーザー操作に対応する複数のコールバック

---

🎯 SearchBarの主なプロパティとコールバック

プロパティ / コールバック	説明
backgroundColor	バーの背景色
shadowColor	影の色
elevation	高さ（影の強さ）
shape	バーの形状
padding	内側余白
onChanged	入力テキストが変わるたびに呼ばれる
onSubmitted	ユーザーが検索を確定したときに呼ばれる（例：Enterキー押下）
onTap	バーがタップされたとき
onTapOutside	フォーカス中にバーの外をタップしたとき

---

💡 SearchAnchorとは？

• SearchBarと組み合わせて使う、検索候補を表示するオーバーレイUI
• SearchAnchor.bar コンストラクタを使えば、SearchBar込みで作成可能
• 必須：suggestionsBuilder
  • BuildContextとSearchControllerを受け取り、候補リストを返す
  • ユーザーの入力に応じて候補をフィルタリング可能

---

🔍 SearchBar — 全プロパティと意味

SearchBar({
  Key? key, // ウィジェットの一意識別子
  TextEditingController? controller, // 入力テキストを管理するコントローラー
  FocusNode? focusNode, // フォーカス状態を管理するノード
  String? hintText, // ヒント文字列（プレースホルダー）
  Widget? leading, // バーの先頭に表示するアイコンやウィジェット
  Iterable<Widget>? trailing, // バーの末尾に表示するアイコンやボタンのリスト
  GestureTapCallback? onTap, // バーがタップされた時のコールバック
  TapRegionCallback? onTapOutside, // バー外をタップしたときのコールバック
  ValueChanged<String>? onChanged, // 入力テキスト変更時のコールバック
  ValueChanged<String>? onSubmitted, // エンターや確定時のコールバック
  BoxConstraints? constraints, // バー全体のサイズ制約
  MaterialStateProperty<double?>? elevation, // 影の高さ（立体感）
  MaterialStateProperty<Color?>? backgroundColor, // 背景色
  MaterialStateProperty<Color?>? shadowColor, // 影の色
  MaterialStateProperty<Color?>? surfaceTintColor, // サーフェスの色味調整
  MaterialStateProperty<Color?>? overlayColor, // タップ時などのオーバーレイ色
  MaterialStateProperty<BorderSide?>? side, // 枠線スタイル
  MaterialStateProperty<OutlinedBorder?>? shape, // 枠の形状（丸角など）
  MaterialStateProperty<EdgeInsetsGeometry?>? padding, // 内側余白
  MaterialStateProperty<TextStyle?>? textStyle, // 入力文字スタイル
  MaterialStateProperty<TextStyle?>? hintStyle, // ヒント文字スタイル
  TextCapitalization? textCapitalization, // 自動大文字化の設定
  bool enabled = true, // 入力可否
  bool autoFocus = false, // 初期表示時にフォーカスするか
  TextInputAction? textInputAction, // キーボードのアクションボタン
  TextInputType? keyboardType, // キーボード種別（text, numberなど）
  EdgeInsets scrollPadding = const EdgeInsets.all(20.0), // フォーカス時のスクロール余白
  EditableTextContextMenuBuilder? contextMenuBuilder, // 長押しメニューのカスタマイズ
})

🔍 SearchAnchor.bar — 全プロパティと意味

SearchAnchor.bar({
  // --- バーの見た目・動作関連 ---
  Widget? barLeading, // バーの先頭に表示するアイコンやウィジェット
  Iterable<Widget>? barTrailing, // バー末尾に表示するアイコンやボタン
  String? barHintText, // バーのヒント文字列
  GestureTapCallback? onTap, // バーがタップされた時
  ValueChanged<String>? onSubmitted, // 入力確定時
  ValueChanged<String>? onChanged, // 入力変更時
  VoidCallback? onClose, // 検索ビューが閉じられた時
  VoidCallback? onOpen, // 検索ビューが開かれた時
  MaterialStateProperty<double?>? barElevation, // バーの影の高さ
  MaterialStateProperty<Color?>? barBackgroundColor, // バー背景色
  MaterialStateProperty<Color?>? barOverlayColor, // タップ時オーバーレイ色
  MaterialStateProperty<BorderSide?>? barSide, // バーの枠線
  MaterialStateProperty<OutlinedBorder?>? barShape, // バーの形状
  MaterialStateProperty<EdgeInsetsGeometry?>? barPadding, // バー内側余白
  MaterialStateProperty<TextStyle?>? barTextStyle, // 入力文字スタイル
  MaterialStateProperty<TextStyle?>? barHintStyle, // ヒント文字スタイル

  // --- 検索ビュー（オーバーレイ）関連 ---
  EdgeInsetsGeometry? viewBarPadding, // ビュー内のバー余白
  ViewBuilder? viewBuilder, // ビュー全体のカスタム構築
  Widget? viewLeading, // ビュー先頭のウィジェット
  Iterable<Widget>? viewTrailing, // ビュー末尾のウィジェット
  String? viewHintText, // ビュー内のヒント文字列
  Color? viewBackgroundColor, // ビュー背景色
  double? viewElevation, // ビュー影の高さ
  BorderSide? viewSide, // ビュー枠線
  OutlinedBorder? viewShape, // ビュー形状
  double? viewHeaderHeight, // ビューのヘッダー高さ
  TextStyle? viewHeaderTextStyle, // ビューヘッダー文字スタイル
  TextStyle? viewHeaderHintStyle, // ビューヘッダーヒントスタイル
  Color? dividerColor, // 区切り線の色
  BoxConstraints? constraints, // バー全体の制約
  BoxConstraints? viewConstraints, // ビュー全体の制約
  EdgeInsetsGeometry? viewPadding, // ビュー内の余白
  bool? shrinkWrap, // コンテンツサイズに合わせるか
  bool? isFullScreen, // ビューを全画面表示にするか

  // --- 検索ロジック関連 ---
  SearchController searchController, // 検索状態を管理するコントローラー
  TextCapitalization textCapitalization, // 入力自動大文字化
  required SuggestionsBuilder suggestionsBuilder, // サジェストの構築関数（必須）
  TextInputAction? textInputAction, // キーボードアクション
  TextInputType? keyboardType, // キーボード種別
  EdgeInsets scrollPadding, // スクロール余白
  EditableTextContextMenuBuilder contextMenuBuilder, // 長押しメニュー
  bool enabled, // 入力可否
})

✅ まとめ：SearchBar & SearchAnchorの活用ポイント

・SearchBar
簡単にMaterialデザイン準拠の検索バーを作成可能
豊富なプロパティでカスタマイズしやすい
・SearchAnchor
入力中に候補をオーバーレイ表示できる
suggestionsBuilderで候補表示を自由に構築可能
SearchControllerで外部から状態管理可能

💡 活用例
ローカルデータ検索
API連携でのリアルタイム候補表示
候補タップで詳細画面に遷移（GoRouterなど）