syncfusion-winforms-numeric-textbox

Syncfusion WinForms SfNumericTextBox の実装

Syncfusion WinForms SfNumericTextBox コントロールは、高度なテキスト入力コントロールです。包括的な検証機能、カスタマイズ機能、カルチャサポートを備え、複数の形式（数値、通貨、パーセント）で数値を表示および受け付けます。書式設定オプション、値の制約、外観のカスタマイズ、イベント駆動型の機能を提供し、業務向けの数値データ入力シナリオに対応します。

このスキルを使用するタイミング

次のような場合は、必ずこのスキルをすぐに使用してください。

• 数値入力：精度を保って数値を受け付け、表示する
• 書式モード：数値、通貨、またはパーセントの形式に対応する
• 値の検証：最小値と最大値の制約を適用する
• 書式設定：接頭辞／接尾辞を設定したり、末尾のゼロを非表示にしたりする
• ウォーターマーク：コントロールが空のときにプレースホルダーテキストを表示する
• カルチャ別書式設定：複数のカルチャと数値形式に対応する
• 外観のカスタマイズ：値（正数／負数／ゼロ）に応じて色をカスタマイズする
• イベント処理：ValueChanged イベントで値の変更に対応する
• データ入力フォーム：検証済みの数値フィールドを備えた業務向けフォームを作成する

コンポーネントの概要

SfNumericTextBox コントロールは Syncfusion Essential Studio for Windows Forms の一部で、次の機能を提供します。

• 複数の書式モード：数値、通貨、パーセントの各モード
• 値の範囲への対応：最小値と最大値を定義して検証する
• 精度の保持：書式設定されたテキストを表示しながら、完全な精度を保持する
• null 値への対応：AllowNull プロパティで null 許容の数値フィールドを設定する
• ウォーターマークテキスト：値が null のときにガイダンステキストを表示する
• カスタム単位：単位やラベルに接頭辞と接尾辞を設定する
• 末尾のゼロ：末尾のゼロを非表示にして、すっきりと表示するオプション
• 検証モード：KeyPress または LostFocus のタイミングで検証する
• 色のカスタマイズ：正数、負数、ゼロに異なる色を設定する
• 境界線のスタイル設定：フォーカス時とホバー時の状態を含む、カスタマイズ可能な境界線
• イベントシステム：OldValue と NewValue の追跡機能を備えた ValueChanged イベント
• カルチャへの対応：NumberFormatInfo によるカルチャ対応の書式設定
• デザイナーへの対応：ツールボックスを使用したデザイン時の完全なサポート

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

はじめに

📄 読む: references/getting-started.md

読むタイミング： 初回のセットアップ、インストール、基本的な実装

説明するトピック：

• アセンブリの配置と NuGet パッケージのインストール
• デザイナーまたはコードから SfNumericTextBox を追加する方法
• 名前空間のインポート
• 値の設定（Value プロパティ）
• 基本的な書式モード
• ウォーターマークテキストの基本
• 最小値／最大値の設定

---

書式モード

📄 読む: references/format-modes.md

読むタイミング： 異なるモードでの数値の書式設定、カルチャへの対応

説明するトピック：

• FormatMode プロパティ（Numeric、Currency、Percent）
• 小数点以下の桁数を制御する数値書式モード
• 通貨記号を使用した書式設定
• パーセント値に使用するパーセントモード
• カルチャ固有の書式設定
• NumberFormatInfo のカスタマイズ
• 小数点の区切り記号と桁区切り記号
• 各モードの実用例

---

書式設定オプション

📄 読む: references/formatting-options.md

読むタイミング： ゼロの非表示、単位の追加、ウォーターマークの表示

説明するトピック：

• 末尾のゼロの非表示（HideTrailingZeros プロパティ）
• カスタム単位用の接頭辞と接尾辞
• ウォーターマークテキストの実装
• WatermarkText プロパティと AllowNull
• ウォーターマークと書式モードの組み合わせ
• 表示例
• エッジケースとベストプラクティス

---

検証と値の範囲

📄 参照先： references/validation-and-ranges.md

参照するタイミング： 値の制約を適用するとき、検証の動作を設定するとき

説明するトピック：

• MinValue プロパティと MaxValue プロパティ
• ValidationMode プロパティ（KeyPress と LostFocus）
• ValueChangeMode プロパティ（値が更新されるタイミング）
• LostFocusValidation モード（Reset、MaxValue、MinValue）
• 検証のフローとイベントのタイミング
• エラーの状況と対処方法
• 実践的な検証の例

---

外観とスタイル設定

📄 参照先： references/appearance-and-styling.md

参照するタイミング： 色、境界線、視覚的な外観をカスタマイズするとき

説明するトピック：

• 正の値に対する PositiveForeColor
• 負の値に対する NegativeForeColor
• ゼロに対する ZeroForeColor
• プレースホルダーテキストに対する WatermarkForeColor
• BorderColor、FocusBorderColor、HoverBorderColor
• 無効状態に対する DisabledBorderColor
• BorderStyle プロパティ
• 背景とフォントのカスタマイズ
• 視覚状態の例

---

イベントと高度なパターン

📄 参照先： references/events-and-advanced.md

参照するタイミング： 値の変更を処理するとき、高度なシナリオに対応するとき

説明するトピック：

• ValueChanged イベントとサブスクリプション
• ValueChangedEventArgs（OldValue、NewValue）
• イベントのタイミングと検証の連携
• 値の変更への対応
• 高度なパターン（条件付き書式設定、連鎖的な更新）
• パフォーマンスに関する考慮事項
• 一般的なイベントパターン

---

クイックスタートの例

コードで作成する基本的な数値入力用 TextBox

using Syncfusion.WinForms.Input;

// Create SfNumericTextBox
var numericTextBox = new SfNumericTextBox();
numericTextBox.Size = new System.Drawing.Size(150, 20);
numericTextBox.Value = 123.45;
this.Controls.Add(numericTextBox);

書式設定と検証を使用する場合

// Set format mode to currency
numericTextBox.FormatMode = Syncfusion.WinForms.Input.Enums.FormatMode.Currency;

// Set value constraints
numericTextBox.MinValue = 0;
numericTextBox.MaxValue = 10000;

// Add watermark
numericTextBox.WatermarkText = "Enter amount";
numericTextBox.AllowNull = true;

// Subscribe to value changes
numericTextBox.ValueChanged += (sender, e) => 
{
    MessageBox.Show($"Value changed from {e.OldValue} to {e.NewValue}");
};

---

主なプロパティとメソッド

プロパティ	型	用途
Value	double?	数値を取得または設定します
FormatMode	FormatMode	書式を設定します（Numeric、Currency、Percent）
MinValue	double	許可される最小値
MaxValue	double	許可される最大値
AllowNull	bool	コントロールで null 値を許可します
WatermarkText	string	空のときに表示するプレースホルダーテキスト
HideTrailingZeros	bool	小数点以下の末尾のゼロを非表示にします
Prefix	string	値の前に付加するテキスト
Suffix	string	値の後に付加するテキスト
ValidationMode	ValidationMode	KeyPress または LostFocus
ValueChangeMode	ValueChangeMode	Value プロパティが更新されるタイミング
NumberFormatInfo	NumberFormatInfo	文化圏固有の数値書式設定

---

よく使われるパターン

パターン 1：範囲を指定した通貨入力

// Currency field with $0-$10,000 range
numericTextBox.FormatMode = FormatMode.Currency;
numericTextBox.MinValue = 0;
numericTextBox.MaxValue = 10000;
numericTextBox.WatermarkText = "Enter amount (0-10000)";

パターン 2：パーセンテージ表示

// Display and accept percentages
numericTextBox.FormatMode = FormatMode.Percent;
numericTextBox.MinValue = 0;
numericTextBox.MaxValue = 100;
numericTextBox.HideTrailingZeros = true;

パターン 3：単位付きの測定値

// Display with custom units
numericTextBox.Suffix = " inches";
numericTextBox.Value = 25.5;
numericTextBox.HideTrailingZeros = true;

パターン 4：色によるフィードバックを使用した検証

// Color based on value
numericTextBox.Style.PositiveForeColor = Color.Green;
numericTextBox.Style.NegativeForeColor = Color.Red;
numericTextBox.Style.ZeroForeColor = Color.Gray;

---

次のステップ

1. ここから開始： インストールと基本設定について、getting-started.md を読みます
2. 書式を選択： 数値、通貨、パーセントの各モードについて、format-modes.md を確認します
3. 書式設定を追加： 単位、ウォーターマーク、表示オプションについて、formatting-options.md を確認します
4. 検証を有効化： 制約について、validation-and-ranges.md を確認します
5. 外観をカスタマイズ： 色と境界線について、appearance-and-styling.md を使用します
6. イベントを処理： 動的な動作について、events-and-advanced.md を実装します