syncfusion-aspnetcore-numerictextbox

ASP.NET Core での NumericTextBox の実装

NumericTextBox は、通貨／パーセンテージの書式設定、範囲検証、スピナーコントロール、精度設定、グローバリゼーション対応などの高度な機能を備えた、数値の入力に特化したコンポーネントです。このスキルでは、Syncfusion の Tag Helper 構文を使用して、ASP.NET Core アプリケーションに NumericTextBox を実装する方法を説明します。

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

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

• 値を自動的に書式設定する数値入力フィールドを作成する
• 通貨やパーセンテージの入力コントロールを構築する
• 範囲検証（最小値／最大値の制約）を実装する
• 増減操作用のスピナーボタンを表示する
• 小数点以下の精度や数値の書式設定を制御する
• 国際的な数値形式や通貨に対応する
• ロケール固有の区切り記号を使用して数値を書式設定する
• 給与、価格、数量、パーセンテージの入力を実装する
• 視覚的なフィードバックを伴う数値範囲の検証を行う
• WCAG 2.2 レベル AA 規格に準拠した、アクセシブルな数値フォームを作成する

主な機能

機能	用途
数値の書式設定	通貨、パーセンテージ、またはカスタム形式（c2、p、n）で書式設定します
範囲検証	最小値／最大値の制約を設定し、自動検証を行います
精度の制御	小数点以下の桁数と丸め動作を制限します
スピナーボタン	上下のコントロールで値を増減します
ステップ値	スピナー操作の増分を定義します
通貨対応	複数の通貨（USD、EUR、GBP など）を表示、書式設定します
パーセンテージ入力	パーセンテージ値を変換して表示します
グローバリゼーション	150 以上の地域固有の数値形式に対応します
ローカライズ	スピナーボタンのツールチップをユーザーの言語に翻訳します
RTL 対応	アラビア語、ヘブライ語、ペルシャ語の右から左へのテキスト方向に対応します
データバインディング	ASP.NET Core モデルと双方向にバインドします
イベント処理	Created、Change、Blur、Focus イベントに応答します

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

はじめに

📄 参照: references/getting-started.md

• 前提条件とシステム要件
• Syncfusion.EJ2.AspNet.Core NuGet パッケージのインストール
• _ViewImports.cshtml への Tag Helper の追加
• CDN 経由でのスタイルシートとスクリプトリソースの追加
• スクリプトマネージャーの登録
• 最初の NumericTextBox の作成
• ASP.NET Core モデルへのバインド
• Tag Helper の構文と属性

数値形式

📄 参照: references/number-formats.md

• 標準数値形式指定子（c、p、n、e、f）
• 通貨記号とロケールを使用した通貨の書式設定
• パーセンテージの変換と表示
• カスタム数値形式のパターン
• ロケール固有の書式設定（en-US、de-DE、fr-FR）
• 出力例とエッジケース
• 書式文字列のベストプラクティス

範囲検証

📄 参照: references/range-validation.md

• 最小値と最大値の設定
• 小数点以下の精度設定
• ステップ値と増分の動作
• 範囲内に収まるよう値を自動的に制限
• 検証エラーの処理
• 実際の検証パターン（給与、年齢、割引）
• エッジケースと境界条件

外観とスタイル設定

📄 参照: references/appearance-styling.md

• NumericTextBox ラッパーの CSS カスタマイズ
• スピナーの上／下ボタンのスタイル設定
• 入力の高さ、フォントサイズ、色
• アイコンと前置／後置テンプレートの追加
• Syncfusion テーマとのテーマ統合
• レスポンシブデザインのパターン
• 検証状態用のカスタム CSS クラス

グローバリゼーションとローカライズ

📄 参照: references/globalization-localization.md

• 文化圏に基づく数値の書式設定（CLDR 対応）
• 特定の地域のロケール設定
• 複数通貨の書式設定
• スピナーボタンのツールチップのローカライズ
• RTL（右から左）言語への対応
• 日付と数値の形式のカルチャーバインディング
• タイムゾーンとロケールの検出

高度なパターン

📄 参照： references/advanced-patterns.md

• ASP.NET Core モデルを使用したデータバインディング
• C# と JavaScript による NumericTextBox のプログラム作成
• イベント処理のパターン（Created、Change、Blur、Focus）
• 複合的な検証シナリオ
• Forms およびモデル検証との統合
• オブザーバブルモデルとの双方向バインディング
• セキュリティ：XSS の防止と入力のサニタイズ

クイックスタートの例

通貨形式の基本的な NumericTextBox（Tag Helper）

<div class="form-group">
    <ejs-numerictextbox id="salary" 
        name="salary" 
        placeholder="Enter salary"
        format="c2"
        min="0"
        max="1000000"
        float-label-type="Auto">
    </ejs-numerictextbox>
</div>

_ViewImports.cshtml 内（一度だけ設定）

@addTagHelper *, Syncfusion.EJ2

_Layout.cshtml 内（一度だけ設定）

<head>
    <link rel="stylesheet" href="https://cdn.syncfusion.com/ej2/24.1.48/fluent.css" />
</head>
<body>
    @RenderBody()
    
    <script src="https://cdn.syncfusion.com/ej2/24.1.48/dist/ej2.min.js"></script>
    <ejs-scripts></ejs-scripts>
</body>

結果

ユーザーに表示される内容：

1. "$0.00" 形式の NumericTextBox
2. 値を増減するスピナーボタン（↑↓）
3. 「5000」を入力すると、「$5,000.00」と表示されます
4. 0～1000000 の範囲外の値は自動的に修正されます
5. フォーカスが外れると、数値が小数点以下 2 桁の通貨形式で表示されます

よくあるパターン

パターン 1：検証機能付き従業員給与フォーム

<form asp-action="SaveEmployee" asp-controller="Employee" method="post">
    <div class="form-group">
        <label asp-for="Salary"></label>
        <ejs-numerictextbox asp-for="Salary"
            format="c2"
            min="20000"
            max="500000"
            step="1000"
            float-label-type="Auto"
            css-class="e-outline">
        </ejs-numerictextbox>
        <small class="form-text text-muted">Salary range: $20,000 - $500,000</small>
    </div>

    <div class="form-group">
        <label asp-for="Bonus"></label>
        <ejs-numerictextbox asp-for="Bonus"
            format="c2"
            min="0"
            max="50000"
            step="100"
            float-label-type="Auto">
        </ejs-numerictextbox>
    </div>

    <button type="submit" class="btn btn-primary">Save Employee</button>
</form>

パターン 2：割引率を使った商品価格設定

<div class="row">
    <div class="col-md-6">
        <div class="form-group">
            <label asp-for="OriginalPrice"></label>
            <ejs-numerictextbox asp-for="OriginalPrice"
                placeholder="Original price"
                format="c2"
                min="0"
                step="0.01"
                float-label-type="Auto">
            </ejs-numerictextbox>
        </div>
    </div>

    <div class="col-md-6">
        <div class="form-group">
            <label asp-for="DiscountPercent"></label>
            <ejs-numerictextbox asp-for="DiscountPercent"
                placeholder="Discount %"
                format="p2"
                min="0"
                max="100"
                step="5"
                float-label-type="Auto"
                change="onDiscountChange">
            </ejs-numerictextbox>
        </div>
    </div>
</div>

<div class="form-group">
    <label>Final Price</label>
    <ejs-numerictextbox id="finalPrice"
        format="c2"
        read-only="true"
        float-label-type="Auto">
    </ejs-numerictextbox>
</div>

<script>
    function onDiscountChange(args) {
        var originalPrice = document.querySelector('input[id="originalPrice"]').value;
        var discountPercent = args.value;
        var finalPrice = originalPrice * (1 - discountPercent / 100);
        
        var finalPriceControl = document.querySelector('input[id="finalPrice"]');
        var finalPriceInstance = finalPriceControl.ej2_instances[0];
        finalPriceInstance.value = finalPrice;
    }
</script>

パターン 3：在庫数制約付き数量入力

<div class="form-group">
    <label asp-for="OrderQuantity"></label>
    <ejs-numerictextbox asp-for="OrderQuantity"
        placeholder="Order quantity"
        min="1"
        max="100"
        step="1"
        float-label-type="Auto"
        css-class="e-outline"
        change="checkInventory">
    </ejs-numerictextbox>
    <small>Available stock: 100 units</small>
</div>

<div class="form-group">
    <label>Unit Price: $25.00</label>
    <ejs-numerictextbox id="totalPrice"
        format="c2"
        read-only="true"
        float-label-type="Auto">
    </ejs-numerictextbox>
</div>

<script>
    document.querySelector('input[asp-for="OrderQuantity"]').addEventListener('change', function(e) {
        var quantity = parseInt(e.target.value) || 0;
        var unitPrice = 25;
        var totalPrice = quantity * unitPrice;
        
        var totalPriceControl = document.querySelector('input[id="totalPrice"]');
        var totalPriceInstance = totalPriceControl.ej2_instances[0];
        totalPriceInstance.value = totalPrice;
    });
</script>

パターン 4：カルチャを使用した国際通貨の選択

<div class="row">
    <div class="col-md-6">
        <div class="form-group">
            <label asp-for="Currency"></label>
            <select asp-for="Currency" id="currencySelect" class="form-control">
                <option value="en-US">USD ($)</option>
                <option value="de-DE">EUR (€)</option>
                <option value="fr-FR">GBP (£)</option>
            </select>
        </div>
    </div>

    <div class="col-md-6">
        <div class="form-group">
            <label asp-for="Amount"></label>
            <ejs-numerictextbox asp-for="Amount"
                placeholder="Enter amount"
                format="c2"
                float-label-type="Auto">
            </ejs-numerictextbox>
        </div>
    </div>
</div>

<script>
    document.getElementById('currencySelect').addEventListener('change', function(e) {
        var culture = e.target.value;
        var amountControl = document.querySelector('input[asp-for="Amount"]');
        var amountInstance = amountControl.ej2_instances[0];
        amountInstance.locale = culture;
    });
</script>

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

プロパティ	型	デフォルト	目的
min	decimal	-∞	許容される最小値
max	decimal	+∞	許容される最大値
step	decimal	1	スピナーで値を増減する刻み幅
value	decimal	null	初期数値
format	string	"n2"	数値形式（c、p、n、e、f）
decimals	int	2	小数点以下の桁数
placeholder	string	-	プレースホルダーテキスト
read-only	bool	false	スピナーを使用可能なまま、手動入力を防止します
disabled	bool	false	入力を完全に無効化します
show-spin-button	bool	true	上下のスピナーボタンを表示します
float-label-type	enum	Never	ラベルのアニメーション（Auto、Always、Never）
css-class	string	-	スタイル設定用の CSS クラス
created	string	-	NumericTextBox の作成時のイベントハンドラー
change	string	-	値変更時のイベントハンドラー
blur	string	-	フォーカスが外れたときのイベントハンドラー

よくあるユースケース

ユースケース 1：財務フォーム（給与計算、請求書発行）

通貨形式と検証機能を備えた給与計算または請求書発行フォームを作成します：

• 対象： 財務取引フォームを作成する場合
• リファレンス： range-validation.md + number-formats.md
• 主な機能： 通貨形式（c2）、最小値／最大値の検証、刻み幅の制御

ユースケース 2：国際 E コマース

ロケールに応じた形式の複数通貨対応ショッピングカートを構築します：

• 対象： 国際的な販売プラットフォームを作成する場合
• リファレンス： globalization-localization.md
• 主な機能： カルチャに基づく形式、複数通貨、ローカライズされたツールチップ

ユースケース 3：制約付きデータ入力フォーム

厳密な数値範囲と精度を備えたデータ入力フォームを作成します：

• 対象： 在庫管理、アンケート、分析用フォームを構築する場合
• リファレンス： range-validation.md
• 主な機能： 最小値／最大値の検証、小数精度、刻み幅

ユースケース 4：科学／工学計算

技術アプリケーション向けに、高精度な数値入力を実装します：

• 対象： 計算ツールや科学ソフトウェアを構築する場合
• リファレンス： advanced-patterns.md
• 主な機能： 高精度の小数、カスタム形式、イベント駆動型の計算

---

次のステップ：

1. getting-started.md を確認し、最初の NumericTextBox を設定します
2. ユースケースを選び、対応するリファレンスガイドに従います
3. コード例をコピーし、プロジェクトに合わせて調整します
4. 複雑なシナリオについては、advanced-patterns.md を参照してください