syncfusion-react-numerictextbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing NumericTextBox

实现 NumericTextBox

Component Overview

组件概览

The NumericTextBox is a Syncfusion React input component designed specifically for numeric data entry. It provides:

Formatted input - Automatic number formatting (currency, percentage, scientific notation)
Validation - Built-in min/max range validation with strict mode
Spin buttons - Visual increment/decrement controls with customizable steps
Decimal control - Manage decimal places and precision during input
Accessibility - Full WCAG 2.2 compliance with ARIA attributes and keyboard navigation
Internationalization - Locale support, RTL (Right-to-Left) languages
Form ready - Integrates seamlessly with React forms and state management

NumericTextBox 是 Syncfusion 推出的 React 输入组件，专门用于数值数据输入场景，它提供以下能力：

格式化输入 - 自动数字格式化（货币、百分比、科学计数法）
验证能力 - 内置最小/最大范围验证，支持严格模式
增减按钮 - 可视化的增减控件，支持自定义步长
小数控制 - 输入过程中管理小数位数和精度
无障碍支持 - 完全符合 WCAG 2.2 标准，支持 ARIA 属性和键盘导航
国际化 - 支持多地区适配、RTL（从右到左）语言支持
表单适配 - 可与 React 表单和状态管理无缝集成

Documentation & Navigation Guide

文档与导航指南

When the user needs help with NumericTextBox, guide them to the appropriate reference:

当用户需要 NumericTextBox 相关帮助时，引导他们查看对应参考文档：

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup
CSS imports and themes
React component import and basic JSX
Creating your first NumericTextBox
Running the application

📄 阅读： references/getting-started.md

安装与包配置
CSS 导入与主题设置
React 组件导入与基础 JSX 编写
创建你的第一个 NumericTextBox
运行应用

Formats & Validation

格式化与验证

📄 Read: references/formats-and-validation.md

Standard format specifiers (currency, percentage, number, scientific)
Custom number formats with # and 0 patterns
Range validation with min and max properties
strictMode for enforcing valid ranges
Real-world formatting examples

📄 阅读： references/formats-and-validation.md

标准格式说明符（货币、百分比、数字、科学计数法）
基于 # 和 0 模式的自定义数字格式
基于 min 和 max 属性的范围验证
用于强制有效范围的 strictMode 配置
实际场景格式化示例

Spin Buttons & Step Control

增减按钮与步长控制

📄 Read: references/spin-buttons-and-step.md

Enabling/disabling spin button arrows
Step property for increment values
Customizing spin button appearance and behavior
Precision with step increments
Keyboard shortcuts (Arrow Up/Down)

📄 阅读： references/spin-buttons-and-step.md

启用/禁用增减按钮箭头
控制增减数值的 step 属性
自定义增减按钮的外观和行为
步长增减的精度控制
键盘快捷键（上下箭头）

Adornments & Styling

装饰与样式

📄 Read: references/adornments-and-styling.md

Prefix and suffix text (units, currency symbols)
CSS classes and custom styling
Placeholder, disabled, and readonly states
Focus and blur event handling
Theme customization and appearance options

📄 阅读： references/adornments-and-styling.md

前缀与后缀文本（单位、货币符号）
CSS 类与自定义样式
占位符、禁用、只读状态
聚焦与失焦事件处理
主题自定义与外观配置

Precision & Decimals

精度与小数

📄 Read: references/precision-decimals.md

decimals property for controlling decimal places
validateDecimalOnType for real-time precision validation
Maintaining trailing zeros in display
Rounding behavior and edge cases
Precision during input vs display

📄 阅读： references/precision-decimals.md

控制小数位数的 decimals 属性
实时精度验证的 validateDecimalOnType 配置
展示时保留末尾零
舍入行为与边界场景
输入精度与展示精度的差异

Two-Way Binding & Forms

双向绑定与表单

📄 Read: references/two-way-binding-forms.md

Two-way value binding in React (value prop + onChange)
Controlled component patterns
React state management
React Hook Form integration
Form validation with NumericTextBox

📄 阅读： references/two-way-binding-forms.md

React 中的双向值绑定（value 属性 + onChange 事件）
受控组件模式
React 状态管理
React Hook Form 集成
基于 NumericTextBox 的表单验证

Globalization & Accessibility

全球化与无障碍

📄 Read: references/globalization-accessibility.md

Internationalization and locale support
Right-to-Left (RTL) language support
WCAG 2.2 accessibility compliance
Keyboard navigation and shortcuts
Screen reader support with ARIA attributes
Focus management and color contrast

📄 阅读： references/globalization-accessibility.md

国际化与多地区支持
RTL（从右到左）语言支持
WCAG 2.2 无障碍合规
键盘导航与快捷键
基于 ARIA 属性的屏幕阅读器支持
焦点管理与颜色对比度

How-To Guide

实操指南

📄 Read: references/how-to-guide.md

Custom validation patterns
Preventing nullable input
Maintaining trailing zeros
Customizing spin button icons
Common troubleshooting and edge cases

📄 阅读： references/how-to-guide.md

自定义验证模式
禁止空值输入
保留末尾零
自定义增减按钮图标
常见问题排查与边界场景处理

API Reference

API 参考

📄 Read: references/api.md

Complete properties reference (value, min, max, step, format, decimals, etc.)
Methods reference (increment, decrement, getText, focusIn, focusOut, destroy, etc.)
Events reference with full argument types (change, blur, focus, created, destroyed)

📄 阅读： references/api.md

完整属性参考（value、min、max、step、format、decimals 等）
方法参考（increment、decrement、getText、focusIn、focusOut、destroy 等）
事件参考与完整参数类型（change、blur、focus、created、destroyed）

Quick Start Example

快速开始示例

Here's a minimal working example to get started:

jsx

import React, { useState } from 'react';
import { NumericTextBoxComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-buttons/styles/material3.css';
import '@syncfusion/ej2-inputs/styles/material3.css';

export default function App() {
  const [value, setValue] = useState(10);

  return (
    <div style={{ padding: '20px' }}>
      <h3>Enter a Number</h3>
      <NumericTextBoxComponent
        value={value}
        onChange={(e) => setValue(e.value)}
        min={0}
        max={100}
        step={1}
      />
      <p>Current Value: {value}</p>
    </div>
  );
}

Key points:

Import

NumericTextBoxComponent

from

@syncfusion/ej2-react-inputs

Import required CSS themes (material3 in this example)
Use
```
value
```
prop for the current numeric value
Use
```
onChange
```
event to update React state
Add
```
min
```
,
```
max
```
,
```
step
```
for validation and controls

以下是最小可用示例：

jsx

import React, { useState } from 'react';
import { NumericTextBoxComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-buttons/styles/material3.css';
import '@syncfusion/ej2-inputs/styles/material3.css';

export default function App() {
  const [value, setValue] = useState(10);

  return (
    <div style={{ padding: '20px' }}>
      <h3>Enter a Number</h3>
      <NumericTextBoxComponent
        value={value}
        onChange={(e) => setValue(e.value)}
        min={0}
        max={100}
        step={1}
      />
      <p>Current Value: {value}</p>
    </div>
  );
}

核心要点：

从

@syncfusion/ej2-react-inputs

导入

NumericTextBoxComponent

导入所需的 CSS 主题（本示例使用 material3）
使用
```
value
```
属性绑定当前数值
使用
```
onChange
```
事件更新 React 状态
添加
```
min
```
、
```
max
```
、
```
step
```
用于验证和控件配置

Common Patterns

常见使用模式

1. Currency Input

1. 货币输入

jsx

<NumericTextBoxComponent
  value={99.99}
  format="c2"
  min={0}
  placeholder="Enter amount"
/>

jsx

<NumericTextBoxComponent
  value={99.99}
  format="c2"
  min={0}
  placeholder="Enter amount"
/>

2. Percentage Input

2. 百分比输入

jsx

<NumericTextBoxComponent
  value={50}
  format="p"
  min={0}
  max={100}
/>

jsx

<NumericTextBoxComponent
  value={50}
  format="p"
  min={0}
  max={100}
/>

3. Integer-Only Input

3. 仅整数输入

jsx

<NumericTextBoxComponent
  value={10}
  decimals={0}
  step={1}
  min={0}
/>

jsx

<NumericTextBoxComponent
  value={10}
  decimals={0}
  step={1}
  min={0}
/>

4. Bounded Range with Validation

4. 带验证的范围限制

jsx

<NumericTextBoxComponent
  value={25}
  min={0}
  max={100}
  strictMode={true}
  placeholder="0-100"
/>

jsx

<NumericTextBoxComponent
  value={25}
  min={0}
  max={100}
  strictMode={true}
  placeholder="0-100"
/>

5. Form Field with Label

5. 带标签的表单字段

jsx

<div>
  <label>Product Quantity:</label>
  <NumericTextBoxComponent
    value={qty}
    onChange={(e) => setQty(e.value)}
    min={1}
    step={1}
    prefix="Units: "
  />
</div>

jsx

<div>
  <label>Product Quantity:</label>
  <NumericTextBoxComponent
    value={qty}
    onChange={(e) => setQty(e.value)}
    min={1}
    step={1}
    prefix="Units: "
  />
</div>

Key Properties Reference

核心属性参考

Property	Type	Purpose
`value`	number	Current numeric value
`min`	number	Minimum allowed value
`max`	number	Maximum allowed value
`step`	number	Increment/decrement step (default: 1)
`decimals`	number	Number of decimal places when focused
`format`	string	Number format (n2, c2, p2, e2, etc.)
`currency`	string	ISO 4217 currency code (e.g., 'USD', 'EUR')
`placeholder`	string	Placeholder text when empty
`floatLabelType`	FloatLabelType	Float label behavior ('Never', 'Always', 'Auto')
`readonly`	boolean	Prevent user input
`enabled`	boolean	Enable or disable the control (default: true)
`strictMode`	boolean	Enforce min/max validation (default: true)
`validateDecimalOnType`	boolean	Restrict decimal length during typing
`showSpinButton`	boolean	Show/hide spinner arrows (default: true)
`showClearButton`	boolean	Show/hide clear icon
`allowMouseWheel`	boolean	Enable mouse wheel increment/decrement (default: true)
`cssClass`	string	Additional CSS classes for custom styling
`width`	number \| string	Width of the component

属性	类型	用途
`value`	number	当前数值
`min`	number	允许的最小值
`max`	number	允许的最大值
`step`	number	增减步长（默认：1）
`decimals`	number	聚焦时显示的小数位数
`format`	string	数字格式（n2、c2、p2、e2 等）
`currency`	string	ISO 4217 货币代码（例如 'USD'、'EUR'）
`placeholder`	string	空值时的占位文本
`floatLabelType`	FloatLabelType	浮动标签行为（'Never'、'Always'、'Auto'）
`readonly`	boolean	禁止用户输入
`enabled`	boolean	启用或禁用控件（默认：true）
`strictMode`	boolean	强制最小/最大值验证（默认：true）
`validateDecimalOnType`	boolean	输入时限制小数长度
`showSpinButton`	boolean	显示/隐藏增减箭头（默认：true）
`showClearButton`	boolean	显示/隐藏清除图标
`allowMouseWheel`	boolean	支持鼠标滚轮增减数值（默认：true）
`cssClass`	string	用于自定义样式的额外 CSS 类
`width`	number \| string	组件宽度

Common Use Cases

常见使用场景

1. Shopping Cart - Quantity Input

Integer-only, min=1, step=1, spinner for easy adjustment

2. Price Calculator - Currency Field

format="c2", min=0, prefix="$", two decimal places

3. Rating or Score - 0-100 Range

min=0, max=100, strictMode=true, no decimals

4. Discount Percentage

format="p", min=0, max=100, two decimal places

5. Measurement Input

decimals=2, suffix=" cm", min=0, spinner for precision

6. Financial Form

format="c2", validation, form integration, accessibility

**1. 购物车 - 数量输入

仅整数、min=1、step=1、增减按钮便于调整

**2. 价格计算器 - 货币字段

format="c2"、min=0、前缀="$"、保留两位小数

**3. 评分或分数 - 0-100 范围

min=0、max=100、strictMode=true、无小数

**4. 折扣百分比

format="p"、min=0、max=100、保留两位小数

**5. 测量值输入

decimals=2、后缀=" cm"、min=0、增减按钮控制精度

**6. 金融表单

format="c2"、验证、表单集成、无障碍支持

Next Steps

下一步操作

Package requirement: The packages
```
@syncfusion/ej2-react-inputs
```
,
```
@syncfusion/ej2-base
```
, and
```
@syncfusion/ej2-buttons
```
must be present in your project's
```
package.json
```
. Confirm they are already installed and that your lockfile (e.g.,
```
package-lock.json
```
or
```
yarn.lock
```
) pins their versions for supply-chain integrity. When adding them, use an explicit version range such as
```
@syncfusion/ej2-react-inputs@^27.x.x
```
to avoid unpinned dependency risks.
Getting Started reference: For installation details and basic setup, see references/getting-started.md.
Choose your reference: Based on your use case (formatting, validation, forms, etc.), navigate to the relevant reference section above.
Review examples: Each reference contains ready-to-use code samples that can be adapted to your requirements.
Customize: Modify the examples to fit your specific use case and application needs.

For detailed implementation guidance, navigate to the appropriate reference file above.

包依赖要求： 项目的
```
package.json
```
中必须存在
```
@syncfusion/ej2-react-inputs
```
、
```
@syncfusion/ej2-base
```
和
```
@syncfusion/ej2-buttons
```
包。确认已安装这些包，且锁文件（如
```
package-lock.json
```
或
```
yarn.lock
```
）固定了版本以保障供应链安全。添加依赖时请使用明确的版本范围，例如
```
@syncfusion/ej2-react-inputs@^27.x.x
```
，避免未固定版本的依赖风险。
快速入门参考： 安装详情和基础配置请查看 references/getting-started.md。
选择参考文档： 根据你的使用场景（格式化、验证、表单等），导航到上方对应的参考章节。
查看示例： 每个参考文档都包含开箱即用的代码示例，可根据你的需求适配。
自定义： 修改示例以适配你的具体使用场景和应用需求。

如需详细的实现指南，请导航到上方对应的参考文件。