syncfusion-react-numerictextbox

用途

Syncfusion React NumericTextBox 是 Syncfusion React 输入组件库中专门用于数字数据录入的输入组件。当需要在 React 应用中实现数字输入、格式化显示、范围校验或带微调按钮的数值控件时，可使用本技能获取实现指导。

主要能力

格式化输入：自动数字格式化，支持货币、百分比、科学计数法等格式。
校验：内置 min/max 范围校验，并提供 strictMode 严格模式。
微调按钮：可视化的递增/递减控件，步长可自定义。
小数控制：在输入过程中管理小数位与精度。
无障碍：完全符合 WCAG 2.2，支持 ARIA 属性与键盘导航。
国际化：支持区域设置与 RTL（从右到左）语言。
表单就绪：可与 React 表单及状态管理无缝集成。

使用方式

该技能以参考文档导航的形式组织，按需求引导至对应参考文件：

入门：references/getting-started.md，包含安装与包设置、CSS 导入与主题、React 组件导入与基础 JSX、创建第一个 NumericTextBox、运行应用。
格式与校验：references/formats-and-validation.md，包含标准格式说明符（货币、百分比、数字、科学计数法）、使用 # 和 0 模式的自定义数字格式、min 与 max 范围校验、strictMode 强制有效范围、实际格式化示例。
微调按钮与步长控制：references/spin-buttons-and-step.md，包含启用/禁用微调箭头、step 属性设置增量值、自定义微调按钮外观与行为、步长增量下的精度、键盘快捷键（上下方向键）。
装饰与样式：references/adornments-and-styling.md，包含前缀与后缀文本（单位、货币符号）、CSS 类与自定义样式、占位符/禁用/只读状态、聚焦与失焦事件处理、主题自定义与外观选项。
精度与小数：references/precision-decimals.md，包含 decimals 属性控制小数位、validateDecimalOnType 实时精度校验、显示中保留末尾零、舍入行为与边界情况、输入时与显示时的精度。
双向绑定与表单：references/two-way-binding-forms.md，包含 React 中的双向值绑定（value 属性 + onChange）、受控组件模式、React 状态管理、React Hook Form 集成、使用 NumericTextBox 进行表单校验。
全球化与无障碍：references/globalization-accessibility.md，包含国际化与区域设置支持、RTL 语言支持、WCAG 2.2 无障碍合规、键盘导航与快捷键、ARIA 属性屏幕阅读器支持、焦点管理与颜色对比度。
操作指南：references/how-to-guide.md，包含自定义校验模式、防止可空输入、保留末尾零、自定义微调按钮图标、常见故障排查与边界情况。
API 参考：references/api.md，包含完整属性参考（value、min、max、step、format、decimals 等）、方法参考（increment、decrement、getText、focusIn、focusOut、destroy 等）、事件参考及完整参数类型（change、blur、focus、created、destroyed）。

快速开始示例：

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 用于校验与控制。

常见模式示例：

货币输入：

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

百分比输入：

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

仅整数输入：

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

带校验的范围限制：

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

带标签的表单字段：

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

关键属性参考：

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）：强制 min/max 校验（默认 true）。
validateDecimalOnType（boolean）：输入时限制小数长度。
showSpinButton（boolean）：显示/隐藏微调箭头（默认 true）。
showClearButton（boolean）：显示/隐藏清除图标。
allowMouseWheel（boolean）：启用鼠标滚轮递增/递减（默认 true）。
cssClass（string）：用于自定义样式的附加 CSS 类。
width（number | string）：组件宽度。

适用场景

购物车数量输入：仅整数，min=1，step=1，使用微调按钮便于调整。
价格计算器货币字段：format="c2"，min=0，prefix="$"，两位小数。
评分或分数 0-100 范围：min=0，max=100，strictMode=true，无小数。
折扣百分比：format="p"，min=0，max=100，两位小数。
测量值输入：decimals=2，suffix=" cm"，min=0，使用微调按钮保证精度。
财务表单：format="c2"，校验，表单集成，无障碍。

限制与前置条件

包要求：项目中 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。
根据用例（格式化、校验、表单等）导航至相应参考章节；各参考包含可直接使用的代码示例，可按需调整。
关于收费、价格、平台支持范围等资料未提供的信息，暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与前置条件