syncfusion-winui-numberbox

WinUI NumberBox の実装

Syncfusion WinUI NumberBox（SfNumberBox）は、数値を入力するための検証、カスタム書式設定、インタラクティブな機能を備えた高度な数値入力コントロールです。

このコンポーネントを使用する場面

次のような場合に NumberBox を使用します。

• 検証機能付きで数値入力を受け付ける
• 通貨、パーセント、または小数形式で値を表示する
• 入力値を特定の範囲（最小値／最大値）に制限する
• 値を調整する UpDown ボタンを用意する
• 複数の数値データ型（double、decimal、int、long など）に対応する
• キーボードやマウスホイールによる値の変更を有効にする
• ウォーターマークテキストやプレースホルダー値を扱う

コンポーネントの概要

NumberBox コントロールは、次の主要な機能を備えています。

• 数値の検証 - 入力を自動的に検証し、書式設定します
• 複数の書式 - 通貨（C）、パーセント（P）、小数（N）、およびカスタム書式
• 値の制御 - 最小値／最大値の境界と null の処理
• インタラクティブな調整 - UpDown ボタン、キーボードの矢印キー、マウススクロール
• データ型のサポート - Double、Decimal、Float、Long、Int、UInt、Byte、SByte
• アクセシビリティ - キーボードによる完全なナビゲーションとスクリーンリーダーのサポート

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールと NuGet パッケージの設定
• XAML および C# での NumberBox の追加
• 基本的なコントロールの作成
• サポートされるデータ型（Double、Decimal、Float、Long、Int、UInt、Byte、SByte）
• プレースホルダーテキストと説明のプロパティ
• Header のカスタマイズ
• Enter キーの押下時／フォーカス喪失時の値の編集と検証

UpDown ボタンと値の調整

📄 参照： references/updown-button.md

• UpDown ボタンの配置モード（Hidden、Inline、Compact）
• キーボード／マウスでの増分に使用する SmallChange
• Page Up／Page Down での増分に使用する LargeChange
• TextBox の表示制御
• キーボードのサポート（矢印キー、Page キー）
• 値を変更するマウススクロール

値の書式設定

📄 参照： references/formatting.md

• CustomFormat プロパティ（C2、P2、N3 形式）
• NumberFormatter クラス（CurrencyFormatter、PercentFormatter、DecimalFormatter）
• 地域／カルチャーのサポートを使用した通貨の書式設定
• パーセントと小数の書式設定
• 整数部と小数部の桁数制御
• カルチャー固有の書式設定
• CustomFormat と NumberFormatter の併用

値の制限と検証

📄 参照： references/restrictions.md

• null 値の処理に使用する AllowNull プロパティ
• 最小値と最大値の境界
• 範囲の検証動作
• 読み取り専用モードにする IsEditable プロパティ
• テキスト編集の制限
• AllowNull=false の場合の既定値へのフォールバック

クイックスタートの例

基本的な NumberBox の設定

XAML：

<editors:SfNumberBox 
    x:Name="priceInput"
    HorizontalAlignment="Center"
    VerticalAlignment="Center"
    Header="Price"
    Value="0"
    Minimum="0"
    Maximum="999.99"
    CustomFormat="C2" />

C#：

SfNumberBox priceInput = new SfNumberBox();
priceInput.Header = "Price";
priceInput.Value = 0;
priceInput.Minimum = 0;
priceInput.Maximum = 999.99;
priceInput.CustomFormat = "C2";

// Handle value changes
priceInput.ValueChanged += (s, e) => {
    var newValue = e.NewValue;
    var oldValue = e.OldValue;
};

一般的な実装パターン

パターン 1：通貨入力フィールド

用途： ユーザーが金額を入力する場合

<editors:SfNumberBox 
    Header="Amount"
    Value="0"
    CustomFormat="C2"
    Minimum="0"
    Maximum="10000"
    AllowNull="False"
    SmallChange="1" />

パターン 2：パーセント入力フィールド

用途： ユーザーがパーセント値を入力する場合

<editors:SfNumberBox 
    Header="Discount"
    Value="0"
    CustomFormat="P2"
    Minimum="0"
    Maximum="100"
    SmallChange="5" />

パターン 3：UpDown ボタン付きの数量セレクター

用途： ユーザーが離散的な数量を選択する場合

<editors:SfNumberBox 
    Header="Quantity"
    Value="1"
    Minimum="1"
    Maximum="100"
    UpDownPlacementMode="Inline"
    SmallChange="1"
    AllowNull="False" />

パターン 4：調整機能付きの読み取り専用表示

用途： 値を表示しながら UpDown ボタンを使えるようにし、テキスト入力を防ぐ場合

<editors:SfNumberBox 
    Value="50"
    IsEditable="False"
    UpDownPlacementMode="Inline"
    SmallChange="1" />

パターン 5：高精度の小数入力

用途： 金融または科学技術計算が必要な場合

<editors:SfNumberBox 
    ValueType="Decimal"
    Value="1234.56"
    CustomFormat="0.00"
    Minimum="0"
    Maximum="999999.99" />

主要なプロパティの早見表

値のプロパティ

• Value - 現在の数値
• ValueType - データ型（Double、Decimal、Float、Long、Int、UInt、Byte、SByte）
• AllowNull - null／空の値を許可します（既定値：True）

書式設定のプロパティ

• CustomFormat - 書式文字列（C2＝通貨、P2＝パーセント、N3＝小数）
• NumberFormatter - 高度なフォーマッターオブジェクト
• Culture - カルチャー固有の書式設定

範囲のプロパティ

• Minimum - 許可される最小値
• Maximum - 許可される最大値

表示プロパティ

• Header - ラベルテキスト
• HeaderTemplate - カスタムヘッダーレイアウト
• PlaceholderText - 空のときに表示するウォーターマーク
• Description - コントロールの下に表示するヘルプテキスト
• ShowClearButton - クリアボタンの表示／非表示

操作プロパティ

• UpDownPlacementMode - ボタンの位置（Hidden、Inline、Compact）
• SmallChange - 矢印キー／スクロール時の増分（既定値：1）
• LargeChange - Page キー使用時の増分（既定値：10）
• IsEditable - テキスト入力を許可するかどうか（既定値：True）
• TextBoxVisibility - テキストボックスの表示／非表示

イベント

• ValueChanged - 検証後に値が変更されると発生します

一般的な使用例

1. 価格入力 - C2 形式を使用し、現実的な最小値／最大値を設定します
2. 年齢入力 - int の ValueType を使用し、範囲を 0～150 に設定します
3. 割引フィールド - P2 形式を使用し、範囲を 0～100 に設定します
4. 数量ピッカー - Inline UpDown を使用し、実用的な上限／下限を設定します
5. パーセンテージ計算 - 適切な小数桁数で P2 形式を使用します
6. 支払金額 - 通貨の規則に従って C2 形式を使用します
7. 小数精度 - 金融データには Decimal 型を使用します

インストール

NuGet パッケージ

Install-Package Syncfusion.Editors.WinUI

XAML 名前空間

xmlns:editors="using:Syncfusion.UI.Xaml.Editors"

次のステップ

• セットアップの詳細については、はじめにをお読みください
• 値の調整については、UpDown ボタンの機能をご確認ください
• 通貨／パーセンテージのサポートについては、値の書式設定をご覧ください
• 検証と上限／下限については、値の制限をご確認ください