syncfusion-aspnetcore-numerictextbox

在 ASP.NET Core 中实现 NumericTextBox

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

何时使用此技能

在需要以下功能时使用此技能：

• 创建可自动格式化值的数值输入字段
• 构建货币和百分比输入控件
• 实现范围验证（最小值／最大值约束）
• 显示用于递增／递减操作的微调按钮
• 控制小数精度和数字格式
• 支持国际数字格式和货币
• 使用特定区域设置的分隔符格式化数字
• 实现薪资、价格、数量或百分比输入
• 验证数值范围并提供视觉反馈
• 创建符合 WCAG 2.2 Level 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 包
• 将 Tag Helper 添加到 _ViewImports.cshtml
• 通过 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）
• 复合验证场景
• 与表单和模型验证集成
• 与可观察模型进行双向绑定
• 安全性：防止 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：国际电子商务

构建支持多种货币并采用区域格式的购物车：

• 适用场景： 创建国际销售平台
• 参考： globalization-localization.md
• 主要功能： 基于区域性的格式、多种货币、本地化工具提示

用例 3：带约束的数据录入表单

创建具有严格数值范围和精度要求的数据录入表单：

• 适用场景： 构建库存、调查或分析表单
• 参考： range-validation.md
• 主要功能： 最小值/最大值验证、小数精度、步长值

用例 4：科学/工程计算

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

• 适用场景： 构建计算工具、科学软件
• 参考： advanced-patterns.md
• 主要功能： 高精度小数、自定义格式、事件驱动计算

---

后续步骤：

1. 查看 getting-started.md，设置你的第一个 NumericTextBox
2. 选择用例并按照相应的参考指南操作
3. 复制代码示例并根据项目进行调整
4. 复杂场景请参阅 advanced-patterns.md