kaze風
NumberField
通貨対応数値入力
プレビュー
¥
%
使いどころ
使う場面
- 数量、金額、割合など、数値として扱う入力。step で増減の幅を決め、min / max で範囲を限る
- 金額は currency（JPY など）で通貨記号と桁区切りを付ける。単位は suffix（%、件）で添える
- 全角数字や「−」の入力を受けたい日本語のフォーム。全角は半角に直して解釈する
使わない場面
- 郵便番号、電話番号、会員番号など、数値ではない数字の並び。先頭の 0 や区切りが意味を持つので Input を使う
- 範囲の大まかな指定。選択肢が少なければ SegmentedControl か Select
- 値が長い桁になる ID。桁区切りを付けて表示されてしまう
使い方
<NumberField
label="金額"
value={15000}
currency="JPY"
onValueChange={(v) => setValue(v)}
/>プロパティ
| 名前 | 型 | デフォルト | 説明 |
|---|---|---|---|
value | number | null | なし | 現在の数値 |
defaultValue | number | null | なし | 初期値（非制御） |
onValueChange | (value: number | null) => void | なし | 値変更時のコールバック（旧 onChange） |
min | number | なし | 最小値 |
max | number | なし | 最大値 |
step | number | 1 | 増減のステップ値 |
currency | "JPY" | "USD" | "EUR" | "GBP" | "CNY" | "KRW" | なし | 通貨コード |
locale | string | なし | 数値の書式に使うロケール（既定は ja-JP） |
showStepper | boolean | true | 増減ボタンを表示するか |
label | string | なし | ラベル |
error | boolean | false | エラー状態 |
errorMessage | string | なし | 入力欄の下に出すエラー文言（role="alert" で読み上げる） |
prefix | string | なし | 接頭辞テキスト（通貨で自動設定） |
suffix | string | なし | 接尾辞テキスト |
decrementLabel | string | なし | Accessible label for decrement button (default: "減少") |
incrementLabel | string | なし | Accessible label for increment button (default: "増加") |
型と必須かどうかはソースの型定義から自動で生成しています。表にない HTML 標準の属性（className や aria-* など）も、ルート要素にそのまま渡せます。
キーボード操作
| キー | 動作 |
|---|---|
| ↑ | step の分だけ増やす |
| ↓ | step の分だけ減らす |
| Enter | 入力を確定する（IME の変換中は確定しない） |
| Tab | 確定して次へ移る。増減ボタンはタブ移動の対象外 |
アクセシビリティ
- 入力欄は type="text" に inputMode="decimal"。スクリーンリーダーでは数値入力ではなくテキスト欄として読まれる
- 増減ボタンの名前は decrementLabel / incrementLabel で変える。既定は「減少」「増加」
- label と errorMessage を自前で持つ。errorMessage は role="alert" で読み上げられ、aria-describedby で結ばれる
- 値の確定はフォーカスが外れたとき。入力中は onValueChange が呼ばれない
文言
- label に単位を含めない。単位は suffix や currency で見せる（label「割引率」、suffix「%」）
- 範囲があるときは、description か errorMessage に「0 から 100 の間で入力してください」のように範囲を書く