syncfusion-react-inputs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Inputs

实现Syncfusion React输入组件

Uploader

The Syncfusion React UploaderComponent provides a rich file upload control with async upload, drag-and-drop, chunk upload with pause/resume/cancel, validation, templates, form integration, and accessibility support.

Syncfusion React UploaderComponent提供功能丰富的文件上传控件，支持异步上传、拖拽、带暂停/恢复/取消的分块上传、验证、模板、表单集成以及无障碍支持。

Navigation Guide

导航指南

🛑 Agentic use: Do not execute multiple steps autonomously. Confirm with the user before each action (install, run, file creation).

🛑 智能代理使用说明： 请勿自主执行多步骤操作。在执行每个操作（安装、运行、创建文件）前请与用户确认。

Getting Started

入门指南

📄 Read: references/getting-started.md

Installing
```
@syncfusion/ej2-react-inputs
```
🛑 STOP — Do not install packages autonomously. Ask the user to run:
npm install @syncfusion/ej2-react-inputs
. Verify with
npm audit
License registration
Basic
```
UploaderComponent
```
usage in JSX/TSX
CSS theme imports
Drop area configuration
Success and failure event handling

📄 阅读： references/getting-started.md

安装
```
@syncfusion/ej2-react-inputs
```
🛑 停止——请勿自主安装包。请用户运行：
npm install @syncfusion/ej2-react-inputs
。使用
npm audit
验证
许可证注册
在JSX/TSX中基础使用
```
UploaderComponent
```
CSS主题导入
拖放区域配置
成功与失败事件处理

Asynchronous Upload

异步上传

📄 Read: references/async-upload.md

```
asyncSettings
```
with
```
saveUrl
```
and
```
removeUrl
```
Multiple vs. single file upload (
```
multiple
```
)
Auto upload vs. manual upload (
```
autoUpload
```
)
Sequential upload (
```
sequentialUpload
```
)
Preloaded files (
```
files
```
property)
Adding custom HTTP headers via
```
uploading
```
/
```
removing
```
events
Server-side save/remove action examples

📄 阅读： references/async-upload.md

带
```
saveUrl
```
和
```
removeUrl
```
的
```
asyncSettings
```
多文件 vs 单文件上传（
```
multiple
```
）
自动上传 vs 手动上传（
```
autoUpload
```
）
顺序上传（
```
sequentialUpload
```
）
预加载文件（
```
files
```
属性）
通过
```
uploading
```
/
```
removing
```
事件添加自定义HTTP请求头
服务器端保存/移除操作示例

Chunk Upload

分块上传

📄 Read: references/chunk-upload.md

Enabling chunk upload with
```
asyncSettings.chunkSize
```
Retry configuration (
```
retryCount
```
,
```
retryAfterDelay
```
)
Pause and resume chunked uploads (
```
pause
```
,
```
resume
```
methods)
Cancel uploads (
```
cancel
```
method)
```
chunkSuccess
```
and
```
chunkFailure
```
events
Server-side chunk handling (C#)

📄 阅读： references/chunk-upload.md

通过
```
asyncSettings.chunkSize
```
启用分块上传
重试配置（
```
retryCount
```
,
```
retryAfterDelay
```
）
暂停和恢复分块上传（
```
pause
```
,
```
resume
```
方法）
取消上传（
```
cancel
```
方法）
```
chunkSuccess
```
和
```
chunkFailure
```
事件
服务器端分块处理（C#示例）

Validation

验证

📄 Read: references/validation.md

Allowed file extensions (
```
allowedExtensions
```
)
File size limits (
```
minFileSize
```
,
```
maxFileSize
```
)
Maximum file count using
```
selected
```
event
Duplicate file prevention
Drag-and-drop image validation

📄 阅读： references/validation.md

允许的文件扩展名（
```
allowedExtensions
```
）
文件大小限制（
```
minFileSize
```
,
```
maxFileSize
```
）
使用
```
selected
```
事件限制最大文件数量
防止重复文件
拖放图片验证

File Sources

文件来源

📄 Read: references/file-source.md

Clipboard paste upload
Directory/folder upload (
```
directoryUpload
```
)
Drag-and-drop with custom drop area (
```
dropArea
```
)
Customizing drop area appearance

📄 阅读： references/file-source.md

剪贴板粘贴上传
目录/文件夹上传（
```
directoryUpload
```
）
自定义拖放区域的拖拽上传（
```
dropArea
```
）
自定义拖放区域外观

Templates and Customization

模板与定制

📄 Read: references/template-customization.md

File list
```
template
```
property
Custom upload UI with
```
showFileList: false
```
Customizing action buttons (
```
buttons
```
property)
Progress bar customization
Hiding the default drop area
Style and appearance overrides

📄 阅读： references/template-customization.md

文件列表
```
template
```
属性
设置
```
showFileList: false
```
实现自定义上传UI
自定义操作按钮（
```
buttons
```
属性）
进度条定制
隐藏默认拖放区域
样式与外观覆盖

Advanced How-To Scenarios

高级场景指南

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

Programmatic file upload (
```
upload
```
method,
```
getFilesData
```
)
Invisible/background upload
Image preview before uploading
Resize images before upload
Sort selected files
Check file size / MIME type before upload
Confirm dialog before file removal
Open/edit uploaded files
Trigger file browser from external button
Convert uploaded image to binary
JWT authentication for secure upload ⚠️ Never hardcode tokens. Retrieve from a secure session store at runtime. Do not log request headers or token values.
Form support (HTML form, template-driven, reactive)
Localization (custom locale strings)
Accessibility and keyboard navigation

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

程序化文件上传（
```
upload
```
方法、
```
getFilesData
```
）
隐形/后台上传
上传前图片预览
上传前调整图片大小
排序选中文件
上传前检查文件大小/MIME类型
文件移除前确认对话框
打开/编辑已上传文件
从外部按钮触发文件浏览器
将上传图片转换为二进制
安全上传的JWT认证 ⚠️ 切勿硬编码令牌。在运行时从安全会话存储中获取。请勿记录请求头或令牌值。
表单支持（HTML表单、模板驱动表单、响应式表单）
本地化（自定义区域字符串）
无障碍与键盘导航

API Reference

API参考

📄 Read: references/api.md

All properties (

allowedExtensions

asyncSettings

autoUpload

buttons

cssClass

directoryUpload

dropArea

dropEffect

enabled

files

htmlAttributes

locale

maxFileSize

minFileSize

multiple

sequentialUpload

showFileList

template

, and more)

All methods (

upload

remove

cancel

pause

resume

retry

clearAll

getFilesData

bytesToSize

createFileList

sortFileList

)

All events (

uploading

success

failure

selected

removing

change

progress

chunkSuccess

chunkFailure

chunkUploading

actionComplete

beforeRemove

beforeUpload

canceling

clearing

fileListRendering

pausing

resuming

created

)

📄 阅读： references/api.md

所有属性（

allowedExtensions

asyncSettings

autoUpload

buttons

cssClass

directoryUpload

dropArea

dropEffect

enabled

files

htmlAttributes

locale

maxFileSize

minFileSize

multiple

sequentialUpload

showFileList

template

等）

所有方法（

upload

remove

cancel

pause

resume

retry

clearAll

getFilesData

bytesToSize

createFileList

sortFileList

）

所有事件（

uploading

success

failure

selected

removing

change

progress

chunkSuccess

chunkFailure

chunkUploading

actionComplete

beforeRemove

beforeUpload

canceling

clearing

fileListRendering

pausing

resuming

created

）

Quick Start Example

快速入门示例

tsx

import { UploaderComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-base/styles/material.css';
import '@syncfusion/ej2-buttons/styles/material.css';
import '@syncfusion/ej2-inputs/styles/material.css';
import '@syncfusion/ej2-popups/styles/material.css';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function App() {
  // ⚠️ Replace with your own server-side endpoints.
  // Never use third-party demo URLs in production — files will be sent to that external server.
  const asyncSettings = {
    saveUrl: '/api/upload/save',
    removeUrl: '/api/upload/remove'
  };

  const onSuccess = (args: any) => {
    console.log('Upload operation:', args.operation, 'File:', args.file.name);
  };

  const onFailure = (args: any) => {
    console.error('Upload failed:', args.file.name);
  };

  return (
    <UploaderComponent
      asyncSettings={asyncSettings}
      autoUpload={false}
      success={onSuccess}
      failure={onFailure}
    />
  );
}

tsx

import { UploaderComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-base/styles/material.css';
import '@syncfusion/ej2-buttons/styles/material.css';
import '@syncfusion/ej2-inputs/styles/material.css';
import '@syncfusion/ej2-popups/styles/material.css';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function App() {
  // ⚠️ 替换为您自己的服务器端端点。
  // 生产环境中切勿使用第三方演示URL——文件将发送到外部服务器。
  const asyncSettings = {
    saveUrl: '/api/upload/save',
    removeUrl: '/api/upload/remove'
  };

  const onSuccess = (args: any) => {
    console.log('上传操作:', args.operation, '文件:', args.file.name);
  };

  const onFailure = (args: any) => {
    console.error('上传失败:', args.file.name);
  };

  return (
    <UploaderComponent
      asyncSettings={asyncSettings}
      autoUpload={false}
      success={onSuccess}
      failure={onFailure}
    />
  );
}

Common Patterns

常见模式

Auto Upload with Validation

带验证的自动上传

tsx

<UploaderComponent
  asyncSettings={{ saveUrl: '/api/upload/save', removeUrl: '/api/upload/remove' }}
  allowedExtensions=".pdf,.doc,.docx"
  maxFileSize={5000000}
  multiple={true}
/>

tsx

<UploaderComponent
  asyncSettings={{ saveUrl: '/api/upload/save', removeUrl: '/api/upload/remove' }}
  allowedExtensions=".pdf,.doc,.docx"
  maxFileSize={5000000}
  multiple={true}
/>

Manual Upload with Custom Buttons

带自定义按钮的手动上传

tsx

<UploaderComponent
  asyncSettings={{ saveUrl: '/api/upload/save', removeUrl: '/api/upload/remove' }}
  autoUpload={false}
  buttons={{ browse: 'Choose File', clear: 'Clear All', upload: 'Upload All' }}
/>

tsx

<UploaderComponent
  asyncSettings={{ saveUrl: '/api/upload/save', removeUrl: '/api/upload/remove' }}
  autoUpload={false}
  buttons={{ browse: '选择文件', clear: '清空所有', upload: '全部上传' }}
/>

Chunk Upload for Large Files

大文件分块上传

tsx

<UploaderComponent
  asyncSettings={{
    saveUrl: '/api/upload/save',
    removeUrl: '/api/upload/remove',
    chunkSize: 500000   // 500 KB chunks
  }}
/>

tsx

<UploaderComponent
  asyncSettings={{
    saveUrl: '/api/upload/save',
    removeUrl: '/api/upload/remove',
    chunkSize: 500000   // 500 KB分块
  }}
/>

Key Decision Guide

关键决策指南

Need	Property/Event
Server URLs	`asyncSettings.saveUrl` + `asyncSettings.removeUrl`
Auto vs manual upload	`autoUpload` (default: `true` )
Large file upload	`asyncSettings.chunkSize`
Restrict file types	`allowedExtensions`
Limit file size	`maxFileSize` / `minFileSize`
Preload files from server	`files` prop
Upload one at a time	`sequentialUpload: true`
Entire folder upload	`directoryUpload: true`
Custom drop target	`dropArea`
Custom file list UI	`template` or `showFileList: false`
Add auth headers	`uploading` event → `args.currentRequest.setRequestHeader()`
Send extra form data	`uploading` event → `args.customFormData`

需求	属性/事件
服务器URL	`asyncSettings.saveUrl` + `asyncSettings.removeUrl`
自动 vs 手动上传	`autoUpload` （默认： `true` ）
大文件上传	`asyncSettings.chunkSize`
限制文件类型	`allowedExtensions`
限制文件大小	`maxFileSize` / `minFileSize`
从服务器预加载文件	`files` 属性
逐个上传文件	`sequentialUpload: true`
上传整个文件夹	`directoryUpload: true`
自定义拖放目标	`dropArea`
自定义文件列表UI	`template` 或 `showFileList: false`
添加认证请求头	`uploading` 事件 → `args.currentRequest.setRequestHeader()`
发送额外表单数据	`uploading` 事件 → `args.customFormData`

NumericTextBox

The Syncfusion React NumericTextBoxComponent is a specialized input control for numeric data entry with support for number formatting (currency, percentage, scientific notation), min/max range validation, spin buttons, decimal precision control, internationalization, RTL languages, and full WCAG 2.2 accessibility compliance.

Syncfusion React NumericTextBoxComponent是一款专门用于数值输入的控件，支持数值格式化（货币、百分比、科学计数法）、最小/最大范围验证、微调按钮、小数精度控制、国际化、RTL语言以及完全符合WCAG 2.2无障碍标准。

Documentation & Navigation Guide

文档与导航指南

🛑 Agentic use: Do not execute multiple steps autonomously. Confirm with the user before each action (install, run, file creation).

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属性的屏幕阅读器支持
焦点管理与颜色对比度

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>输入一个数字</h3>
      <NumericTextBoxComponent
        value={value}
        onChange={(e) => setValue(e.value)}
        min={0}
        max={100}
        step={1}
      />
      <p>当前值: {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="输入金额"
/>

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>产品数量:</label>
  <NumericTextBoxComponent
    value={qty}
    onChange={(e) => setQty(e.value)}
    min={1}
    step={1}
    prefix="单位: "
  />
</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	强制min/max验证（默认：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，prefix="$"，两位小数

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

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

4. 折扣百分比

format="p"，min=0，max=100，两位小数

5. 测量输入

decimals=2，suffix=" 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。
选择参考文档： 根据您的用例（格式化、验证、表单等），导航到上述相关参考章节。
查看示例： 每个参考文档都包含可直接使用的代码示例，可根据需求调整。
定制： 修改示例以适应您的特定用例和应用需求。

如需详细实现指导，请导航至上述相应参考文件。

TextBox

The TextBox component is a lightweight input control that captures user text input with support for floating labels, validation states, icons, and advanced features. This skill guides you through implementing, configuring, and customizing the TextBox component in React applications.

TextBox组件是一款轻量级输入控件，用于捕获用户文本输入，支持浮动标签、验证状态、图标以及高级功能。本指南将指导您在React应用中实现、配置和定制TextBox组件。

Navigation Guide

导航指南

🛑 Agentic use: Do not execute multiple steps autonomously. Confirm with the user before each action (install, run, file creation).

🛑 智能代理使用说明： 请勿自主执行多步骤操作。在执行每个操作（安装、运行、创建文件）前请与用户确认。

Getting Started

入门指南

📄 Read: references/getting-started.md

Vite setup for React development
Installing
```
@syncfusion/ej2-react-inputs
```
package 🛑 STOP — Do not install packages autonomously. Ask the user to run:
npm install @syncfusion/ej2-react-inputs
. Pin a specific version (e.g.,
@syncfusion/ej2-react-inputs@28.x.x
) and verify with
npm audit
Adding CSS imports and themes
Creating your first TextBox component
Adding icons and floating labels
Running the development server 🛑 STOP — Do not start the dev server autonomously. Ask the user to run:
npm run dev

📄 阅读： references/getting-started.md

React开发的Vite配置
安装
```
@syncfusion/ej2-react-inputs
```
包 🛑 停止——请勿自主安装包。请用户运行：
npm install @syncfusion/ej2-react-inputs
。固定特定版本（如
@syncfusion/ej2-react-inputs@28.x.x
）并使用
npm audit
验证
添加CSS导入与主题
创建第一个TextBox组件
添加图标与浮动标签
运行开发服务器 🛑 停止——请勿自主启动开发服务器。请用户运行：
npm run dev

Features and Groups

功能与分组

📄 Read: references/features-and-groups.md

Floating label behavior (Never, Always, Auto)
Icons with
```
addIcon()
```
method (prepend/append)
Clear button with
```
showClearButton
```
property
Rounded corner with
```
e-corner
```
CSS class
Disabled state with
```
enabled={false}
```
Multi-line textbox creation
TextBox with clear button and floating label combinations

📄 阅读： references/features-and-groups.md

浮动标签行为（Never, Always, Auto）
使用
```
addIcon()
```
方法添加图标（前置/后置）
带
```
showClearButton
```
属性的清除按钮
使用
```
e-corner
```
CSS类实现圆角
禁用状态（
```
enabled={false}
```
）
创建多行文本框
带清除按钮和浮动标签的TextBox组合

Styling and Sizing

样式与尺寸

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

Three predefined sizes: Normal, Small (
```
e-small
```
), Large (
```
e-bigger
```
)
Applying size classes via
```
cssClass
```
property
Rounded corner with
```
e-corner
```
CSS class
CSS customization for TextBox wrapper and floating label
Custom CSS classes and themes
Responsive design patterns

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

三种预定义尺寸：Normal, Small（
```
e-small
```
）, Large（
```
e-bigger
```
）
通过
```
cssClass
```
属性应用尺寸类
使用
```
e-corner
```
CSS类实现圆角
TextBox容器与浮动标签的CSS定制
自定义CSS类与主题
响应式设计模式

Multiline TextBox

多行TextBox

📄 Read: references/multiline-textbox.md

Creating multiline/textarea inputs with
```
multiline={true}
```
Floating labels with multiline
Auto-resizing textboxes
Disabling resize functionality
Limiting text length with
```
htmlAttributes={{ maxlength: '...' }}
```
Character counting and display

📄 阅读： references/multiline-textbox.md

设置
```
multiline={true}
```
创建多行/textarea输入框
多行文本框的浮动标签
自动调整大小的文本框
禁用调整大小功能
使用
```
htmlAttributes={{ maxlength: '...' }}
```
限制文本长度
字符计数与显示

Validation and States

验证与状态

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

Error, warning, and success validation states via
```
cssClass
```
Applying validation classes (
```
e-error
```
,
```
e-warning
```
,
```
e-success
```
)
Disabled state with
```
enabled={false}
```
(not
```
disabled
```
)
Read-only state with
```
readonly={true}
```
Differences between disabled and read-only
Dynamic color changes based on values using
```
input
```
event

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

通过
```
cssClass
```
设置错误、警告和成功验证状态
应用验证类（
```
e-error
```
,
```
e-warning
```
,
```
e-success
```
）
禁用状态（
```
enabled={false}
```
，而非
```
disabled
```
）
只读状态（
```
readonly={true}
```
）
禁用与只读的区别
使用
```
input
```
事件根据值动态更改颜色

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Adornments:
```
prependTemplate
```
and
```
appendTemplate
```
properties
Interactive adornments (password toggle, delete button)
React functional components with hooks
```
useState
```
,
```
useEffect
```
,
```
useRef
```
,
```
useReducer
```
integration
Event handling (created, input, change events)
Form validation patterns

📄 阅读： references/advanced-features.md

装饰元素：
```
prependTemplate
```
和
```
appendTemplate
```
属性
交互式装饰元素（密码切换、删除按钮）
带钩子的React函数组件
```
useState
```
,
```
useEffect
```
,
```
useRef
```
,
```
useReducer
```
集成
事件处理（created, input, change事件）
表单验证模式

Accessibility and Migration

无障碍与迁移

📄 Read: references/accessibility-and-migration.md

WCAG 2.2, Section 508, and WAI-ARIA compliance
Screen reader support and ARIA attributes
Right-to-Left (RTL) support with
```
enableRtl
```
property
Keyboard navigation support
Migrating from CSS TextBox to React component
Before/after code comparison

📄 阅读： references/accessibility-and-migration.md

WCAG 2.2、Section 508和WAI-ARIA合规性
屏幕阅读器支持与ARIA属性
使用
```
enableRtl
```
属性实现从右到左（RTL）支持
键盘导航支持
从CSS TextBox迁移到React组件
迁移前后代码对比

API Reference

API参考

📄 Read: references/api.md

All properties:

placeholder

floatLabelType

value

type

cssClass

multiline

showClearButton

enabled

readonly

enableRtl

enablePersistence

autocomplete

htmlAttributes

locale

width

prependTemplate

appendTemplate

Methods:

addIcon

addAttributes

removeAttributes

focusIn

focusOut

destroy

getPersistData

Events:
```
created
```
,
```
destroyed
```
,
```
change
```
,
```
input
```
,
```
focus
```
,
```
blur
```

📄 阅读： references/api.md

所有属性：

placeholder

floatLabelType

value

type

cssClass

multiline

showClearButton

enabled

readonly

enableRtl

enablePersistence

autocomplete

htmlAttributes

locale

width

prependTemplate

appendTemplate

方法：

addIcon

addAttributes

removeAttributes

focusIn

focusOut

destroy

getPersistData

事件：
```
created
```
,
```
destroyed
```
,
```
change
```
,
```
input
```
,
```
focus
```
,
```
blur
```

Quick Start

快速入门

Basic TextBox with Floating Label

带浮动标签的基础TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import './App.css';

export default function App() {
  return (
    <TextBoxComponent 
      placeholder="Enter your name" 
      floatLabelType="Auto"
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import './App.css';

export default function App() {
  return (
    <TextBoxComponent 
      placeholder="输入您的姓名" 
      floatLabelType="Auto"
    />
  );
}

TextBox with Icon

带图标的TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

export default function App() {
  const textboxRef = useRef(null);

  const handleCreate = () => {
    if (textboxRef.current) {
      textboxRef.current.addIcon('append', 'e-icons e-input-popup-date');
    }
  };

  return (
    <TextBoxComponent
      placeholder="Enter date"
      floatLabelType="Auto"
      ref={textboxRef}
      created={handleCreate}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

export default function App() {
  const textboxRef = useRef(null);

  const handleCreate = () => {
    if (textboxRef.current) {
      textboxRef.current.addIcon('append', 'e-icons e-input-popup-date');
    }
  };

  return (
    <TextBoxComponent
      placeholder="输入日期"
      floatLabelType="Auto"
      ref={textboxRef}
      created={handleCreate}
    />
  );
}

TextBox with Clear Button

带清除按钮的TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function App() {
  return (
    <TextBoxComponent
      placeholder="Enter your email"
      floatLabelType="Auto"
      showClearButton={true}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function App() {
  return (
    <TextBoxComponent
      placeholder="输入您的邮箱"
      floatLabelType="Auto"
      showClearButton={true}
    />
  );
}

Multiline TextBox

多行TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function App() {
  return (
    <TextBoxComponent
      multiline={true}
      placeholder="Enter your address"
      floatLabelType="Auto"
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function App() {
  return (
    <TextBoxComponent
      multiline={true}
      placeholder="输入您的地址"
      floatLabelType="Auto"
    />
  );
}

Common Patterns

常见模式

Form with Validation States

带验证状态的表单

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

export default function ValidationForm() {
  const [cssClass, setCssClass] = useState('');

  return (
    <div>
      <TextBoxComponent
        placeholder="Enter username"
        cssClass={cssClass}
        floatLabelType="Auto"
        input={(e: any) => {
          if (!e.value) setCssClass('');
          else if (e.value.length < 3) setCssClass('e-error');
          else if (e.value.length < 6) setCssClass('e-warning');
          else setCssClass('e-success');
        }}
      />
    </div>
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

export default function ValidationForm() {
  const [cssClass, setCssClass] = useState('');

  return (
    <div>
      <TextBoxComponent
        placeholder="输入用户名"
        cssClass={cssClass}
        floatLabelType="Auto"
        input={(e: any) => {
          if (!e.value) setCssClass('');
          else if (e.value.length < 3) setCssClass('e-error');
          else if (e.value.length < 6) setCssClass('e-warning');
          else setCssClass('e-success');
        }}
      />
    </div>
  );
}

Password TextBox with Toggle

带切换按钮的密码TextBox

tsx

import * as React from 'react';
import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef, useState } from 'react';

export default function PasswordInput() {
  const textboxRef = useRef<TextBoxComponent>(null);
  const [isVisible, setIsVisible] = useState(false);

  const toggleVisibility = () => {
    if (textboxRef.current) {
      const newVisibility = !isVisible;
      textboxRef.current.type = newVisibility ? 'text' : 'password';
      setIsVisible(newVisibility);
    }
  };

  function appendTemplate(): JSX.Element {
    return (
      <>
        <span className="e-input-separator"></span>
        <span
          className={`e-icons ${isVisible ? 'e-eye-slash' : 'e-eye'}`}
          onClick={toggleVisibility}
          style={{ cursor: 'pointer' }}
        ></span>
      </>
    );
  }

  return (
    <TextBoxComponent
      ref={textboxRef}
      type="password"
      placeholder="Enter password"
      floatLabelType="Auto"
      appendTemplate={appendTemplate}
    />
  );
}

tsx

import * as React from 'react';
import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef, useState } from 'react';

export default function PasswordInput() {
  const textboxRef = useRef<TextBoxComponent>(null);
  const [isVisible, setIsVisible] = useState(false);

  const toggleVisibility = () => {
    if (textboxRef.current) {
      const newVisibility = !isVisible;
      textboxRef.current.type = newVisibility ? 'text' : 'password';
      setIsVisible(newVisibility);
    }
  };

  function appendTemplate(): JSX.Element {
    return (
      <>
        <span className="e-input-separator"></span>
        <span
          className={`e-icons ${isVisible ? 'e-eye-slash' : 'e-eye'}`}
          onClick={toggleVisibility}
          style={{ cursor: 'pointer' }}
        ></span>
      </>
    );
  }

  return (
    <TextBoxComponent
      ref={textboxRef}
      type="password"
      placeholder="输入密码"
      floatLabelType="Auto"
      appendTemplate={appendTemplate}
    />
  );
}

Email Input with Unit Label

带单位标签的邮箱输入框

tsx

import * as React from 'react';
import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function EmailInput() {
  function prependTemplate(): JSX.Element {
    return (
      <>
        <span className="e-icons e-user"></span>
        <span className="e-input-separator"></span>
      </>
    );
  }

  function appendTemplate(): JSX.Element {
    return (
      <>
        <span className="e-input-separator"></span>
        <span>.com</span>
      </>
    );
  }

  return (
    <TextBoxComponent
      type="email"
      placeholder="Enter email"
      floatLabelType="Auto"
      prependTemplate={prependTemplate}
      appendTemplate={appendTemplate}
    />
  );
}

tsx

import * as React from 'react';
import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function EmailInput() {
  function prependTemplate(): JSX.Element {
    return (
      <>
        <span className="e-icons e-user"></span>
        <span className="e-input-separator"></span>
      </>
    );
  }

  function appendTemplate(): JSX.Element {
    return (
      <>
        <span className="e-input-separator"></span>
        <span>.com</span>
      </>
    );
  }

  return (
    <TextBoxComponent
      type="email"
      placeholder="输入邮箱"
      floatLabelType="Auto"
      prependTemplate={prependTemplate}
      appendTemplate={appendTemplate}
    />
  );
}

Rounded Corner TextBox

圆角TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function RoundedCornerTextBox() {
  return (
    <TextBoxComponent
      placeholder="Enter Date"
      cssClass="e-corner"
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function RoundedCornerTextBox() {
  return (
    <TextBoxComponent
      placeholder="输入日期"
      cssClass="e-corner"
    />
  );
}

Disabled TextBox

禁用的TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function DisabledTextBox() {
  return (
    <TextBoxComponent
      placeholder="Enter Name"
      enabled={false}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function DisabledTextBox() {
  return (
    <TextBoxComponent
      placeholder="输入姓名"
      enabled={false}
    />
  );
}

RTL TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function RTLTextBox() {
  return (
    <TextBoxComponent
      placeholder="أدخل اسمك"
      floatLabelType="Auto"
      enableRtl={true}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function RTLTextBox() {
  return (
    <TextBoxComponent
      placeholder="أدخل اسمك"
      floatLabelType="Auto"
      enableRtl={true}
    />
  );
}

Auto-sizing Multiline TextBox

自动调整大小的多行TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

export default function AutoSizeTextbox() {
  const textboxRef = useRef(null);

  const handleInput = () => {
    if (textboxRef.current) {
      const elem = textboxRef.current.respectiveElement;
      elem.style.height = 'auto';
      elem.style.height = elem.scrollHeight + 'px';
    }
  };

  const handleCreate = () => {
    if (textboxRef.current) {
      textboxRef.current.addAttributes({ rows: 1 });
    }
    handleInput();
  };

  return (
    <TextBoxComponent
      multiline={true}
      placeholder="Enter your message"
      floatLabelType="Auto"
      ref={textboxRef}
      created={handleCreate}
      input={handleInput}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

export default function AutoSizeTextbox() {
  const textboxRef = useRef(null);

  const handleInput = () => {
    if (textboxRef.current) {
      const elem = textboxRef.current.respectiveElement;
      elem.style.height = 'auto';
      elem.style.height = elem.scrollHeight + 'px';
    }
  };

  const handleCreate = () => {
    if (textboxRef.current) {
      textboxRef.current.addAttributes({ rows: 1 });
    }
    handleInput();
  };

  return (
    <TextBoxComponent
      multiline={true}
      placeholder="输入您的消息"
      floatLabelType="Auto"
      ref={textboxRef}
      created={handleCreate}
      input={handleInput}
    />
  );
}

Key Properties

关键属性

Property	Type	Purpose
`placeholder`	`string`	Hint text shown when input is empty
`floatLabelType`	`"Never" \| "Always" \| "Auto"`	Label animation behavior
`value`	`string`	Sets the content of the TextBox
`type`	`string`	Input type ( `text` , `password` , `email` , `number` , etc.)
`multiline`	`boolean`	Convert to textarea for multi-line input
`showClearButton`	`boolean`	Display clear button when input has value
`cssClass`	`string`	Apply CSS classes for sizing/validation/appearance (e.g., `"e-error"` , `"e-small"` , `"e-corner"` )
`enabled`	`boolean`	Enable ( `true` ) or disable ( `false` ) input interaction
`readonly`	`boolean`	Allow selection but prevent editing
`enableRtl`	`boolean`	Enable right-to-left rendering
`enablePersistence`	`boolean`	Persist value state between page reloads ⚠️ Stores data in browser storage — enable only with explicit user consent
`autocomplete`	`string`	Control browser autocomplete ( `"on"` \| `"off"` )
`htmlAttributes`	`{ [key: string]: string }`	Pass additional HTML attributes (e.g., `{ maxlength: '200' }` )
`locale`	`string`	Override global culture/localization value
`width`	`number \| string`	Set component width
`prependTemplate`	`() => JSX.Element`	Render element before input
`appendTemplate`	`() => JSX.Element`	Render element after input

属性	类型	用途
`placeholder`	`string`	输入为空时显示的提示文本
`floatLabelType`	`"Never" \| "Always" \| "Auto"`	标签动画行为
`value`	`string`	设置TextBox的内容
`type`	`string`	输入类型（ `text` , `password` , `email` , `number` 等）
`multiline`	`boolean`	转换为textarea以支持多行输入
`showClearButton`	`boolean`	输入有值时显示清除按钮
`cssClass`	`string`	应用CSS类进行尺寸/验证/外观设置（如 `"e-error"` , `"e-small"` , `"e-corner"` ）
`enabled`	`boolean`	启用（ `true` ）或禁用（ `false` ）输入交互
`readonly`	`boolean`	允许选择但阻止编辑
`enableRtl`	`boolean`	启用从右到左渲染
`enablePersistence`	`boolean`	在页面重载之间保留值状态 ⚠️ 将数据存储在浏览器存储中——仅在获得用户明确同意后启用
`autocomplete`	`string`	控制浏览器自动完成（ `"on"` \| `"off"` ）
`htmlAttributes`	`{ [key: string]: string }`	传递额外HTML属性（如 `{ maxlength: '200' }` ）
`locale`	`string`	覆盖全局文化/本地化值
`width`	`number \| string`	设置组件宽度
`prependTemplate`	`() => JSX.Element`	在输入前渲染元素
`appendTemplate`	`() => JSX.Element`	在输入后渲染元素

Key Events

关键事件

Event	Arguments	Purpose
`created`	`Object`	Fires after component initialization
`destroyed`	`Object`	Fires when component is destroyed
`change`	`ChangedEventArgs`	Fires when value changes on focus-out
`input`	`InputEventArgs`	Fires on every keystroke
`focus`	`FocusInEventArgs`	Fires when TextBox gains focus
`blur`	`FocusOutEventArgs`	Fires when TextBox loses focus

事件	参数	用途
`created`	`Object`	组件初始化完成后触发
`destroyed`	`Object`	组件销毁时触发
`change`	`ChangedEventArgs`	失焦时值发生变化时触发
`input`	`InputEventArgs`	每次按键时触发
`focus`	`FocusInEventArgs`	TextBox获得焦点时触发
`blur`	`FocusOutEventArgs`	TextBox失去焦点时触发

CheckBox

The Syncfusion React

CheckBoxComponent

is a graphical UI element that allows users to select one or more options. It supports checked, unchecked, and indeterminate states, flexible label positioning, size variants, full accessibility compliance, and rich CSS customization.

Package:

@syncfusion/ej2-react-buttons

Syncfusion React

CheckBoxComponent

是一款图形化UI元素，允许用户选择一个或多个选项。它支持选中、未选中和不确定状态，灵活的标签定位，尺寸变体，完全符合无障碍标准，以及丰富的CSS定制能力。

包：

@syncfusion/ej2-react-buttons

Navigation Guide

导航指南

🛑 Agentic use: Do not execute multiple steps autonomously. Confirm with the user before each action (install, run, file creation).

🛑 智能代理使用说明： 请勿自主执行多步骤操作。在执行每个操作（安装、运行、创建文件）前请与用户确认。

Getting Started

入门指南

📄 Read: references/getting-started.md

Installing
```
@syncfusion/ej2-react-buttons
```
🛑 STOP — Do not install packages autonomously. Ask the user to run:
npm install @syncfusion/ej2-react-buttons --save
. Verify with
npm audit
CSS theme imports for Tailwind3
Minimal
```
CheckBoxComponent
```
setup
Running the Vite/React app 🛑 STOP — Do not start the dev server autonomously. Ask the user to run:
npm run dev

📄 阅读： references/getting-started.md

安装

@syncfusion/ej2-react-buttons

🛑 停止——请勿自主安装包。请用户运行：
npm install @syncfusion/ej2-react-buttons --save
。使用
npm audit
验证

Tailwind3的CSS主题导入
最小化
```
CheckBoxComponent
```
配置
运行Vite/React应用 🛑 停止——请勿自主启动开发服务器。请用户运行：
npm run dev

States (Checked, Unchecked, Indeterminate, Disabled)

状态（选中、未选中、不确定、禁用）

📄 Read: references/states.md

Setting
```
checked={true}
```
for checked state
Setting
```
indeterminate={true}
```
for indeterminate state
Setting
```
disabled={true}
```
for disabled state
Combined state examples

📄 阅读： references/states.md

设置
```
checked={true}
```
实现选中状态
设置
```
indeterminate={true}
```
实现不确定状态
设置
```
disabled={true}
```
实现禁用状态
组合状态示例

Label and Size

标签与尺寸

📄 Read: references/label-and-size.md

```
label
```
prop for caption text
```
labelPosition
```
(
```
"Before"
```
/
```
"After"
```
)
Small size via
```
cssClass="e-small"
```
Default vs. small size examples

📄 阅读： references/label-and-size.md

```
label
```
属性用于设置标题文本
```
labelPosition
```
（
```
"Before"
```
/
```
"After"
```
）
通过
```
cssClass="e-small"
```
设置小尺寸
默认尺寸与小尺寸示例

Style and Appearance

样式与外观

📄 Read: references/style-and-appearance.md

Available CSS classes for overriding checkbox styles
Color variant customization (primary, success, warning, danger, info)
Custom frame shapes (round checkbox)
Custom check icon
Theme Studio integration

📄 阅读： references/style-and-appearance.md

用于覆盖复选框样式的可用CSS类
颜色变体定制（primary, success, warning, danger, info）
自定义框形状（圆形复选框）
自定义勾选图标
Theme Studio集成

Accessibility and RTL

无障碍与RTL

📄 Read: references/accessibility.md

WCAG 2.2 / Section 508 compliance
WAI-ARIA attributes (
```
aria-disabled
```
)
Keyboard navigation (Space key)
Right-to-left (
```
enableRtl
```
) support
Screen reader support

📄 阅读： references/accessibility.md

WCAG 2.2 / Section 508合规性
WAI-ARIA属性（
```
aria-disabled
```
）
键盘导航（空格键）
从右到左（
```
enableRtl
```
）支持
屏幕阅读器支持

How-To Guides

操作指南

📄 Read: references/how-to.md

Name and value in form submission
Enabling right-to-left display
Building customized checkbox variants

📄 阅读： references/how-to.md

表单提交中的name和value
启用从右到左显示
构建自定义复选框变体

API Reference

API参考

📄 Read: references/api.md

All properties:

checked

cssClass

disabled

enableHtmlSanitizer

enablePersistence

enableRtl

htmlAttributes

indeterminate

label

labelPosition

locale

name

value

Methods:
```
click()
```
,
```
destroy()
```
,
```
focusIn()
```
Events:
```
change
```
,
```
created
```

📄 阅读： references/api.md

所有属性：

checked

cssClass

disabled

enableHtmlSanitizer

enablePersistence

enableRtl

htmlAttributes

indeterminate

label

labelPosition

locale

name

value

方法：
```
click()
```
,
```
destroy()
```
,
```
focusIn()
```
事件：
```
change
```
,
```
created
```

Quick Start

快速入门

bash

npm install @syncfusion/ej2-react-buttons --save

bash

npm install @syncfusion/ej2-react-buttons --save

Then run: npm audit

然后运行：npm audit


```css
/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css";

tsx

import { CheckBoxComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';
import './App.css';

function App() {
  return (
    <div>
      <CheckBoxComponent label="Accept Terms" />
    </div>
  );
}
export default App;


```css
/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css";

tsx

import { CheckBoxComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';
import './App.css';

function App() {
  return (
    <div>
      <CheckBoxComponent label="接受条款" />
    </div>
  );
}
export default App;

Common Patterns

常见模式

Controlled Checkbox with Change Handler

带变更处理程序的受控复选框

tsx

import { CheckBoxComponent } from '@syncfusion/ej2-react-buttons';
import { ChangeEventArgs } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  const [isChecked, setIsChecked] = React.useState(false);

  const handleChange = (args: ChangeEventArgs) => {
    setIsChecked(args.checked);
  };

  return (
    <CheckBoxComponent
      label="Subscribe to newsletter"
      checked={isChecked}
      change={handleChange}
    />
  );
}
export default App;

tsx

import { CheckBoxComponent } from '@syncfusion/ej2-react-buttons';
import { ChangeEventArgs } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  const [isChecked, setIsChecked] = React.useState(false);

  const handleChange = (args: ChangeEventArgs) => {
    setIsChecked(args.checked);
  };

  return (
    <CheckBoxComponent
      label="订阅新闻"
      checked={isChecked}
      change={handleChange}
    />
  );
}
export default App;

Parent / Children with Indeterminate State

父/子复选框与不确定状态

tsx

import { CheckBoxComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  return (
    <ul>
      {/* Parent: indeterminate when some children are selected */}
      <li><CheckBoxComponent label="Select All" indeterminate={true} /></li>
      <li><CheckBoxComponent label="Option A" checked={true} /></li>
      <li><CheckBoxComponent label="Option B" /></li>
    </ul>
  );
}
export default App;

tsx

import { CheckBoxComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  return (
    <ul>
      {/* 父复选框：部分子项选中时为不确定状态 */}
      <li><CheckBoxComponent label="全选" indeterminate={true} /></li>
      <li><CheckBoxComponent label="选项A" checked={true} /></li>
      <li><CheckBoxComponent label="选项B" /></li>
    </ul>
  );
}
export default App;

Form Submission with Name and Value

带name和value的表单提交

tsx

import { CheckBoxComponent, ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  return (
    <form>
      <CheckBoxComponent name="hobby" value="Reading" label="Reading" checked={true} />
      <CheckBoxComponent name="hobby" value="Gaming" label="Gaming" />
      <ButtonComponent isPrimary={true}>Submit</ButtonComponent>
    </form>
  );
}
export default App;

tsx

import { CheckBoxComponent, ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  return (
    <form>
      <CheckBoxComponent name="hobby" value="Reading" label="阅读" checked={true} />
      <CheckBoxComponent name="hobby" value="Gaming" label="游戏" />
      <ButtonComponent isPrimary={true}>提交</ButtonComponent>
    </form>
  );
}
export default App;

Key Props at a Glance

关键属性概览

Prop	Type	Default	Purpose
`label`	`string`	`''`	Caption text next to checkbox
`checked`	`boolean`	`false`	Checked state
`indeterminate`	`boolean`	`false`	Indeterminate (partial) state
`disabled`	`boolean`	`false`	Disabled state
`labelPosition`	`'Before' \| 'After'`	`'After'`	Label placement
`cssClass`	`string`	`''`	Custom CSS class(es)
`name`	`string`	`''`	Form field name
`value`	`string`	`''`	Form field value
`enableRtl`	`boolean`	`false`	Right-to-left rendering
`enablePersistence`	`boolean`	`false`	Persist state across reloads ⚠️ Stores data in browser storage — enable only with explicit user consent

属性	类型	默认值	用途
`label`	`string`	`''`	复选框旁的标题文本
`checked`	`boolean`	`false`	选中状态
`indeterminate`	`boolean`	`false`	不确定（部分选中）状态
`disabled`	`boolean`	`false`	禁用状态
`labelPosition`	`'Before' \| 'After'`	`'After'`	标签位置
`cssClass`	`string`	`''`	自定义CSS类(es)
`name`	`string`	`''`	表单字段名称
`value`	`string`	`''`	表单字段值
`enableRtl`	`boolean`	`false`	从右到左渲染
`enablePersistence`	`boolean`	`false`	在重载之间保留状态 ⚠️ 将数据存储在浏览器存储中——仅在获得用户明确同意后启用

Signature

The Syncfusion React

SignatureComponent

renders a canvas-based signature pad that captures smooth handwritten signatures using variable-width bezier curves. It supports drawing, saving (PNG/JPEG/SVG/base64/blob), loading existing signatures, undo/redo history, customizable stroke and background appearance, and full accessibility compliance.

Package:

@syncfusion/ej2-react-inputs

Syncfusion React

SignatureComponent

渲染一个基于画布的签名板，使用可变宽度的贝塞尔曲线捕获流畅的手写签名。它支持绘制、保存（PNG/JPEG/SVG/base64/blob）、加载现有签名、撤销/重做历史记录、自定义笔触和背景外观，以及完全符合无障碍标准。

包：

@syncfusion/ej2-react-inputs

Navigation Guide

导航指南

🛑 Agentic use: Do not execute multiple steps autonomously. Confirm with the user before each action (install, run, file creation).

🛑 智能代理使用说明： 请勿自主执行多步骤操作。在执行每个操作（安装、运行、创建文件）前请与用户确认。

Getting Started

入门指南

📄 Read: references/getting-started.md

Installing
```
@syncfusion/ej2-react-inputs
```
🛑 STOP — Do not install packages autonomously. Ask the user to run:
npm install @syncfusion/ej2-react-inputs --save
. Verify with
npm audit
CSS theme imports (Tailwind3)
Minimal
```
SignatureComponent
```
setup
Running the application 🛑 STOP — Do not start the dev server autonomously. Ask the user to run:
npm run dev

📄 阅读： references/getting-started.md

安装

@syncfusion/ej2-react-inputs

🛑 停止——请勿自主安装包。请用户运行：
npm install @syncfusion/ej2-react-inputs --save
。使用
npm audit
验证

Tailwind3的CSS主题导入
最小化
```
SignatureComponent
```
配置
运行应用 🛑 停止——请勿自主启动开发服务器。请用户运行：
npm run dev

Customization

定制

📄 Read: references/customization.md

Stroke width:
```
maxStrokeWidth
```
,
```
minStrokeWidth
```
,
```
velocity
```
Stroke color:
```
strokeColor
```
Background color:
```
backgroundColor
```
Background image:
```
backgroundImage
```

📄 阅读： references/customization.md

笔触宽度：
```
maxStrokeWidth
```
,
```
minStrokeWidth
```
,
```
velocity
```
笔触颜色：
```
strokeColor
```
背景颜色：
```
backgroundColor
```
背景图片：
```
backgroundImage
```

Open and Save

打开与保存

📄 Read: references/open-save.md

Load signature from base64 or URL (
```
load
```
)
Save as base64 (
```
getSignature
```
)
Save as Blob (
```
saveAsBlob
```
,
```
getBlob
```
)
Save as image file — PNG, JPEG, SVG (
```
save
```
)
Save with background (
```
saveWithBackground
```
)

📄 阅读： references/open-save.md

从base64或URL加载签名（
```
load
```
）
保存为base64（
```
getSignature
```
）
保存为Blob（
```
saveAsBlob
```
,
```
getBlob
```
）
保存为图片文件——PNG、JPEG、SVG（
```
save
```
）
带背景保存（
```
saveWithBackground
```
）

User Interaction

用户交互

📄 Read: references/user-interaction.md

Undo/redo strokes (
```
undo
```
,
```
redo
```
,
```
canUndo
```
,
```
canRedo
```
)
Clear the canvas (
```
clear
```
,
```
isEmpty
```
)
Disabled state (
```
disabled
```
)
Read-only mode (
```
isReadOnly
```
)
Draw text as signature (
```
draw
```
)
Keyboard shortcuts (Ctrl+Z, Ctrl+Y, Ctrl+S, Delete)

📄 阅读： references/user-interaction.md

撤销/重做笔触（
```
undo
```
,
```
redo
```
,
```
canUndo
```
,
```
canRedo
```
）
清除画布（
```
clear
```
,
```
isEmpty
```
）
禁用状态（
```
disabled
```
）
只读模式（
```
isReadOnly
```
）
将文本绘制为签名（
```
draw
```
）
键盘快捷键（Ctrl+Z, Ctrl+Y, Ctrl+S, Delete）

Toolbar Integration

工具栏集成

📄 Read: references/toolbar-integration.md

Integrating with Syncfusion
```
ToolbarComponent
```
Wiring undo, redo, clear, and save toolbar buttons
Stroke color picker using
```
ColorPickerComponent
```
Background color picker integration
Stroke width dropdown with
```
DropDownListComponent
```
Enabling/disabling toolbar buttons based on signature state

📄 阅读： references/toolbar-integration.md

与Syncfusion
```
ToolbarComponent
```
集成
连接撤销、重做、清除和保存工具栏按钮
使用
```
ColorPickerComponent
```
实现笔触颜色选择器
背景颜色选择器集成
使用
```
DropDownListComponent
```
实现笔触宽度下拉菜单
根据签名状态启用/禁用工具栏按钮

Accessibility

无障碍

📄 Read: references/accessibility.md

WCAG 2.2 / Section 508 compliance
Keyboard interaction (Ctrl+Z, Ctrl+Y, Ctrl+S, Delete)
Screen reader and mobile device support

📄 阅读： references/accessibility.md

WCAG 2.2 / Section 508合规性
键盘交互（Ctrl+Z, Ctrl+Y, Ctrl+S, Delete）
屏幕阅读器和移动设备支持

API Reference

API参考

📄 Read: references/api.md

All properties:

backgroundColor

backgroundImage

disabled

enablePersistence

isReadOnly

maxStrokeWidth

minStrokeWidth

saveWithBackground

strokeColor

velocity

All methods:

canRedo

canUndo

clear

destroy

draw

getBlob

getSignature

isEmpty

load

redo

refresh

save

saveAsBlob

undo

Events:
```
beforeSave
```
,
```
change
```
,
```
created
```

📄 阅读： references/api.md

所有属性：

backgroundColor

backgroundImage

disabled

enablePersistence

isReadOnly

maxStrokeWidth

minStrokeWidth

saveWithBackground

strokeColor

velocity

所有方法：

canRedo

canUndo

clear

destroy

draw

getBlob

getSignature

isEmpty

load

redo

refresh

save

saveAsBlob

undo

事件：
```
beforeSave
```
,
```
change
```
,
```
created
```

Quick Start

快速入门

bash

npm install @syncfusion/ej2-react-inputs --save

bash

npm install @syncfusion/ej2-react-inputs --save

Then run: npm audit

然后运行：npm audit


```css
/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";

tsx

import { SignatureComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';
import './App.css';

function App() {
  return (
    <div>
      <SignatureComponent id="signature" />
    </div>
  );
}
export default App;


```css
/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";

tsx

import { SignatureComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';
import './App.css';

function App() {
  return (
    <div>
      <SignatureComponent id="signature" />
    </div>
  );
}
export default App;

Common Patterns

常见模式

Signature with Undo/Redo/Clear Controls

带撤销/重做/清除控件的签名板

tsx

import { SignatureComponent, SignatureChangeEventArgs } from '@syncfusion/ej2-react-inputs';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';
import { useRef } from 'react';

function App() {
  const sigRef = React.useRef<SignatureComponent>(null);
  const [canUndo, setCanUndo] = React.useState(false);
  const [canRedo, setCanRedo] = React.useState(false);
  const [isEmpty, setIsEmpty] = React.useState(true);

  function handleChange(args: SignatureChangeEventArgs) {
    if (sigRef.current) {
      setCanUndo(sigRef.current.canUndo());
      setCanRedo(sigRef.current.canRedo());
      setIsEmpty(sigRef.current.isEmpty());
    }
  }

  return (
    <div>
      <ButtonComponent disabled={!canUndo} onClick={() => sigRef.current?.undo()}>Undo</ButtonComponent>
      <ButtonComponent disabled={!canRedo} onClick={() => sigRef.current?.redo()}>Redo</ButtonComponent>
      <ButtonComponent disabled={isEmpty} onClick={() => sigRef.current?.clear()}>Clear</ButtonComponent>
      <SignatureComponent id="signature" ref={sigRef} change={handleChange} />
    </div>
  );
}
export default App;

tsx

import { SignatureComponent, SignatureChangeEventArgs } from '@syncfusion/ej2-react-inputs';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';
import { useRef } from 'react';

function App() {
  const sigRef = React.useRef<SignatureComponent>(null);
  const [canUndo, setCanUndo] = React.useState(false);
  const [canRedo, setCanRedo] = React.useState(false);
  const [isEmpty, setIsEmpty] = React.useState(true);

  function handleChange(args: SignatureChangeEventArgs) {
    if (sigRef.current) {
      setCanUndo(sigRef.current.canUndo());
      setCanRedo(sigRef.current.canRedo());
      setIsEmpty(sigRef.current.isEmpty());
    }
  }

  return (
    <div>
      <ButtonComponent disabled={!canUndo} onClick={() => sigRef.current?.undo()}>撤销</ButtonComponent>
      <ButtonComponent disabled={!canRedo} onClick={() => sigRef.current?.redo()}>重做</ButtonComponent>
      <ButtonComponent disabled={isEmpty} onClick={() => sigRef.current?.clear()}>清除</ButtonComponent>
      <SignatureComponent id="signature" ref={sigRef} change={handleChange} />
    </div>
  );
}
export default App;

Save Signature as PNG

将签名保存为PNG

tsx

import { SignatureComponent } from '@syncfusion/ej2-react-inputs';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  const sigRef = React.useRef<SignatureComponent>(null);

  function saveSignature() {
    sigRef.current?.save('Png', 'MySignature');
  }

  return (
    <div>
      <SignatureComponent id="signature" ref={sigRef} />
      <ButtonComponent onClick={saveSignature}>Save as PNG</ButtonComponent>
    </div>
  );
}
export default App;

tsx

import { SignatureComponent } from '@syncfusion/ej2-react-inputs';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  const sigRef = React.useRef<SignatureComponent>(null);

  function saveSignature() {
    sigRef.current?.save('Png', 'MySignature');
  }

  return (
    <div>
      <SignatureComponent id="signature" ref={sigRef} />
      <ButtonComponent onClick={saveSignature}>保存为PNG</ButtonComponent>
    </div>
  );
}
export default App;

Key Props at a Glance

关键属性概览

Prop	Type	Default	Purpose
`strokeColor`	`string`	`'#000000'`	Pen/stroke color (hex, rgb, or name)
`backgroundColor`	`string`	`''`	Canvas background color
`backgroundImage`	`string`	`''`	Canvas background image URL
`maxStrokeWidth`	`number`	`2`	Maximum stroke thickness
`minStrokeWidth`	`number`	`0.5`	Minimum stroke thickness
`velocity`	`number`	`0.7`	Controls stroke width variation
`disabled`	`boolean`	`false`	Disables the component
`isReadOnly`	`boolean`	`false`	Prevents drawing, allows focus
`saveWithBackground`	`boolean`	`true`	Include background when saving
`enablePersistence`	`boolean`	`false`	Persist state across page reloads ⚠️ Stores signature data (biometric input) in browser storage — enable only with explicit user consent and applicable privacy disclosures

属性	类型	默认值	用途
`strokeColor`	`string`	`'#000000'`	画笔/笔触颜色（十六进制、rgb或颜色名称）
`backgroundColor`	`string`	`''`	画布背景颜色
`backgroundImage`	`string`	`''`	画布背景图片URL
`maxStrokeWidth`	`number`	`2`	最大笔触粗细
`minStrokeWidth`	`number`	`0.5`	最小笔触粗细
`velocity`	`number`	`0.7`	控制笔触宽度变化
`disabled`	`boolean`	`false`	禁用组件
`isReadOnly`	`boolean`	`false`	阻止绘制，允许聚焦
`saveWithBackground`	`boolean`	`true`	保存时包含背景
`enablePersistence`	`boolean`	`false`	在页面重载之间保留状态 ⚠️ 将签名数据（生物特征输入）存储在浏览器存储中——仅在获得用户明确同意和适用隐私声明后启用

OTP Input

A focused input component for collecting one-time passwords, PINs, and verification codes. Renders a configurable number of individual character input fields with full keyboard navigation, accessibility support, and visual styling modes.

一款专注于收集一次性密码、PIN码和验证码的输入组件。渲染可配置数量的独立字符输入字段，支持完整的键盘导航、无障碍支持和视觉样式模式。

Quick Start

快速入门

tsx

import { OtpInputComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';
import './App.css';

function App() {
  return (
    <div id="container">
      <OtpInputComponent id="otpinput" />
    </div>
  );
}

export default App;

CSS (src/App.css):

css

@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";

Install:

bash

npm install @syncfusion/ej2-react-inputs --save

tsx

import { OtpInputComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';
import './App.css';

function App() {
  return (
    <div id="container">
      <OtpInputComponent id="otpinput" />
    </div>
  );
}

export default App;

CSS (src/App.css):

css

@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";

安装：

bash

npm install @syncfusion/ej2-react-inputs --save

Common Patterns

常见模式

6-digit OTP with verification callback

带验证回调的6位OTP

tsx

import { OtpInputComponent, OtpChangedEventArgs } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';

function App() {
  const handleValueChanged = (args: OtpChangedEventArgs) => {
    console.log('Complete OTP:', args.value);
    // Call your API verification here
  };

  return (
    <OtpInputComponent
      id="otpinput"
      length={6}
      autoFocus={true}
      valueChanged={handleValueChanged}
    />
  );
}

tsx

import { OtpInputComponent, OtpChangedEventArgs } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';

function App() {
  const handleValueChanged = (args: OtpChangedEventArgs) => {
    console.log('完整OTP:', args.value);
    // 在此调用您的API验证逻辑
  };

  return (
    <OtpInputComponent
      id="otpinput"
      length={6}
      autoFocus={true}
      valueChanged={handleValueChanged}
    />
  );
}

Password-masked OTP with error state

带错误状态的密码掩码OTP

tsx

import { OtpInputComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';

function App() {
  return (
    <OtpInputComponent
      id="otpinput"
      type="password"
      length={6}
      cssClass="e-error"
      placeholder="*"
    />
  );
}

tsx

import { OtpInputComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';

function App() {
  return (
    <OtpInputComponent
      id="otpinput"
      type="password"
      length={6}
      cssClass="e-error"
      placeholder="*"
    />
  );
}

Alphanumeric OTP with separator

带分隔符的字母数字OTP

tsx

import { OtpInputComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';

function App() {
  return (
    <OtpInputComponent
      id="otpinput"
      type="text"
      length={6}
      separator="-"
      textTransform="uppercase"
      stylingMode="filled"
    />
  );
}

tsx

import { OtpInputComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';

function App() {
  return (
    <OtpInputComponent
      id="otpinput"
      type="text"
      length={6}
      separator="-"
      textTransform="uppercase"
      stylingMode="filled"
    />
  );
}

Key Properties

关键属性

Property	Type	Default	Purpose
`length`	`number`	`4`	Number of OTP input fields
`value`	`string \| number`	`''`	Current OTP value
`type`	`'number' \| 'text' \| 'password'`	`'number'`	Input character type
`stylingMode`	`'outlined' \| 'filled' \| 'underlined'`	`'outlined'`	Visual style variant
`placeholder`	`string`	`''`	Hint character(s) per field
`separator`	`string`	`''`	Character between fields
`cssClass`	`string`	`''`	Custom/predefined CSS class ( `e-success` , `e-warning` , `e-error` )
`disabled`	`boolean`	`false`	Disables user input
`autoFocus`	`boolean`	`false`	Auto-focuses on render
`enableRtl`	`boolean`	`false`	Right-to-left layout
`textTransform`	`'none' \| 'uppercase' \| 'lowercase'`	`'none'`	Case transformation
`ariaLabels`	`string[]`	`[]`	Per-field ARIA labels
`htmlAttributes`	`{ [key: string]: string }`	`{}`	Extra HTML attributes

属性	类型	默认值	用途
`length`	`number`	`4`	OTP输入字段的数量
`value`	`string \| number`	`''`	当前OTP值
`type`	`'number' \| 'text' \| 'password'`	`'number'`	输入字符类型
`stylingMode`	`'outlined' \| 'filled' \| 'underlined'`	`'outlined'`	视觉样式变体
`placeholder`	`string`	`''`	每个字段的提示字符(s)
`separator`	`string`	`''`	字段之间的分隔符
`cssClass`	`string`	`''`	自定义/预定义CSS类（ `e-success` , `e-warning` , `e-error` ）
`disabled`	`boolean`	`false`	禁用用户输入
`autoFocus`	`boolean`	`false`	渲染时自动聚焦
`enableRtl`	`boolean`	`false`	从右到左布局
`textTransform`	`'none' \| 'uppercase' \| 'lowercase'`	`'none'`	大小写转换
`ariaLabels`	`string[]`	`[]`	每个字段的ARIA标签
`htmlAttributes`	`{ [key: string]: string }`	`{}`	额外HTML属性

Navigation Guide

导航指南

Installation, Setup & Basic Usage

安装、配置与基础使用

📄 Read: references/getting-started.md

npm install and Vite project setup
CSS theme imports
Minimal working example
Setting OTP length
Setting a default value
Auto-focus on load
Troubleshooting

📄 阅读： references/getting-started.md

npm安装与Vite项目配置
CSS主题导入
最小化可用示例
设置OTP长度
设置默认值
加载时自动聚焦
故障排除

Input Types, Styling & Visual Configuration

输入类型、样式与视觉配置

📄 Read: references/configuration.md

Input types: number, text, password
Styling modes: outlined, filled, underlined
Placeholder text (single/per-field)
Separator characters
Disabled state
CSS class customization (
```
e-success
```
,
```
e-warning
```
,
```
e-error
```
)
RTL support
Text transform (uppercase/lowercase)
State persistence

📄 阅读： references/configuration.md

输入类型：number, text, password
样式模式：outlined, filled, underlined
占位文本（单个/每个字段）
分隔符
禁用状态
CSS类定制（
```
e-success
```
,
```
e-warning
```
,
```
e-error
```
）
RTL支持
文本转换（大写/小写）
状态持久化

Events & Interaction Handling

事件与交互处理

📄 Read: references/events.md

```
created
```
event (post-render init)
```
focus
```
and
```
blur
```
events with
```
OtpFocusEventArgs
```
```
input
```
event for real-time tracking with
```
OtpInputEventArgs
```
```
valueChanged
```
event for OTP submission with
```
OtpChangedEventArgs
```
Programmatic focus via
```
focusIn()
```
/
```
focusOut()
```
methods
Patterns: conditional submit button, verification feedback

📄 阅读： references/events.md

```
created
```
事件（渲染后初始化）
带
```
OtpFocusEventArgs
```
的
```
focus
```
和
```
blur
```
事件
带
```
OtpInputEventArgs
```
的
```
input
```
事件用于实时跟踪
带
```
OtpChangedEventArgs
```
的
```
valueChanged
```
事件用于OTP提交
通过
```
focusIn()
```
/
```
focusOut()
```
方法程序化聚焦
模式：条件提交按钮、验证反馈

Accessibility

无障碍

📄 Read: references/accessibility.md

WCAG 2.2, Section 508 compliance
WAI-ARIA roles and attributes
Keyboard navigation shortcuts
Per-field
```
ariaLabels
```
configuration
```
htmlAttributes
```
for custom accessibility metadata
RTL support
Axe-core and accessibility-checker validation

📄 阅读： references/accessibility.md

WCAG 2.2、Section 508合规性
WAI-ARIA角色与属性
键盘导航快捷键
每个字段的
```
ariaLabels
```
配置
用于自定义无障碍元数据的
```
htmlAttributes
```
RTL支持
Axe-core和无障碍检查器验证

Full API Reference

完整API参考

📄 Read: references/api.md

All properties with types, defaults, and examples
Methods:
```
destroy()
```
,
```
focusIn()
```
,
```
focusOut()
```
All events and their argument interfaces
Type enumerations:
```
OtpInputType
```
,
```
OtpInputStyle
```
,
```
TextTransform
```

Event argument interfaces:

OtpFocusEventArgs

OtpInputEventArgs

OtpChangedEventArgs

📄 阅读： references/api.md

所有属性及其类型、默认值和示例
方法：
```
destroy()
```
,
```
focusIn()
```
,
```
focusOut()
```
所有事件及其参数接口
类型枚举：
```
OtpInputType
```
,
```
OtpInputStyle
```
,
```
TextTransform
```

事件参数接口：

OtpFocusEventArgs

OtpInputEventArgs

OtpChangedEventArgs

Decision Guide

决策指南

Which type to use?

User enters digits only →
```
type="number"
```
(default)
User enters letters + digits →
```
type="text"
```
Input should be hidden/masked →
```
type="password"
```

Which event to use?

Trigger verification when OTP is fully entered →
```
valueChanged
```
Track partial input in real time →
```
input
```
Know when user clicks into/out of a field →
```
focus
```
/
```
blur
```

Which styling mode?

Standard forms →
```
outlined
```
(default)
Card/dashboard UI →
```
filled
```
Material Design forms →
```
underlined
```

Visual feedback after verification?

Correct OTP → set
```
cssClass="e-success"
```
Wrong OTP → set
```
cssClass="e-error"
```
Pending/caution → set
```
cssClass="e-warning"
```

选择哪种类型？

用户仅输入数字 →
```
type="number"
```
（默认）
用户输入字母+数字 →
```
type="text"
```
输入需要隐藏/掩码 →
```
type="password"
```

选择哪种事件？

OTP完全输入后触发验证 →
```
valueChanged
```
实时跟踪部分输入 →
```
input
```
了解用户何时点击进入/离开字段 →
```
focus
```
/
```
blur
```

选择哪种样式模式？

标准表单 →
```
outlined
```
（默认）
卡片/仪表板UI →
```
filled
```
Material Design表单 →
```
underlined
```

验证后的视觉反馈？

OTP正确 → 设置
```
cssClass="e-success"
```
OTP错误 → 设置
```
cssClass="e-error"
```
待处理/警告 → 设置
```
cssClass="e-warning"
```

TextArea

The TextArea component enables efficient collection of multiline text input in forms and applications. It provides essential features for user feedback, comments, descriptions, and any scenario requiring extended text input.

TextArea组件可在表单和应用中高效收集多行文本输入。它为用户反馈、评论、描述以及任何需要扩展文本输入的场景提供必要功能。

Navigation Guide

导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and npm setup
Vite/React project configuration
Basic TextArea implementation
CSS imports and theming
Getting and setting values with properties, state, and events

📄 阅读： references/getting-started.md

安装与npm配置
Vite/React项目配置
基础TextArea实现
CSS导入与主题
使用属性、状态和事件获取与设置值

Core Features & Content

核心功能与内容

📄 Read: references/value-and-content.md

Setting initial values with property and state
Getting current value from textarea
Value binding patterns
Change detection and state management

📄 阅读： references/value-and-content.md

使用属性和状态设置初始值
从textarea获取当前值
值绑定模式
变更检测与状态管理

Floating Labels & Placeholders

浮动标签与占位符

📄 Read: references/floating-label.md

Floating label types (Auto, Always, Never)
Placeholder behavior during user interaction
Localization with floating labels
Placeholder text translations for different cultures

📄 阅读： references/floating-label.md

浮动标签类型（Auto, Always, Never）
用户交互期间的占位符行为
浮动标签的本地化
不同文化的占位符文本翻译

Adornments (Custom Elements)

装饰元素（自定义元素）

📄 Read: references/adornments.md

Adding icons, buttons, or text before/after textarea
Prepend and append templates
Adornment flow and orientation (horizontal/vertical)
Common use cases: character count, formatting tools, validation icons

📄 阅读： references/adornments.md

在textarea前后添加图标、按钮或文本
前置和后置模板
装饰元素流与方向（水平/垂直）
常见用例：字符计数、格式化工具、验证图标

Form Integration

表单集成

📄 Read: references/form-support.md

HTML form submission with textarea
Name attribute and form data
FormValidator integration for validation rules
Required fields, min/max length constraints
Validation messaging and error states

📄 阅读： references/form-support.md

带textarea的HTML表单提交
name属性与表单数据
FormValidator集成用于验证规则
必填字段、最小/最大长度约束
验证消息与错误状态

Content Constraints

内容约束

📄 Read: references/max-length.md

Enforcing character limits with maxLength
Preventing user input beyond limit
User feedback on character restrictions
Edge cases and best practices

📄 阅读： references/max-length.md

使用maxLength强制字符限制
阻止用户输入超出限制
字符限制的用户反馈
边界情况与最佳实践

Sizing & Dimensions

尺寸与维度

📄 Read: references/rows-columns-sizing.md

Setting visible height with rows property
Setting visible width with cols property
Responsive sizing strategies
Controlling textarea dimensions

📄 阅读： references/rows-columns-sizing.md

使用rows属性设置可见高度
使用cols属性设置可见宽度
响应式尺寸策略
控制textarea维度

Resize Behavior

调整大小行为

📄 Read: references/resize.md

Resize modes: Vertical, Horizontal, Both, None
User-controlled resizing
Width customization
Layout considerations for fixed-size textareas

📄 阅读： references/resize.md

调整大小模式：Vertical, Horizontal, Both, None
用户控制的调整大小
宽度定制
固定尺寸textarea的布局考虑

Styling & Appearance

样式与外观

📄 Read: references/styling-appearance.md

Size classes (e-small, e-bigger)
Filled and outline appearance modes
Custom CSS with cssClass property
Disabled and read-only states
Validation state styling (success, warning, error)
Clear button configuration
Color customization and rounded corners

📄 阅读： references/styling-appearance.md

尺寸类（e-small, e-bigger）
填充与轮廓外观模式
使用cssClass属性的自定义CSS
禁用与只读状态
验证状态样式（success, warning, error）
清除按钮配置
颜色定制与圆角

Events & User Interaction

事件与用户交互

📄 Read: references/events.md

created: Initialization event
input: Real-time value change detection
change: Value change with focus-out
focus: Focus gained
blur: Focus lost
destroyed: Component cleanup
Event args and usage patterns

📄 阅读： references/events.md

created: 初始化事件
input: 实时值变更检测
change: 失焦时值变更
focus: 获得焦点
blur: 失去焦点
destroyed: 组件清理
事件参数与使用模式

Methods & Programmatic Control

方法与程序化控制

📄 Read: references/methods.md

focusIn(): Programmatically set focus
focusOut(): Remove focus
getPersistData(): Retrieve persistence state
addAttributes(): Add HTML attributes dynamically
removeAttributes(): Remove HTML attributes
destroy(): Clean up component

📄 阅读： references/methods.md

focusIn(): 程序化设置焦点
focusOut(): 移除焦点
getPersistData(): 获取持久化状态
addAttributes(): 动态添加HTML属性
removeAttributes(): 移除HTML属性
destroy(): 清理组件

Complete API Reference

完整API参考

📄 Read: references/api.md

All properties with descriptions and defaults
All methods with parameters and return types
All events with arg types
Type definitions and enums
Usage examples for each API

📄 阅读： references/api.md

所有属性及其描述与默认值
所有方法及其参数与返回类型
所有事件及其参数类型
类型定义与枚举
每个API的使用示例

Quick Start

快速入门

typescript

import { TextAreaComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';
import './App.css';

function App() {
  const [textValue, setTextValue] = React.useState('');

  const handleChange = (args) => {
    console.log('TextArea value changed:', args.value);
  };

  return (
    <div className='wrap'>
      <TextAreaComponent
        id='default'
        placeholder='Enter your comments'
        value={textValue}
        change={handleChange}
        floatLabelType='Auto'
        rows={5}
        cols={40}
      />
    </div>
  );
}

export default App;

typescript

import { TextAreaComponent } from '@syncfusion/ej2-react-inputs';
import * as React from 'react';
import './App.css';

function App() {
  const [textValue, setTextValue] = React.useState('');

  const handleChange = (args) => {
    console.log('TextArea值变更:', args.value);
  };

  return (
    <div className='wrap'>
      <TextAreaComponent
        id='default'
        placeholder='输入您的评论'
        value={textValue}
        change={handleChange}
        floatLabelType='Auto'
        rows={5}
        cols={40}
      />
    </div>
  );
}

export default App;

Common Patterns

常见模式

Pattern 1: Form with Validation

模式1：带验证的表单

typescript

<TextAreaComponent
  name='comments'
  placeholder='Your feedback'
  floatLabelType='Auto'
  required={true}
  maxLength={500}
  showClearButton={true}
/>

typescript

<TextAreaComponent
  name='comments'
  placeholder='您的反馈'
  floatLabelType='Auto'
  required={true}
  maxLength={500}
  showClearButton={true}
/>

Pattern 2: Controlled Component with State

模式2：带状态的受控组件

typescript

const [value, setValue] = React.useState('');

<TextAreaComponent
  value={value}
  input={(args) => setValue(args.value)}
/>

typescript

const [value, setValue] = React.useState('');

<TextAreaComponent
  value={value}
  input={(args) => setValue(args.value)}
/>

Pattern 3: Styled with Custom CSS

模式3：带自定义CSS的样式化组件

typescript

<TextAreaComponent
  placeholder='Enter text'
  cssClass='e-outline e-small'
  floatLabelType='Auto'
/>

typescript

<TextAreaComponent
  placeholder='输入文本'
  cssClass='e-outline e-small'
  floatLabelType='Auto'
/>

Pattern 4: Disabled & Read-Only States

模式4：禁用与只读状态

typescript

<TextAreaComponent placeholder='Disabled' enabled={false} />
<TextAreaComponent placeholder='Read-only' readonly={true} />

typescript

<TextAreaComponent placeholder='禁用' enabled={false} />
<TextAreaComponent placeholder='只读' readonly={true} />

Pattern 5: With Adornments

模式5：带装饰元素的组件

typescript

<TextAreaComponent
  placeholder='Message'
  prependTemplate={() => <span className='icon'>📝</span>}
  appendTemplate={() => <button>Send</button>}
/>

typescript

<TextAreaComponent
  placeholder='消息'
  prependTemplate={() => <span className='icon'>📝</span>}
  appendTemplate={() => <button>发送</button>}
/>

Key Props Summary

关键属性摘要

Prop	Purpose	Common Values
`value`	Set/get textarea content	string
`placeholder`	Hint text	string
`rows`	Visible height in lines	3-10
`cols`	Visible width in characters	30-80
`floatLabelType`	Floating behavior	'Auto', 'Always', 'Never'
`maxLength`	Character limit	number
`resizeMode`	User resizing	'Both', 'Vertical', 'Horizontal', 'None'
`enabled`	Enable/disable input	boolean
`readonly`	Read-only mode	boolean
`cssClass`	Custom styling	'e-outline', 'e-small', 'e-filled'
`showClearButton`	Display clear button	boolean

属性	用途	常见值
`value`	设置/获取textarea内容	string
`placeholder`	提示文本	string
`rows`	可见高度（行数）	3-10
`cols`	可见宽度（字符数）	30-80
`floatLabelType`	浮动行为	'Auto', 'Always', 'Never'
`maxLength`	字符限制	number
`resizeMode`	用户调整大小	'Both', 'Vertical', 'Horizontal', 'None'
`enabled`	启用/禁用输入	boolean
`readonly`	只读模式	boolean
`cssClass`	自定义样式	'e-outline', 'e-small', 'e-filled'
`showClearButton`	显示清除按钮	boolean

Syncfusion React Slider (RangeSlider)

A comprehensive guide for implementing the Syncfusion Essential JS 2

SliderComponent

in React applications. Supports single-value (

Default

), min-range fill (

MinRange

), and dual-handle range selection (

Range

) with tooltips, ticks, limits, color ranges, custom values, formatting, accessibility, events, and more.

Package:

@syncfusion/ej2-react-inputs

一份关于在React应用中实现Syncfusion Essential JS 2

SliderComponent

的综合指南。支持单值（

Default

）、最小范围填充（

MinRange

）和双滑块范围选择（

Range

），具备工具提示、刻度、限制、颜色范围、自定义值、格式化、无障碍、事件等功能。

包：

@syncfusion/ej2-react-inputs

Navigation Guide

导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and package setup
Basic implementation of three slider types
CSS imports and theme setup
Minimal working example
Initial configuration

📄 阅读： references/getting-started.md

安装与包配置
三种滑块类型的基础实现
CSS导入与主题配置
最小化可用示例
初始配置

Types and Orientation

类型与方向

📄 Read: references/types-and-orientation.md

Three slider types: Default, MinRange, Range
Understanding shadow/fill behavior
Horizontal vs vertical orientation
Type selection guide
Code examples for each type

📄 阅读： references/types-and-orientation.md

三种滑块类型：Default, MinRange, Range
理解阴影/填充行为
水平 vs 垂直方向
类型选择指南
每种类型的代码示例

Tooltips and Ticks

工具提示与刻度

📄 Read: references/tooltips-and-ticks.md

Tooltip configuration and placement
Tooltip visibility modes (Always, Focus, Click)
Tick marks and scale display
largeStep and smallStep configuration
Small tick visibility
Combined tooltip + ticks examples

📄 阅读： references/tooltips-and-ticks.md

工具提示配置与位置
工具提示可见性模式（Always, Focus, Click）
刻度标记与刻度显示
largeStep和smallStep配置
小刻度可见性
工具提示+刻度组合示例

Formatting and Limits

格式化与限制

📄 Read: references/formatting-and-limits.md

Value formatting (currency, percentages, custom formats)
Using the format API
Slider limits and restricted ranges
Handle locking (start/end fixed)
Min/max bounds per handle
Edge cases and constraint handling

📄 阅读： references/formatting-and-limits.md

值格式化（货币、百分比、自定义格式）
使用format API
滑块限制与受限范围
滑块锁定（起始/结束固定）
每个滑块的最小/最大边界
边界情况与约束处理

Styling and Customization

样式与定制

📄 Read: references/styling.md

CSS selectors for track, handle, limits, ticks, buttons
Customizing track color and height
Handle styling (color, border, size)
Theme integration and built-in themes
CSS variable customization
Advanced styling patterns

📄 阅读： references/styling.md

轨道、滑块、限制、刻度、按钮的CSS选择器
自定义轨道颜色与高度
滑块样式（颜色、边框、尺寸）
主题集成与内置主题
CSS变量定制
高级样式模式

Accessibility

无障碍

📄 Read: references/accessibility.md

WCAG 2.2 and Section 508 compliance

WAI-ARIA attributes and roles (

role="slider"

aria-valuemin

aria-valuemax

aria-valuenow

aria-orientation

)

Keyboard navigation (Arrow keys, Home, End, Page Up/Down)
Screen reader support and
```
aria-live
```
regions
Focus management and color contrast requirements
Mobile touch accessibility

📄 阅读： references/accessibility.md

WCAG 2.2和Section 508合规性

WAI-ARIA属性与角色（

role="slider"

aria-valuemin

aria-valuemax

aria-valuenow

aria-orientation

）

键盘导航（箭头键、Home、End、Page Up/Down）
屏幕阅读器支持与
```
aria-live
```
区域
焦点管理与颜色对比度要求
移动触摸无障碍

Color Range

颜色范围

📄 Read: references/color-range.md

```
colorRange
```
property and
```
ColorRangeDataModel
```
interface
Three-zone and multi-zone patterns (red/amber/green)
Color range with
```
Range
```
type (dual handles)
Dynamic color zones based on runtime data
Real-world: battery, risk, performance, score patterns
Combining
```
colorRange
```
with
```
limits
```
,
```
ticks
```
, and
```
tooltip
```

📄 阅读： references/color-range.md

```
colorRange
```
属性与
```
ColorRangeDataModel
```
接口
三区与多区模式（红/琥珀/绿）
带
```
Range
```
类型（双滑块）的颜色范围
基于运行时数据的动态颜色区域
实际场景：电池、风险、性能、评分模式
结合
```
colorRange
```
与
```
limits
```
,
```
ticks
```
, 和
```
tooltip
```

Events and Methods

事件与方法

📄 Read: references/events-and-methods.md

```
change
```
event — continuous value updates while dragging
```
changed
```
event — final committed value on drag release
```
created
```
event — post-render initialization
```
renderingTicks
```
— customize tick label text per tick
```
renderedTicks
```
— post-process tick DOM after all ticks render
```
tooltipChange
```
— customize tooltip display text
```
reposition()
```
method — when and how to call
```
destroy()
```
method — cleanup and removal
React
```
ref
```
patterns for programmatic control
Common patterns: API sync, conditional logic, live preview

📄 阅读： references/events-and-methods.md

```
change
```
事件——拖拽时持续更新值
```
changed
```
事件——拖拽释放时的最终确认值
```
created
```
事件——渲染后初始化
```
renderingTicks
```
——自定义每个刻度的标签文本
```
renderedTicks
```
——所有刻度渲染后处理刻度DOM
```
tooltipChange
```
——自定义工具提示显示文本
```
reposition()
```
方法——调用时机与方式
```
destroy()
```
方法——清理与移除
用于程序化控制的React
```
ref
```
模式
常见模式：API同步、条件逻辑、实时预览

API Reference

API参考

📄 Read: references/api-reference.md

All official

SliderComponent

properties:

value

type

min

max

step

orientation

ticks

tooltip

limits

colorRange

customValues

showButtons

enableAnimation

enabled

readonly

cssClass

width

enableRtl

enablePersistence

enableHtmlSanitizer

locale

Official methods:
```
reposition()
```
,
```
destroy()
```

All official events with correct argument interfaces:

change

changed

created

renderingTicks

renderedTicks

tooltipChange

Interface:

TicksDataModel

—

placement

(

'Before'

'After'

'Both'

'None'

largeStep

smallStep

showSmallTicks

format

Interface:

TooltipDataModel

—

isVisible

placement

showOn

(

'Always'

'Focus'

'Click'

format

cssClass

Interface:

LimitDataModel

—

enabled

minStart

minEnd

maxStart

maxEnd

startHandleFixed

endHandleFixed

Interface:
```
ColorRangeDataModel
```
—
```
color
```
,
```
start
```
,
```
end
```

Interface:

SliderChangeEventArgs

—

value

previousValue

action

isInteracted

text

Interface:
```
SliderTickEventArgs
```
—
```
value
```
,
```
text
```
,
```
tickElement
```

Interface:

SliderTickRenderedEventArgs

—

ticksWrapper

tickElements

Interface:
```
SliderTooltipEventArgs
```
—
```
value
```
,
```
text
```
Enum:
```
SliderType
```
(
```
'Default'
```
|
```
'MinRange'
```
|
```
'Range'
```
)
Enum:
```
SliderOrientation
```
(
```
'Horizontal'
```
|
```
'Vertical'
```
)

📄 阅读： references/api-reference.md

所有官方

SliderComponent

属性：

value

type

min

max

step

orientation

ticks

tooltip

limits

colorRange

customValues

showButtons

enableAnimation

enabled

readonly

cssClass

width

enableRtl

enablePersistence

enableHtmlSanitizer

locale

官方方法：
```
reposition()
```
,
```
destroy()
```

所有官方事件及其正确参数接口：

change

changed

created

renderingTicks

renderedTicks

tooltipChange

接口：

TicksDataModel

——

placement

（

'Before'

'After'

'Both'

'None'

）,

largeStep

smallStep

showSmallTicks

format

接口：

TooltipDataModel

——

isVisible

placement

showOn

（

'Always'

'Focus'

'Click'

）,

format

cssClass

接口：

LimitDataModel

——

enabled

minStart

minEnd

maxStart

maxEnd

startHandleFixed

endHandleFixed

接口：
```
ColorRangeDataModel
```
——
```
color
```
,
```
start
```
,
```
end
```

接口：

SliderChangeEventArgs

——

value

previousValue

action

isInteracted

text

接口：
```
SliderTickEventArgs
```
——
```
value
```
,
```
text
```
,
```
tickElement
```

接口：

SliderTickRenderedEventArgs

——

ticksWrapper

tickElements

接口：
```
SliderTooltipEventArgs
```
——
```
value
```
,
```
text
```
枚举：
```
SliderType
```
（
```
'Default'
```
|
```
'MinRange'
```
|
```
'Range'
```
）
枚举：
```
SliderOrientation
```
（
```
'Horizontal'
```
|
```
'Vertical'
```
）

Quick Start

快速入门

Basic Single Value Slider

基础单值滑块

tsx

import React from 'react';
import { SliderComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function App() {
  return (
    <div>
      <SliderComponent 
        id="slider" 
        value={30}
        min={0}
        max={100}
      />
    </div>
  );
}
export default App;

tsx

import React from 'react';
import { SliderComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function App() {
  return (
    <div>
      <SliderComponent 
        id="slider" 
        value={30}
        min={0}
        max={100}
      />
    </div>
  );
}
export default App;

Range Slider (Two Handles)

范围滑块（双滑块）

tsx

import React from 'react';
import { SliderComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function App() {
  const [range, setRange] = React.useState([30, 70]);

  return (
    <div>
      <SliderComponent 
        id="range-slider" 
        type="Range"
        value={range}
        change={(e) => setRange(e.value)}
        min={0}
        max={100}
      />
    </div>
  );
}
export default App;

tsx

import React from 'react';
import { SliderComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function App() {
  const [range, setRange] = React.useState([30, 70]);

  return (
    <div>
      <SliderComponent 
        id="range-slider" 
        type="Range"
        value={range}
        change={(e) => setRange(e.value)}
        min={0}
        max={100}
      />
    </div>
  );
}
export default App;

Price Range Selector

价格范围选择器

tsx

import React from 'react';
import { SliderComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function PriceRangeSelector() {
  const [priceRange, setPriceRange] = React.useState([100, 500]);
  
  const tooltip = {
    placement: 'Before',
    isVisible: true,
    format: 'C2'  // Currency format
  };

  return (
    <div>
      <h3>Price Range: ${priceRange[0]} - ${priceRange[1]}</h3>
      <SliderComponent 
        id="price-slider"
        type="Range"
        value={priceRange}
        change={(e) => setPriceRange(e.value)}
        min={0}
        max={1000}
        step={10}
        tooltip={tooltip}
      />
    </div>
  );
}
export default PriceRangeSelector;

tsx

import React from 'react';
import { SliderComponent } from '@syncfusion/ej2-react-inputs';
import '@syncfusion/ej2-react-inputs/styles/material.css';

function PriceRangeSelector() {
  const [priceRange, setPriceRange] = React.useState([100, 500]);
  
  const tooltip = {
    placement: 'Before',
    isVisible: true,
    format: 'C2'  // 货币格式
  };

  return (
    <div>
      <h3>价格范围: ${priceRange[0]} - ${priceRange[1]}</h3>
      <SliderComponent 
        id="price-slider"
        type="Range"
        value={priceRange}
        change={(e) => setPriceRange(e.value)}
        min={0}
        max={1000}
        step={10}
        tooltip={tooltip}
      />
    </div>
  );
}
export default PriceRangeSelector;

Common Patterns

常见模式

Pattern 1: Single Value with Ticks

模式1：带刻度的单值滑块

Use Default type for simple numeric selection with visual scale.

tsx

<SliderComponent
  id="default-slider"
  value={40}
  min={0}
  max={100}
  step={5}
  ticks={{
    placement: 'After',
    largeStep: 20,
    smallStep: 5,
    showSmallTicks: true
  }}
/>

使用Default类型实现带视觉刻度的简单数值选择。

tsx

<SliderComponent
  id="default-slider"
  value={40}
  min={0}
  max={100}
  step={5}
  ticks={{
    placement: 'After',
    largeStep: 20,
    smallStep: 5,
    showSmallTicks: true
  }}
/>

Pattern 2: Range with Fixed Limits

模式2：带固定限制的范围滑块

Use Range type with limits to restrict handle movement to specific areas.

tsx

<SliderComponent
  id="limited-range"
  type="Range"
  value={[25, 75]}
  limits={{
    enabled: true,
    minStart: 10,
    minEnd: 40,
    maxStart: 60,
    maxEnd: 90
  }}
  tooltip={{ isVisible: true }}
/>

使用Range类型并设置限制，将滑块移动限制到特定区域。

tsx

<SliderComponent
  id="limited-range"
  type="Range"
  value={[25, 75]}
  limits={{
    enabled: true,
    minStart: 10,
    minEnd: 40,
    maxStart: 60,
    maxEnd: 90
  }}
  tooltip={{ isVisible: true }}
/>

Pattern 3: Formatted Values (Currency)

模式3：格式化值（货币）

Display values as currency using format API.

tsx

<SliderComponent
  id="currency-slider"
  type="Range"
  value={[1000, 5000]}
  min={0}
  max={10000}
  step={100}
  tooltip={{
    isVisible: true,
    format: 'C0'  // Currency without decimals
  }}
  ticks={{
    placement: 'After',
    largeStep: 2000,
    format: 'C0'
  }}
/>

使用format API将值显示为货币。

tsx

<SliderComponent
  id="currency-slider"
  type="Range"
  value={[1000, 5000]}
  min={0}
  max={10000}
  step={100}
  tooltip={{
    isVisible: true,
    format: 'C0'  // 无小数的货币格式
  }}
  ticks={{
    placement: 'After',
    largeStep: 2000,
    format: 'C0'
  }}
/>

Pattern 4: Vertical Orientation

模式4：垂直方向

Display slider vertically for space-constrained layouts.

tsx

<div style={{ height: '300px', width: '100px' }}>
  <SliderComponent
    id="vertical-slider"
    value={50}
    orientation="Vertical"
    tooltip={{ isVisible: true }}
  />
</div>

在空间受限的布局中垂直显示滑块。

tsx

<div style={{ height: '300px', width: '100px' }}>
  <SliderComponent
    id="vertical-slider"
    value={50}
    orientation="Vertical"
    tooltip={{ isVisible: true }}
  />
</div>

Pattern 5: With Increment/Decrement Buttons

模式5：带增减按钮的滑块

Add buttons to manually adjust slider values.

tsx

<SliderComponent
  id="button-slider"
  type="Range"
  value={[30, 70]}
  showButtons={true}
  tooltip={{ isVisible: true }}
/>

添加按钮手动调整滑块值。

tsx

<SliderComponent
  id="button-slider"
  type="Range"
  value={[30, 70]}
  showButtons={true}
  tooltip={{ isVisible: true }}
/>

Pattern 6: Color Range (Zones)

模式6：颜色范围（区域）

Paint distinct color sections on the slider track using

colorRange

tsx

import { ColorRangeDataModel } from '@syncfusion/ej2-react-inputs';

const colorRange: ColorRangeDataModel[] = [
  { color: '#ff4040', start: 0,  end: 33  },   // Low zone — red
  { color: '#ffb300', start: 34, end: 66  },   // Mid zone — amber
  { color: '#00c853', start: 67, end: 100 }    // High zone — green
];

<SliderComponent
  id="color-slider"
  type="MinRange"
  value={50}
  colorRange={colorRange}
  tooltip={{ isVisible: true, showOn: 'Always' }}
/>

使用

colorRange

在滑块轨道上绘制不同颜色的区域。

tsx

import { ColorRangeDataModel } from '@syncfusion/ej2-react-inputs';

const colorRange: ColorRangeDataModel[] = [
  { color: '#ff4040', start: 0,  end: 33  },   // 低区域 — 红色
  { color: '#ffb300', start: 34, end: 66  },   // 中区域 — 琥珀色
  { color: '#00c853', start: 67, end: 100 }    // 高区域 — 绿色
];

<SliderComponent
  id="color-slider"
  type="MinRange"
  value={50}
  colorRange={colorRange}
  tooltip={{ isVisible: true, showOn: 'Always' }}
/>

Pattern 7: Custom Value Scale

模式7：自定义值刻度

Use non-numeric labels as slider values with

customValues

tsx

<SliderComponent
  id="size-slider"
  customValues={['XS', 'S', 'M', 'L', 'XL', 'XXL']}
  value="M"
  tooltip={{ isVisible: true }}
/>

使用非数字标签作为滑块值（

customValues

）。

tsx

<SliderComponent
  id="size-slider"
  customValues={['XS', 'S', 'M', 'L', 'XL', 'XXL']}
  value="M"
  tooltip={{ isVisible: true }}
/>

Pattern 8: Read-Only Display

模式8：只读显示

Show a locked slider for informational display.

tsx

<SliderComponent
  id="status-slider"
  type="MinRange"
  value={65}
  min={0}
  max={100}
  readonly={true}
  tooltip={{ isVisible: true, showOn: 'Always' }}
  ticks={{ placement: 'After', largeStep: 20 }}
/>

显示锁定的滑块用于信息展示。

tsx

<SliderComponent
  id="status-slider"
  type="MinRange"
  value={65}
  min={0}
  max={100}
  readonly={true}
  tooltip={{ isVisible: true, showOn: 'Always' }}
  ticks={{ placement: 'After', largeStep: 20 }}
/>

Key Properties

关键属性

Property	Type	Default	Purpose
`value`	`number \| number[]`	`null`	Single value or `[start, end]` array for Range type
`type`	`'Default' \| 'MinRange' \| 'Range'`	`'Default'`	Slider mode
`min`	`number`	`0`	Minimum selectable value
`max`	`number`	`100`	Maximum selectable value
`step`	`number`	`1`	Value increment/decrement per step
`orientation`	`'Horizontal' \| 'Vertical'`	`'Horizontal'`	Slider direction
`tooltip`	`TooltipDataModel`	`{ isVisible: false }`	Tooltip configuration
`ticks`	`TicksDataModel`	`{ placement: 'before' }`	Tick marks configuration
`limits`	`LimitDataModel`	`{ enabled: false }`	Thumb movement restrictions
`colorRange`	`ColorRangeDataModel[]`	`[]`	Color zones on the track
`customValues`	`string[] \| number[]`	`null`	Custom value scale (ignores min/max/step)
`showButtons`	`boolean`	`false`	Show +/- increment/decrement buttons
`enabled`	`boolean`	`true`	Enable or disable the slider
`readonly`	`boolean`	`false`	Read-only display mode
`enableRtl`	`boolean`	`false`	Right-to-left layout
`width`	`number \| string`	`null`	Slider element width
`cssClass`	`string`	`''`	Custom CSS classes on root element

属性	类型	默认值	用途
`value`	`number \| number[]`	`null`	单值或Range类型的 `[start, end]` 数组
`type`	`'Default' \| 'MinRange' \| 'Range'`	`'Default'`	滑块模式
`min`	`number`	`0`	最小可选值
`max`	`number`	`100`	最大可选值
`step`	`number`	`1`	每次增量/减量的值
`orientation`	`'Horizontal' \| 'Vertical'`	`'Horizontal'`	滑块方向
`tooltip`	`TooltipDataModel`	`{ isVisible: false }`	工具提示配置
`ticks`	`TicksDataModel`	`{ placement: 'before' }`	刻度标记配置
`limits`	`LimitDataModel`	`{ enabled: false }`	滑块移动限制
`colorRange`	`ColorRangeDataModel[]`	`[]`	轨道上的颜色区域
`customValues`	`string[] \| number[]`	`null`	自定义值刻度（忽略min/max/step）
`showButtons`	`boolean`	`false`	显示+/-增减按钮
`enabled`	`boolean`	`true`	启用或禁用滑块
`readonly`	`boolean`	`false`	只读显示模式
`enableRtl`	`boolean`	`false`	从右到左布局
`width`	`number \| string`	`null`	滑块元素宽度
`cssClass`	`string`	`''`	根元素上的自定义CSS类

Type Comparison

类型对比

Type	Handles	Fill Behavior	Use Case
Default	1	No fill	Simple numeric selection
MinRange	1	Fill from min	Visual progress/level indicator
Range	2	Fill between handles	Min/max range selection

类型	滑块数量	填充行为	用例
Default	1	无填充	简单数值选择
MinRange	1	从最小值开始填充	视觉进度/级别指示器
Range	2	在滑块之间填充	最小/最大范围选择

Common Use Cases

常见用例

Budget Range Selector

预算范围选择器

Select min and max budget with step increments and currency formatting. → Use

type="Range"

step={50}

, format

'C0'

, tooltip enabled

选择最小和最大预算，带步长增量和货币格式化。 → 使用

type="Range"

step={50}

, 格式

'C0'

, 启用工具提示

Time Range Picker

时间范围选择器

Select time window (hours, minutes, days). → Use

type="Range"

, custom formatting via

renderingTicks

event

选择时间窗口（小时、分钟、天）。 → 使用

type="Range"

, 通过

renderingTicks

事件自定义格式化

Volume/Brightness Control

音量/亮度控制

Single handle adjustment with immediate feedback. → Use

type="Default"

, no ticks, always-visible tooltip

单滑块调整，即时反馈。 → 使用

type="Default"

, 无刻度，始终显示工具提示

Score/Rating Range

评分/评级范围

MinRange mode with shadow showing current level. → Use

type="MinRange"

min={0}

max={10}

, step-based

MinRange模式，阴影显示当前级别。 → 使用

type="MinRange"

min={0}

max={10}

, 基于步长

Product Filter

产品筛选

Multiple product categories with price ranges. → Use

type="Range"

, limits for each category, event handlers

多个产品类别，带价格范围。 → 使用

type="Range"

, 每个类别的限制，事件处理程序

Events

事件

Event	Trigger	Usage
`created`	Component created and rendered	One-time setup operations
`change`	Value changing while dragging	Real-time feedback (continuous)
`changed`	Drag complete (thumb released)	Capture final committed value
`tooltipChange`	Tooltip about to render	Custom tooltip text formatting
`renderingTicks`	Each tick being rendered	Custom tick label text
`renderedTicks`	All ticks rendered	Post-process tick DOM elements

⚠️ Note: The official event for continuous updates while dragging is
change
, not
changing
. The event fired after drag completes is
changed
. Do NOT use
onChange
prop (that is a React native input prop). Use
change
and
changed
directly.

事件	触发时机	用途
`created`	组件创建并渲染完成	一次性设置操作
`change`	拖拽时值变化	实时反馈（持续）
`changed`	拖拽完成（滑块释放）	捕获最终确认值
`tooltipChange`	工具提示即将渲染	自定义工具提示文本格式化
`renderingTicks`	每个刻度正在渲染	自定义刻度标签文本
`renderedTicks`	所有刻度渲染完成	处理刻度DOM元素

⚠️ 注意： 拖拽时持续更新的官方事件是
change
，而非
changing
。拖拽完成后触发的事件是
changed
。请勿使用
onChange
属性（这是React原生输入属性）。直接使用
change
和
changed
。

Troubleshooting Quick Links

故障排除快速链接

Component not displaying? → Check CSS imports and theme in getting-started.md

Values not updating? → Use

change

(continuous) or

changed

(on release) events — NOT

onChange

Formatting not working? → See format API examples in formatting-and-limits.md

Accessibility issues? → Refer to accessibility.md for ARIA and keyboard support

Vertical slider not rendering? → Wrap in a container with explicit

height

(e.g.,

style={{ height: '300px' }}

)

Range type with single value? → Always pass

value={[start, end]}

array for

type="Range"

Color zones not showing? → Check

colorRange

array has valid

start

end

color

properties

组件未显示？ → 查看getting-started.md中的CSS导入和主题

值未更新？ → 使用

change

（持续）或

changed

（释放时）事件——不要使用

onChange

格式化不生效？ → 查看formatting-and-limits.md中的format API示例

无障碍问题？ → 参考accessibility.md获取ARIA和键盘支持

垂直滑块未渲染？ → 将其包裹在具有明确

height

的容器中（如

style={{ height: '300px' }}

）

Range类型使用单值？ →

type="Range"

时始终传递

value={[start, end]}

数组

颜色区域未显示？ → 检查

colorRange

数组是否有有效的

start

end

color

属性

Next Steps

下一步

Choose your slider type based on use case (
```
Default
```
,
```
MinRange
```
, or
```
Range
```
)
Read getting-started.md for installation
Navigate to specific reference for your feature needs
Test with examples from reference files
Customize styling using styling.md
Ensure accessibility following accessibility.md
Verify all API usage against api-reference.md

⚠️ Critical: Only use APIs explicitly listed in references/api-reference.md. Do not reference
onChange
(use
change
/
changed
),
toggle()
,
open()
,
close()
, or any undocumented methods.

根据用例选择滑块类型（
```
Default
```
,
```
MinRange
```
或
```
Range
```
）
阅读getting-started.md进行安装
根据功能需求导航到特定参考文档
使用参考文件中的示例进行测试
使用styling.md自定义样式
根据accessibility.md确保无障碍支持
根据api-reference.md验证所有API使用

⚠️ 重要提示： 仅使用references/api-reference.md中明确列出的API。请勿使用
onChange
（使用
change
/
changed
）、
toggle()
、
open()
、
close()
或任何未记录的方法。