WinUI 3で業務アプリを作っていると、「数量」「金額」「割合」「しきい値」など、数値だけを入力してほしい場面が数多くあります。こうした入力欄をTextBoxで作ると、文字列から数値への変換、入力チェック、最小値・最大値の判定、増減ボタンなどを自前で用意することになりがちです。
WinUI 3には、数値入力に特化したNumberBoxがあります。単に「数字しか入らないTextBox」ではなく、最小値・最大値、増減ステップ、入力検証、数式入力、数値フォーマットまで扱えるコントロールです。今回はTextBoxで数値入力を作る場合との違いを整理しながら、実務で使いやすいNumberBoxの設計を見ていきます。
なぜTextBoxだけでは数値入力が面倒なのか
TextBoxのTextは文字列です。そのため、たとえば数量を入力させる場合、アプリ側ではint.TryParseやdouble.TryParseなどで変換し、変換に失敗した場合の表示を考え、さらに「1以上100以下」といった範囲チェックも行う必要があります。
入力中に数字以外のキーを禁止する方法もありますが、貼り付け、IME、ロケールごとの小数点表記などまで考えると、単純なキーイベント処理だけでは十分ではありません。数値というデータを扱いたいのに、UI側では文字列を相手にし続けることになります。
NumberBoxでは、表示文字列のTextとは別に、数値として扱うValueプロパティがあります。Microsoftも、プログラムから値を変更するときはTextではなくValueを使うことを推奨しています。UIの文字列とアプリ内部の数値を分けて考えられるのが大きな利点です。
まずは最小構成を作る
次は、1～100個の商品数量を入力する例です。上下のスピンボタンを表示し、1個ずつ増減できるようにします。
<NumberBox x:Name="QuantityNumberBox"
Header="数量"
Value="1"
Minimum="1"
Maximum="100"
SmallChange="1"
SpinButtonPlacementMode="Inline"
ValidationMode="InvalidInputOverwritten" />C#側では、文字列を再度パースするのではなくValueを読み取れます。
private void SaveButton_Click(object sender, RoutedEventArgs e)
{
double quantity = QuantityNumberBox.Value;
if (double.IsNaN(quantity))
{
return;
}
// 必要に応じて整数へ変換して利用する
int quantityAsInt = (int)quantity;
}MinimumとMaximumは入力可能な範囲、SmallChangeは上下キーやスピンボタンで増減する量です。SpinButtonPlacementMode="Inline"にすると増減ボタンが常時横に表示されます。スペースを節約したい場合はCompactも選べます。
Valueがdoubleであることを意識する
NumberBoxのValueはdoubleです。数量のように整数しか扱わない画面でも、NumberBox自体が整数専用になるわけではありません。アプリのドメインモデルがintなら、値を取り出したあとで整数として扱う設計が必要です。
もう1つ重要なのが、入力欄が空の場合です。NumberBoxをクリアすると、Valueは「値がない」ことを表すNaNになります。そのため、空欄を許すフォームではdouble.IsNaNで確認できます。TextBoxの空文字列を数値変換して失敗させるより、数値コントロールとして状態を判断しやすくなります。
ValidationModeで「不正入力をどう扱うか」を決める
ValidationMode="InvalidInputOverwritten"を指定すると、ユーザーが数値として解釈できない内容を入力した場合、Enterまたはフォーカス移動による評価時に、最後の有効な値へ戻す動作になります。
一方、独自の入力検証やエラー表示を実装したい場合はValidationMode="Disabled"を利用できます。ここは「厳しい検証を有効にするか」というより、NumberBoxに不正入力の処理を任せるか、アプリ側で扱うかの選択だと考えると分かりやすいです。
業務アプリでは、入力値を黙って補正することが適切とは限りません。たとえば請求金額など重要な値なら、エラー理由を明示して再入力してもらう設計のほうが安全な場合があります。コントロールの機能だけでなく、データの重要度から検証方法を決めることが大切です。
AcceptsExpressionで入力欄を小さな計算機にする
NumberBoxには少し面白い機能があります。AcceptsExpression="True"にすると、加減乗除などの基本的な数式を入力して、その結果を値として利用できます。
<NumberBox x:Name="PriceNumberBox"
Header="金額"
PlaceholderText="例: 1200*3"
AcceptsExpression="True"
SpinButtonPlacementMode="Hidden" />たとえばユーザーが1200*3のような式を入力し、Enterを押すかフォーカスを移動すると式が評価されます。Microsoftのドキュメントでは、乗算・除算・加算・減算に加えて累乗と括弧を含む式評価の規則も説明されています。
これは見積入力や寸法計算など、「別の電卓で計算して結果を貼り付ける」操作が頻繁に発生する業務画面で便利です。ただし、評価後は元の式そのものは保持されません。計算式を履歴として保存する必要があるアプリでは、NumberBoxの式評価だけに任せる設計は向きません。
TextBoxとNumberBoxをどう使い分けるか
判断基準は「見た目が入力欄か」ではなく、「入力されるデータの意味」です。氏名、備考、コードなど文字列として保持したい値ならTextBoxが自然です。一方、数量、金額、割合、温度、しきい値など、最終的に数値として計算や比較へ使う値ならNumberBoxを最初に検討できます。
特に最小値・最大値や増減操作が必要な場合、NumberBoxを使うことでUIと検証ロジックをまとめやすくなります。逆に、郵便番号や社員番号のように数字だけで構成されていても、加算や大小比較をする「数値」ではなく識別子ならTextBoxのほうが適しています。先頭の0を保持したい値も同様です。
実務ではx:BindでViewModelと同期する
画面が大きくなると、コードビハインドから毎回Valueを読むより、ViewModelへバインドするほうが管理しやすくなります。Microsoftの基本例でもx:BindによるTwoWayバインディングが紹介されています。
<NumberBox Header="発注数"
Value="{x:Bind ViewModel.Quantity, Mode=TwoWay}"
Minimum="1"
Maximum="1000"
SmallChange="1"
SpinButtonPlacementMode="Inline" />こうしておけば、画面上の値とViewModelの値を同期できます。ただし、先ほどのとおりValueはdoubleなので、ViewModel側の型設計との整合性は確認してください。整数しか許さない業務ルールをNumberBoxの見た目だけで保証しようとせず、保存時のドメイン側検証も残しておくと安全です。
注意点：ロケールと表示形式を自前で決めつけない
数値入力では、小数点や桁区切りの表記が地域設定によって異なります。NumberBoxはNumberFormatterを設定でき、DecimalFormatterなどを使って小数桁、丸め、表示形式を調整できます。
そのため、「小数点は必ずピリオドだから」と文字列を直接分割するような処理は避けたほうがよいでしょう。通貨や割合を扱う場合も、表示フォーマットと内部の数値を分離して考えることで、ローカライズに強い画面になります。
まとめ
WinUI 3で数値入力を作るなら、まずNumberBoxを検討するとよいでしょう。Valueで数値を直接扱え、Minimum・Maximum、増減ステップ、入力検証、数式評価、フォーマットといった数値入力に必要な機能を一つのコントロールへまとめられます。
一方で、「数字が並んでいるもの＝NumberBox」ではありません。識別子ならTextBox、連続値を直感的に選ぶならSliderなど、データの意味と操作方法に合わせて選ぶことが重要です。入力コントロールを正しく選ぶと、コードが短くなるだけでなく、ユーザーにとっても「ここには何を入力すればよいか」が自然に伝わる画面になります。
参考資料
コメント