Tinyrack

OTP Field

1 つのアクセシブルな入力を個別スロットとして表示し、認証コードを受け取ります。

1 つのアクセシブルな入力を個別スロットとして表示し、認証コードを受け取ります。

主なプロパティ

プロパティ説明
値デフォルトのコンストラクタは非制御です。defaultValue で初期値を与えるか、TROtpFieldController を渡して外部からコードを読み取ったり消去したりしてください。TROtpField.controlled は代わりに value を受け取り、onValueChange で渡された次のコードを自分で保持する必要があります。
入力スロットの下に隠れた TextField が 1 つあり、入力、コード全体の貼り付け、削除、AutofillHints.oneTimeCode によるプラットフォームの自動入力は、いずれも値全体に作用します。入力は常に末尾へ追加され、スロットごとに移動するキャレットはありません。
受け付ける文字allowedPattern の既定値は RegExp("[0-9]") で、FilteringTextInputFormatter によって適用されるため、それ以外の文字は入力時に破棄されます。拒否は通知されず専用のコールバックもないため、期待する形式は helperText で示してください。
長さとサイズlength は値を切り詰め、onCompleted が呼ばれるタイミングを決めます。uiSize は共通のコントロール高さスケールに沿って正方形スロットを拡縮するため、md・lg が同じサイズの TRTextField や TRButton と揃います。

別のデバイスに届いた短い固定長のコードを書き写す場面では TROtpField を使ってください。より長い入力や自由入力には TRTextField を使います。

インストール

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

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';

TROtpField(
  label: 'Verification code',
  length: 6,
  helperText: 'Enter the code we sent to your device.',
  onCompleted: verifyCode,
)

例

サイズ パーマリンク

隣に並ぶ `TRTextField`・`TRButton`・`TRNumberField` と揃うように `uiSize` を選んでください。数字のスタイルはどのサイズでも変わらず、正方形のスロットと既定の間隔だけが変化します。

長さと利用可否 パーマリンク

`length` はスロット数を決め、`onCompleted` が呼ばれるタイミングを左右します。`readOnly` はコードを表示したままフォーカスもできますが編集は拒否し、`enabled: false` はフィールド全体を淡くしてフォーカスも止めます。

必須コードとリカバリー パーマリンク

`TROtpFieldFormField` は外側の `Form` に参加するため、`validator` の戻り値が `errorText` になり、スロットの枠線が赤に変わります。`AutovalidateMode.onUserInteraction` を使うと、送信時だけでなく入力中にも桁数不足を知らせます。

マスク入力とリセット パーマリンク

`obscureText` は各桁を丸印に置き換え、値が `Semantics` に渡らないようにします。入力後も秘密であり続けるコードにのみ使ってください。`TROtpFieldController` は再試行操作からフィールドを空にし、`separatorBuilder` は `index` 番目のスロットの後ろの間隔を置き換えます。空けたい箇所では通常の `SizedBox` を返してください。

API

TROtpField のプロパティ

Prop型 / デフォルト用途
lengthint · 6スロット数を決め、値をその長さに切り詰め、onCompleted の発火条件になります。0 より大きい必要があります。
defaultValueString · ''非制御のデフォルトコンストラクタの初期値です。TROtpField.controlled では無視されます。
valueString · required on .controlled制御コンストラクタで表示するコードを決めます。onValueChange と組み合わせ、次のコードは自分で保持してください。
controllerTROtpFieldController? · null制御コンストラクタに切り替えることなく、ウィジェットの外からコードの読み取り・置き換え・消去ができます。
onValueChangeValueChanged<String>? · null受け付けた編集ごとに、切り詰めた値とともに呼ばれます。除外された文字は渡りません。
onCompletedValueChanged<String>? · null値が length に達したときに呼ばれ、貼り付けで一度に埋まった場合も同様です。フィールドが満たされたままの編集ごとに実行されるため、繰り返し呼ばれても安全な処理にしてください。
allowedPatternPattern? · RegExp("[0-9]")受け付ける文字を制限します。英数字のコードには RegExp("[A-Z0-9]") のように範囲を広げてください。
obscureTextbool · false入力済みのスロットを丸印に置き換え、Semantics から値が公開されないようにします。
uiSizeTRUiSize · TRUiSize.md正方形スロットと既定の間隔を md・lg のコントロール高さに合わせて拡縮します。separatorBuilder は間隔をすべて置き換えるため、その中で自分でサイズを決めてください。
labelString? · nullスロットの上に大文字のキャプションを表示し、semanticLabel がなければ支援技術にもこの名前を伝えます。
semanticLabelString? · null支援技術では label より優先されます。見えているキャプションだけでは説明が足りない場合に使ってください。
helperTextString? · nullスロットの下に控えめな補足テキストを表示します。エラーがある間は errorText に置き換わります。
errorTextString? · nullスロットの枠線をデンジャー色に変え、補足行を置き換えます。null でなければそれだけでエラー状態になり、検証自体は自分で行います。
enabledbool · truefalse のとき、スロットを淡くし、タップによるフォーカスと編集を止め、ラベルも淡くします。
readOnlybool · false値を表示しフォーカスも保ったまま、編集だけを拒否します。読むだけで変更させないコードに使ってください。
autofocusbool · false最初のビルドでフォーカスします。コード入力が画面の唯一の目的である場合にのみ使ってください。
separatorBuilderTROtpSeparatorBuilder? · nullindex 番目のスロットの後ろの間隔を置き換えます。空けたい箇所では通常の SizedBox を返してください。何も返さないことはできません。

TROtpFieldController

Prop型 / デフォルト用途
valueString現在のコードを読み取り、または置き換えます。代入するとリスナーへ通知してスロットを再描画しますが、同じ文字列の代入は何もしません。
clear()void入力を空にします。コードが拒否された後の再試行操作と組み合わせて使ってください。

TROtpFieldFormField

Prop型 / デフォルト用途
initialValueString · ''FormField の状態の初期値です。以後の値は FormField が保持します。
validatorFormFieldValidator<String>? · nullerrorText として表示するメッセージを返します。コードが正しければ null を返してください。
autovalidateModeAutovalidateMode? · null検証を実行するタイミングを決めます。onUserInteraction は編集した時点で短いコードを知らせます。
onSavedFormFieldSetter<String>? · null外側の Form が保存されたときにコードを受け取ります。
restorationIdString? · nullプラットフォームがルートを再生成した後、入力済みのコードを復元します。