syncfusion-aspnetcore-numerictextbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing NumericTextBox in ASP.NET Core

在ASP.NET Core中实现NumericTextBox

The NumericTextBox is a specialized input component for capturing numeric values with advanced features like currency/percentage formatting, range validation, spinner controls, precision settings, and globalization support. This skill guides you through implementing NumericTextBox in ASP.NET Core applications using Syncfusion's Tag Helper syntax.

NumericTextBox是一款专门用于捕获数值的输入组件，具备货币/百分比格式化、范围验证、微调控件、精度设置和全球化支持等高级功能。本指南将引导你使用Syncfusion的Tag Helper语法在ASP.NET Core应用中实现NumericTextBox。

When to Use This Skill

适用场景

Use this skill when you need to:

Create numeric input fields with automatic value formatting
Build currency and percentage input controls
Implement range validation (min/max constraints)
Display spinner buttons for increment/decrement operations
Control decimal precision and number formatting
Support international number formats and currencies
Format numbers with locale-specific separators
Implement salary, price, quantity, or percentage inputs
Validate numeric ranges with visual feedback
Create accessible numeric forms following WCAG 2.2 Level AA standards

当你需要以下功能时，可以使用本指南：

创建具备自动值格式化的数值输入字段
构建货币和百分比输入控件
实现范围验证（最小/最大约束）
显示用于增减数值的微调按钮
控制小数精度和数值格式化
支持国际化数值格式和货币
使用区域特定的分隔符格式化数值
实现薪资、价格、数量或百分比输入
通过视觉反馈验证数值范围
创建符合WCAG 2.2 AA级标准的可访问数值表单

Key Features

核心功能

Feature	Use Case
Number Formatting	Format as currency, percentage, or custom formats (c2, p, n)
Range Validation	Set min/max constraints with automatic validation
Precision Control	Restrict decimal places and rounding behavior
Spinner Buttons	Increment/decrement values with up/down controls
Step Values	Define increment step size for spinner operations
Currency Support	Display and format multiple currencies (USD, EUR, GBP, etc.)
Percentage Input	Convert and display percentage values
Globalization	Support 150+ culture-specific number formats
Localization	Translate spinner button tooltips to user's language
RTL Support	Right-to-left text direction for Arabic, Hebrew, Persian
Data Binding	Two-way binding with ASP.NET Core models
Event Handling	Respond to Created, Change, Blur, and Focus events

功能	适用场景
数值格式化	格式化为货币、百分比或自定义格式（c2、p、n）
范围验证	设置最小/最大约束并自动验证
精度控制	限制小数位数和舍入行为
微调按钮	通过上下控件增减数值
步长设置	定义微调操作的增量步长
货币支持	显示和格式化多种货币（USD、EUR、GBP等）
百分比输入	转换并显示百分比数值
全球化	支持150+种区域特定的数值格式
本地化	将微调按钮提示翻译为用户语言
RTL支持	为阿拉伯语、希伯来语、波斯语提供从右到左的文本方向
数据绑定	与ASP.NET Core模型进行双向绑定
事件处理	响应Created、Change、Blur和Focus事件

Documentation Navigation Guide

文档导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Prerequisites and system requirements
Installing Syncfusion.EJ2.AspNet.Core NuGet package
Adding Tag Helpers to _ViewImports.cshtml
Adding stylesheets and script resources via CDN
Registering the script manager
Creating your first NumericTextBox
Binding to ASP.NET Core models
Tag Helper syntax and attributes

📄 阅读： references/getting-started.md

前提条件和系统要求
安装Syncfusion.EJ2.AspNet.Core NuGet包
向_ViewImports.cshtml添加Tag Helpers
通过CDN添加样式表和脚本资源
注册脚本管理器
创建你的第一个NumericTextBox
绑定到ASP.NET Core模型
Tag Helper语法和属性

Number Formats

数值格式

📄 Read: references/number-formats.md

Standard numeric format specifiers (c, p, n, e, f)
Currency formatting with symbol and locale
Percentage conversion and display
Custom number format patterns
Locale-specific formatting (en-US, de-DE, fr-FR)
Output examples and edge cases
Format string best practices

📄 阅读： references/number-formats.md

标准数值格式说明符（c、p、n、e、f）
带符号和区域的货币格式化
百分比转换和显示
自定义数值格式模式
区域特定格式化（en-US、de-DE、fr-FR）
输出示例和边缘情况
格式字符串最佳实践

Range Validation

范围验证

📄 Read: references/range-validation.md

Setting minimum and maximum values
Decimal precision configuration
Step values and increment behavior
Automatic value clamping within range
Validation error handling
Real-world validation patterns (salary, age, discount)
Edge cases and boundary conditions

📄 阅读： references/range-validation.md

设置最小值和最大值
小数精度配置
步长值和增量行为
自动将值限制在范围内
验证错误处理
实际验证模式（薪资、年龄、折扣）
边缘情况和边界条件

Appearance and Styling

外观与样式

📄 Read: references/appearance-styling.md

CSS customization of NumericTextBox wrapper
Styling spinner up/down buttons
Input height, font size, and color
Adding icons and prepend/append templates
Theme integration with Syncfusion themes
Responsive design patterns
Custom CSS classes for validation states

📄 阅读： references/appearance-styling.md

NumericTextBox容器的CSS自定义
微调上下按钮的样式设置
输入框高度、字体大小和颜色
添加图标和前置/后置模板
与Syncfusion主题集成
响应式设计模式
验证状态的自定义CSS类

Globalization and Localization

全球化与本地化

📄 Read: references/globalization-localization.md

Culture-based number formatting (CLDR support)
Setting locale for specific regions
Multi-currency formatting
Spinner button tooltip localization
RTL (right-to-left) language support
Date and number format culture binding
Timezone and locale detection

📄 阅读： references/globalization-localization.md

基于区域的数值格式化（支持CLDR）
为特定区域设置语言环境
多货币格式化
微调按钮提示本地化
RTL（从右到左）语言支持
日期和数值格式的区域绑定
时区和区域检测

Advanced Patterns

高级模式

📄 Read: references/advanced-patterns.md

Data binding with ASP.NET Core models
Programmatic NumericTextBox creation with C# and JavaScript
Event handling patterns (Created, Change, Blur, Focus)
Composite validation scenarios
Integration with Forms and Model Validation
Two-way binding with observable models
Security: XSS prevention and input sanitization

📄 阅读： references/advanced-patterns.md

与ASP.NET Core模型的数据绑定
使用C#和JavaScript以编程方式创建NumericTextBox
事件处理模式（Created、Change、Blur、Focus）
复合验证场景
与表单和模型验证集成
与可观察模型的双向绑定
安全性：XSS防护和输入清理

Quick Start Example

快速入门示例

Basic NumericTextBox with Currency Format (Tag Helper)

带货币格式的基础NumericTextBox（Tag Helper）

html

<!-- Views/Home/Index.cshtml -->
<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>

html

<!-- Views/Home/Index.cshtml -->
<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>

In _ViewImports.cshtml (one-time setup)

在_ViewImports.cshtml中（一次性设置）

html

@addTagHelper *, Syncfusion.EJ2

html

@addTagHelper *, Syncfusion.EJ2

In _Layout.cshtml (one-time setup)

在_Layout.cshtml中（一次性设置）

html

<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>

html

<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>

Result

效果

User sees:

NumericTextBox with "$0.00" format
Spinner buttons (↑↓) to increment/decrement values
On entry of "5000", displays as "$5,000.00"
Values outside 0-1000000 range are auto-corrected
When blurred, number formatted to currency with 2 decimal places

用户将看到：

带有"$0.00"格式的NumericTextBox
用于增减数值的微调按钮（↑↓）
输入"5000"时，显示为"$5,000.00"
超出0-1000000范围的值会自动修正
失去焦点时，数值格式化为保留2位小数的货币形式

Common Patterns

常见模式

Pattern 1: Employee Salary Form with Validation

模式1：带验证的员工薪资表单

html

<!-- Views/Employee/Create.cshtml -->
<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>

html

<!-- Views/Employee/Create.cshtml -->
<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>

Pattern 2: Product Pricing with Percentage Discount

模式2：带百分比折扣的产品定价

html

<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>

html

<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>

Pattern 3: Quantity Input with Stock Constraint

模式3：带库存约束的数量输入

html

<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>

html

<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>

Pattern 4: International Currency Selection with Culture

模式4：带区域的国际货币选择

html

<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>

html

<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>

Key Properties Reference

核心属性参考

Property	Type	Default	Purpose
`min`	decimal	-∞	Minimum acceptable value
`max`	decimal	+∞	Maximum acceptable value
`step`	decimal	1	Increment/decrement step for spinner
`value`	decimal	null	Initial numeric value
`format`	string	"n2"	Number format (c, p, n, e, f)
`decimals`	int	2	Number of decimal places
`placeholder`	string	-	Placeholder text
`read-only`	bool	false	Prevent manual input while allowing spinner
`disabled`	bool	false	Completely disable input
`show-spin-button`	bool	true	Display up/down spinner buttons
`float-label-type`	enum	Never	Label animation (Auto, Always, Never)
`css-class`	string	-	CSS classes for styling
`created`	string	-	Event handler for NumericTextBox created
`change`	string	-	Event handler for value change
`blur`	string	-	Event handler for blur event

属性	类型	默认值	用途
`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	-	失去焦点事件的处理程序

Common Use Cases

常见使用场景

Use Case 1: Financial Forms (Payroll, Invoicing)

场景1：财务表单（薪资、发票）

Create payroll or invoicing forms with currency formatting and validation:

When: Building financial transaction forms
Reference: range-validation.md + number-formats.md
Key Features: Currency format (c2), min/max validation, step control

创建带货币格式化和验证的薪资或发票表单：

适用时机： 构建财务交易表单时
参考文档： range-validation.md + number-formats.md
核心功能： 货币格式（c2）、最小/最大验证、步长控制

Use Case 2: International E-Commerce

场景2：国际电商

Build multi-currency shopping carts with locale-aware formatting:

When: Creating international sales platforms
Reference: globalization-localization.md
Key Features: Culture-based formatting, multiple currencies, localized tooltips

构建支持区域感知格式化的多货币购物车：

适用时机： 创建国际销售平台时
参考文档： globalization-localization.md
核心功能： 基于区域的格式化、多货币支持、本地化提示

Use Case 3: Data Entry Forms with Constraints

场景3：带约束的数据输入表单

Create data entry forms with strict numeric ranges and precision:

When: Building inventory, survey, or analytics forms
Reference: range-validation.md
Key Features: Min/max validation, decimal precision, step values

创建具备严格数值范围和精度的数据输入表单：

适用时机： 构建库存、调查或分析表单时
参考文档： range-validation.md
核心功能： 最小/最大验证、小数精度、步长值

Use Case 4: Scientific/Engineering Calculations

场景4：科学/工程计算

Implement precision numeric inputs for technical applications:

When: Building calculation tools, scientific software
Reference: advanced-patterns.md
Key Features: High precision decimals, custom formats, event-driven calculations

Next Steps:

Review getting-started.md to set up your first NumericTextBox
Choose your use case and follow the corresponding reference guide
Copy code examples and adapt to your project
Refer to advanced-patterns.md for complex scenarios

为技术应用实现高精度数值输入：

适用时机： 构建计算工具、科学软件时
参考文档： advanced-patterns.md
核心功能： 高精度小数、自定义格式、事件驱动计算

下一步：

查看getting-started.md来创建你的第一个NumericTextBox
选择你的使用场景并遵循对应的参考指南
复制代码示例并适配你的项目
复杂场景请参考advanced-patterns.md