Tinyrack

Combobox

検索語と選択状態を分け、型付きの候補を 1 つまたは複数選択します。

検索語と選択状態を分け、型付きの候補を 1 つまたは複数選択します。

主なプロパティ

プロパティ説明
状態検索語と選択値は別々の軸です。TRComboboxController が値に加えて TextEditingController と FocusNode を保持し、TRCombobox.controlled は値のみを呼び出し側に渡して検索語は controller が保持し続けます。
フィールドフィールドは TRTextField のため、label、placeholder、helperText、errorText、uiSize、width はそちらと同じ挙動です。clearable を有効にすると、検索語または選択値があるときに末尾スロットへクリアボタンが表示されます。
レイヤーサイズlayerSize はフィールドの width とは別です。デフォルトでは候補レイヤー全体の幅をアンカーに合わせ、高さはコンテンツに応じて TRMeasurements.measureXl まで広げます。
フィルタリングoptionsBuilder が候補を決め、filterMode が contains・startsWith・none のいずれかで絞り込みます。filter コールバックを渡すと filterMode より優先されます。リモートや非同期の optionsBuilder が既に結果を確定している場合は none を使ってください。
複数選択TRMultiCombobox は確定した値をフィールドの上に削除可能なチップとして表示し、選択のたびに検索語を消去します。layout: TRComboboxLayout.grid を指定すると、ポップアップがリストではなく 2 列のグリッドになります。
操作矢印キーでハイライトを移動し、Enter で確定し、Escape でポップアップを閉じます。autoHighlight は、矢印キーを押す前に Enter が最初の一致を確定できるかどうかを決めます。enabled: false の候補は表示されたまま淡く描画され、Enter と矢印移動の双方でスキップされます。
フォームTRComboboxFormField と TRMultiComboboxFormField は FormField のサブクラスなので、validator、onSaved、autovalidateMode、Form.reset は通常どおり動作し、errorText はフィールドの状態から供給されます。

入力のほうがスクロールより速いほど候補が多く、それでも確定値はその一覧から選ばれる必要がある場合に combobox を使ってください。短い固定リストには TRSelect を、利用者が入力した自由テキスト自体が有効な答えになる場合は TRAutocomplete を使ってください。

インストール

パッケージを追加し、公開ライブラリをインポートしてください。

flutter pub add tinyrack_ui
import 'package:tinyrack_ui/tinyrack_ui.dart';

プレイグラウンド

使用方法

import 'package:material_ui/material_ui.dart';
import 'package:tinyrack_ui/tinyrack_ui.dart';

TRCombobox<String>(
  label: 'Channel',
  placeholder: 'Choose a channel',
  items: const [
    TRComboboxItem(value: 'stable', label: 'Stable'),
    TRComboboxItem(value: 'beta', label: 'Beta'),
  ],
  onValueChange: selectChannel,
)

例

絞り込んでラックを 1 つ確定する パーマリンク

入力でポップアップを絞り込みつつ、確定した値は検索語とは別に保たれます。ラックを選ぶと、そのラベルがフィールドへ書き戻されます。

サイズ パーマリンク

uiSize を渡して、隣接する TRTextField、TRSelect、TRButton と高さを揃えます。

選択済みと無効な候補 パーマリンク

enabled を false にした候補はポップアップに残るため、利用できない理由が見えたままになります。淡く描画され、Enter と矢印移動の双方でスキップされます。

フィルタの意味 パーマリンク

contains、startsWith、組み込みの絞り込みなしを比べます。非同期の optionsBuilder が表示したい候補を既に返している場合は none を使ってください。

複数選択のチップとグリッドのポップアップ パーマリンク

TRMultiCombobox は確定した値を削除可能なチップとして表示し、選択のたびに検索語を消去します。グリッドレイアウトは短いラベルを 2 列に収めます。

必須の選択とエラー解消 パーマリンク

TRComboboxFormField はエラーを errorText で伝え、値が確定した時点で解消します。そのため、再送信しなくても状態を回復できます。

制御された状態とカスタムフィルタ パーマリンク

制御コンストラクタは値を呼び出し側に返し、controller が検索語を保持します。組み込みの規則で足りない場合は、filter コールバックが filterMode を置き換えます。

ポップアップの幅とレイヤー パーマリンク

Flutter には portal や positioner に相当するパーツはありません。ポップアップは combobox レイヤーで開き、幅はフィールドから、width が未指定の場合は small のオーバーレイ幅トークンから取得します。

キーボードでの選択 パーマリンク

autoHighlight を無効にすると、矢印キーで行をハイライトするまで Enter では何も確定しません。クリアボタンはフィールドにフォーカスを戻すため、ポップアップは開いたままです。

単一選択と複数選択のフィールド パーマリンク

FormField 版は検索文字列と型付きの選択値を分けたまま、検証、保存、リセットに参加します。

API

TRCombobox のプロパティ

Prop型 / デフォルト用途
itemsList<TRComboboxItem<T>> · const []候補の元データを提供します。items と optionsBuilder のいずれかは必ず指定してください。
optionsBuilderTRComboboxOptionsBuilder<T>? · null検索語に対する候補を同期または Future で返します。filterMode が none でない限り、その結果もさらに絞り込まれます。
filterModeTRComboboxFilterMode · containscontains または startsWith で候補ラベルを大文字小文字を区別せずに照合し、none では絞り込みません。比較には toLowerCase を使うため、React の useFilter の collator と異なりアクセントの違いは無視されません。
filterTRComboboxFilter<T>? · nullfilterMode の代わりに独自の判定関数を使います。渡される検索語は既に前後の空白が除去され、小文字化されています。
autoHighlightbool · true最初の一致を待機状態にして、Enter で即座に確定できるようにします。false にすると先に矢印キーが必要になります。基盤の RawAutocomplete が常に有効なハイライト位置を保つため、React の既定値とは異なり、ここでは true が既定です。
clearable, clearSemanticLabelbool · false, String · 'Clear'検索語または選択値があるときにクリアボタンを表示します。クリアすると検索語を空にし、onValueChange で null を通知したうえで、フィールドにフォーカスを戻します。
controller, defaultValue, valueTRComboboxController<T>?, T?, T?状態モデルを選びます。defaultValue は非制御コンストラクタの初期値、value は TRCombobox.controlled で必須で、controller はどちらとも併用できます。
onQueryChange, onValueChangeValueChanged<String>?, ValueChanged<T?>?検索語の編集と確定した選択を別々に通知します。クリアボタンを押した場合、onValueChange は null でも呼び出されます。
layoutTRComboboxLayout · listポップアップを 1 列のリストまたは 2 列のグリッドとして描画します。
enabled, readOnlybool · true, bool · false操作を無効にするか、フォーカスは可能でも検索語を編集できないフィールドにします。どちらの場合もクリアボタンは表示されません。
label, placeholder, helperText, errorTextString? · null基盤の TRTextField を通じて、フィールドと検証状態を説明します。
uiSize, widthTRUiSize · TRUiSize.md, double? · nullコントロールサイズと任意の固定フィールド幅を指定します。ポップアップのサイズには layerSize を使ってください。
layerSizeTRLayerSize · match anchor / content height ≤ measureXl単一選択、複数選択、FormField バリアントの候補レイヤー全体のサイズを指定します。

TRMultiCombobox のプロパティ

Prop型 / デフォルト用途
defaultValue, valueList<T> · const [], List<T>?確定した値を保持します。value は TRMultiCombobox.controlled で必須であり、指定するとウィジェットは完全な制御モードになります。
onValueChangeValueChanged<List<T>>? · null選択、チップの削除、クリアのたびに選択内容の全体を通知します。既に選択済みの値をもう一度選ぶと解除されます。
controllerTRMultiComboboxController<T>? · null値と共有の検索フィールドを保持します。clear は値のみを消去するため、直接操作する場合は textEditingController も併せて消去してください。

項目と列挙型

Prop型 / デフォルト用途
TRComboboxItem.value, labelT · required, String · required型付きの値と、ポップアップに表示され確定時にフィールドへ書き戻されるテキストを保持します。
TRComboboxItem.enabledbool · true候補を選択不可にします。ポップアップには残り、muted のテキスト色で描画され、キーボード移動ではスキップされます。
TRComboboxItem.leading, trailingWidget? · null候補ラベルの両側にアイコンを配置します。
TRComboboxLayoutlist, gridポップアップの配置を選ぶ列挙型です。grid は高さが固定された行を 2 列で配置します。
TRComboboxFilterModecontains, startsWith, none候補の元データに適用する組み込みの絞り込みルールを選ぶ列挙型です。

Controller とフォームフィールド

Prop型 / デフォルト用途
TRComboboxControllerChangeNotifiervalue、select、clear に加えて、保持する textEditingController と focusNode を公開します。生成したウィジェット側で dispose してください。
TRMultiComboboxControllerChangeNotifiervalues、replace、toggle、clear を公開します。values は変更不可のビューのため、直接変更せずリストを差し替えてください。
TRComboboxFormFieldFormField<T>型付きの選択値で検証と保存コールバックに参加し、errorText をフィールドへ戻します。
TRMultiComboboxFormFieldFormField<List<T>>値のリストに対して同じ役割を果たします。validator で 1 つ以上の選択を必須にできます。