syncfusion-wpf-percent-textbox

Syncfusion WPF PercentTextBox の実装

このスキルを使用する場面

ユーザーが以下を必要としている場合に、このスキルを使用します。

• パーセンテージ入力コントロールを実装する：WPF アプリケーションで、値の制限と書式設定に対応したコントロールを実装します
• 値の検証を設定する：最小値／最大値の制限と、検証のタイミング（OnKeyPress と OnLostFocus）を設定します
• 数値の書式設定を適用する：カルチャ固有の区切り文字、小数桁数、グループサイズを設定します
• 外観をカスタマイズする：正の値、負の値、ゼロの値に異なる前景色を設定します
• インタラクティブな機能を有効にする：スクロール間隔、マウスホイールのサポート、クリックとドラッグによる値の変更などを有効にします
• 視覚的な進捗を表示する：範囲アドナーを使用して、最小値／最大値の範囲に対する値を表示します
• パーセンテージデータをバインドする：プロパティ変更通知を備えた ViewModel からデータをバインドします
• null 値を処理する：カスタムの null 表示や透かしテキストを設定します
• 国際的な書式を実装する：カルチャベースの小数点／グループ区切り文字とパーセント記号を設定します

PercentTextBox コントロールは入力を double 値に制限し、データバインディング、検証、書式設定、外観に関する幅広いカスタマイズオプションを備えたパーセンテージとして表示します。

コンポーネントの概要

Syncfusion WPF PercentTextBox は、次の機能を備えた特殊な入力コントロールです。

• 入力を double 値のみ に制限します（テキストは入力できません）
• カスタマイズ可能な記号とパターンで、値を パーセンテージ として表示します
• 検証のタイミングを設定できる 最小値／最大値の検証 に対応します
• MVVM パターン向けの データバインディング をサポートします
• グループ区切り文字と小数桁数を含む カルチャ固有の書式設定 を提供します
• 正の値、負の値、ゼロの値に 異なる前景色 を設定できます
• キーボードの矢印キー、マウスホイール、クリックとドラッグによる インタラクティブな値の変更 に対応します
• 視覚的な進捗表示に使用できる 範囲アドナー を備えています
• 透かしテキストのサポートにより null 値 を処理します
• 組み込みのビジュアルスタイル とテーマを提供します

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

はじめに

📄 参照先： references/getting-started.md

次の作業を行う場合は、このリファレンスを参照してください。

• PercentTextBox を WPF プロジェクトに追加する（デザイナー、XAML、または C# を使用）
• アセンブリの配置と NuGet パッケージ（Syncfusion.Shared.WPF）を設定する
• PercentValue プロパティの基本的な使い方を理解する
• コントロールの初期サイズと配置を設定する
• 基本的なコントロール宣言のパターンを確認する

値の管理とバインディング

📄 参照先： references/value-management.md

次の作業を行う場合は、このリファレンスを参照してください。

• PercentValue プロパティを使用してパーセンテージ値を設定、変更する
• ViewModel とのデータバインディング（単方向または双方向）を実装する
• PercentValueChanged イベントを処理して値の変更を追跡する
• NullValue プロパティと UseNullOption プロパティを使用して null 値の動作を設定する
• コントロールが空または null のときに透かしテキストを表示する
• 前景色またはテンプレートを使用して透かしの外観をカスタマイズする
• PasteMode プロパティ（Default と Advanced）を使用して貼り付けの動作を制御する
• 増分／減分操作用のスピンボタンを追加する

検証と制限

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

次の作業を行う場合は、このリファレンスを参照してください。

• 最小値と最大値（MinValue、MaxValue）の範囲内に値を制限する
• 検証のタイミング（MinValidation、MaxValidation：OnKeyPress と OnLostFocus）を設定する
• 制限値を超えた場合の動作（MaxValueOnExceedMaxDigit、MinValueOnExceedMinDigit）を制御する
• MinPercentDecimalDigits と MaxPercentDecimalDigits を使用して小数桁数を制限する
• 小数桁数の設定におけるプロパティの優先順位を理解する
• テキストの選択とキャレットの表示を許可したまま、読み取り専用モードを有効にする
• キー入力時に無効な入力を防ぐ、またはフォーカスが失われたときに検証する

数値の書式設定とカルチャ

📄 参照： references/number-formatting.md

以下が必要な場合は、このリファレンスを使用してください。

• Culture プロパティを使用して、カルチャ固有の書式を適用する
• カスタムの数値パターン用に NumberFormatInfo を構成する
• グループ区切り記号（PercentGroupSeparator）とグループサイズ（PercentGroupSizes）を設定する
• 小数点区切り記号と桁数をカスタマイズする
• パーセント記号（PercentageSymbol）を変更する
• GroupSeperatorEnabled でグループ区切り記号の表示を有効にする
• 正の値のパターンを定義する（PercentPositivePattern：4 つのオプション）
• 負の値のパターンを定義する（PercentNegativePattern：12 個のオプション）
• プロパティの優先順位（専用プロパティ、NumberFormat、Culture）を理解する

外観のカスタマイズ

📄 参照： references/appearance-customization.md

以下が必要な場合は、このリファレンスを使用してください。

• 正の値に異なる前景色を設定する（PositiveForeground）
• ApplyNegativeForeground と NegativeForeground で負の値の前景色を適用する
• ゼロの値をカスタムカラーで表示する（ApplyZeroColor、ZeroColor）
• コントロールの背景ブラシをカスタマイズする
• 角丸の枠線に角の半径を適用する
• 選択されたテキストのブラシと不透明度を構成する
• TextAlignment を使用してテキストを配置する（Left、Center、Right）
• カスタム情報を含むツールチップを追加する

インタラクティブ機能

📄 参照： references/interactive-features.md

ベストプラクティス

📄 参照： references/best-practices.md

以下が必要な場合は、このリファレンスを使用してください。

• 値の増減に使うスクロール間隔を構成する
• 上下矢印キーによるキーボード操作を有効にする
• IsScrollingOnCircle でマウスホイールによるスクロールを許可する
• EnableExtendedScrolling でクリックとドラッグによる値の変更を有効にする
• フォーカス時のテキスト選択動作を制御する（TextSelectionOnFocus）
• 手動で値を増減するためのスピンボタンを表示する
• 視覚的な進捗表示のためにレンジアドーナーを有効にする（EnableRangeAdorner）
• レンジアドーナーの背景色をカスタマイズする
• レンジアドーナーの表示に必要な最小値と最大値を理解する

クイックスタートの例

XAML での基本的な PercentTextBox

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
    x:Class="PercentTextBoxSample.MainWindow">
    <Grid>
        <syncfusion:PercentTextBox x:Name="percentTextBox" 
                                   Width="150" 
                                   Height="30"
                                   PercentValue="75.5"
                                   MinValue="0"
                                   MaxValue="100"/>
    </Grid>
</Window>

C# での基本的な PercentTextBox

using Syncfusion.Windows.Shared;

// Create instance
PercentTextBox percentTextBox = new PercentTextBox();
percentTextBox.Width = 150;
percentTextBox.Height = 30;

// Set value and limits
percentTextBox.PercentValue = 75.5;
percentTextBox.MinValue = 0;
percentTextBox.MaxValue = 100;

// Add to container
this.Content = percentTextBox;

データバインディングの例

<syncfusion:PercentTextBox PercentValue="{Binding DiscountPercentage, UpdateSourceTrigger=PropertyChanged}"
                           Width="150" Height="30"
                           MinValue="0" MaxValue="100"/>

// ViewModel.cs
public class ViewModel : INotifyPropertyChanged
{
    private double discountPercentage;
    public double DiscountPercentage
    {
        get { return discountPercentage; }
        set
        {
            discountPercentage = value;
            OnPropertyChanged(nameof(DiscountPercentage));
        }
    }

    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

よくあるパターン

パターン 1：入力時に検証するパーセンテージ入力

キー入力時にすぐ検証するパーセンテージ入力が必要な場合：

<syncfusion:PercentTextBox PercentValue="50"
                           MinValue="0"
                           MaxValue="100"
                           MinValidation="OnKeyPress"
                           MaxValidation="OnKeyPress"
                           MaxValueOnExceedMaxDigit="True"
                           MinValueOnExceedMinDigit="True"/>

この方法が有効な理由： OnKeyPress による検証で無効な入力をすぐに防ぎ、境界を超えた場合は超過時のプロパティによって値が上限または下限にリセットされます。

パターン 2：カルチャに応じて書式設定するパーセンテージ

カルチャ固有のパーセンテージ書式が必要な場合：

<syncfusion:PercentTextBox PercentValue="1234.567"
                           Culture="de-DE"
                           GroupSeperatorEnabled="True"
                           PercentDecimalDigits="2"/>

この方法が有効な理由： ドイツ語のカルチャでは「.」がグループ区切り記号、「,」が小数点区切り記号として使われ、表示が自動的に書式設定されます。

パターン 3：値を色分けするパーセンテージ

正、負、ゼロの値を視覚的に区別する必要がある場合：

<syncfusion:PercentTextBox PercentValue="-15"
                           PositiveForeground="Green"
                           NegativeForeground="Red"
                           ApplyNegativeForeground="True"
                           ZeroColor="Gray"
                           ApplyZeroColor="True"/>

この方法が有効な理由： 色を使い分けることで、数値を読まなくても値の状態をすばやく識別できます。

パターン 4：スクロールで操作するパーセンテージ

キーボードやマウスで値をすばやく調整する必要がある場合：

<syncfusion:PercentTextBox PercentValue="25"
                           ScrollInterval="5"
                           IsScrollingOnCircle="True"
                           EnableExtendedScrolling="True"
                           ShowSpinButton="True"/>

この方法が有効な理由： 複数の操作方法（矢印キー、マウスホイール、スピンボタン、クリックとドラッグ）により、ユーザーの好みに合わせて柔軟に操作できます。

パターン 5：視覚的なフィードバックのためのレンジアドーナー

視覚的に進捗を表示する必要がある場合：

<syncfusion:PercentTextBox PercentValue="65"
                           MinValue="0"
                           MaxValue="100"
                           EnableRangeAdorner="True"
                           RangeAdornerBackground="LightBlue"/>

この方法が有効な理由： レンジアドーナーはコントロールの背景を値に比例して塗りつぶすため、プログレスバーのように進捗をひと目で確認できます。

パターン 6：透かしテキストを使った Null 値の表示

空の状態でプレースホルダーテキストを表示する必要がある場合：

<syncfusion:PercentTextBox UseNullOption="True"
                           NullValue="{x:Null}"
                           WatermarkText="Enter discount %"
                           WatermarkTextIsVisible="True"
                           WatermarkTextForeground="Gray"/>

この方法が有効な理由： コントロールが空のときに透かしテキストでユーザーを案内でき、UX が向上します。

主要プロパティのリファレンス

値のプロパティ

• PercentValue - パーセンテージ値を取得または設定します（double）
• MinValue - 許可される最小値
• MaxValue - 許可される最大値
• NullValue - UseNullOption が true で値が null の場合に表示する値
• UseNullOption - null 値の処理を有効にします

検証プロパティ

• MinValidation - 最小値の検証タイミング（OnKeyPress、OnLostFocus）
• MaxValidation - 最大値の検証タイミング（OnKeyPress、OnLostFocus）
• MinValueOnExceedMinDigit - 超過時に MinValue にリセットします（bool）
• MaxValueOnExceedMaxDigit - 超過時に MaxValue にリセットします（bool）

書式設定プロパティ

• Culture - 数値の書式設定に使用するカルチャ（CultureInfo）
• NumberFormat - カスタムの NumberFormatInfo オブジェクト
• PercentGroupSeparator - 桁区切りに使用する文字（例: ","）
• PercentGroupSizes - 桁区切りのサイズの配列（例: {3, 2}）
• PercentDecimalSeparator - 小数点に使用する文字（例: "."）
• PercentDecimalDigits - 小数点以下の桁数
• MinPercentDecimalDigits - 小数点以下の最小桁数
• MaxPercentDecimalDigits - 小数点以下の最大桁数
• PercentageSymbol - パーセント記号（既定値: "%"）
• GroupSeperatorEnabled - 桁区切りの表示／非表示（bool）
• PercentPositivePattern - 正の値の書式（0～3）
• PercentNegativePattern - 負の値の書式（0～11）

外観プロパティ

• PositiveForeground - 正の値に使用する前景ブラシ
• NegativeForeground - 負の値に使用する前景ブラシ
• ApplyNegativeForeground - 負の値の前景色を有効にします（bool）
• ZeroColor - ゼロ値に使用する前景ブラシ
• ApplyZeroColor - ゼロ値の色を有効にします（bool）
• Background - コントロールの背景ブラシ
• CornerRadius - 枠線の角の半径
• SelectionBrush - 選択したテキストの背景
• SelectionOpacity - 選択したテキストの不透明度（0～1）
• TextAlignment - テキストの配置（Left、Center、Right）

インタラクティブプロパティ

• ScrollInterval - 増減する刻み値
• IsScrollingOnCircle - マウスホイールによるスクロールを有効にします（bool）
• EnableExtendedScrolling - クリックしてドラッグするスクロールを有効にします（bool）
• ShowSpinButton - 上下ボタンを表示します（bool）
• TextSelectionOnFocus - フォーカス時にテキストを自動選択します（bool）
• EnableRangeAdorner - 範囲アドーナーを表示します（bool）
• RangeAdornerBackground - 範囲アドーナーの塗りつぶしブラシ

ウォーターマークのプロパティ

• WatermarkText - プレースホルダーのテキスト文字列
• WatermarkTextIsVisible - ウォーターマークを表示します（bool）
• WatermarkTextForeground - ウォーターマークのテキスト色
• WatermarkTemplate - ウォーターマーク用のカスタム DataTemplate

その他のプロパティ

• IsReadOnly - ユーザーによる編集を禁止します（bool）
• IsReadOnlyCaretVisible - 読み取り専用モードでキャレットを表示します（bool）
• PasteMode - 貼り付けの動作（Default、Advanced）
• ToolTip - ツールチップのテキストまたはオブジェクト

一般的な使用例

1. 割引／税計算

PercentTextBox を使用して、0～100%の範囲、少数点以下2桁、即時検証に対応した割引率または税率の入力欄を作成します。

2. 進捗／完了状況の追跡

範囲アドーナーによる視覚的なフィードバックを使ってプロジェクトの完了率を表示し、値を0～100%に制限します。

3. 財務計算

カルチャに応じた書式設定と複数の小数桁を使用して、金利、ROI のパーセンテージ、または成長率を扱います。

4. アンケート／評価システム

色分けされた前景色（高い値には緑、低い値には赤）を使用して、パーセンテージ形式の評価を収集します。

5. リソース配分

検証により合計が100%を超えないようにしながら、パーセンテージ形式の配分（例: 予算の配分）を入力します。

6. 構成設定

スクロール間隔を設定してすばやく調整できるようにし、パフォーマンスのしきい値、キャッシュサイズ、またはバッファーの割合を設定します。

7. データ分析フォーム

大きな数値には桁区切りを使用し、カルチャに応じた書式設定で統計上のパーセンテージを収集します。

8. ダッシュボードコントロール

ライブデータにバインドし、目標に対する進捗を示す範囲アドーナー付きで KPI の割合を表示します。

---

次のステップ：

1. 実装のニーズに応じた適切なリファレンスファイルを読みます
2. クイックスタートの例を土台として使用します
3. ユースケースに合った一般的なパターンを適用します
4. 動作や外観を微調整するには、主要なプロパティを参照します