syncfusion-react-inputs

实现 Syncfusion React 输入组件

Uploader

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

导航指南

🛑 Agentic 使用： 请勿自主执行多个步骤。每次操作（安装、运行、创建文件）前都要向用户确认。

快速入门

📄 阅读： references/getting-started.md

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

异步上传

📄 阅读： references/async-upload.md

• 使用 saveUrl 和 removeUrl 配置 asyncSettings
• 上传多个或单个文件（multiple）
• 自动上传或手动上传（autoUpload）
• 顺序上传（sequentialUpload）
• 预加载文件（files 属性）
• 通过 uploading/removing 事件添加自定义 HTTP 标头
• 服务端保存/移除操作示例

分块上传

📄 阅读： references/chunk-upload.md

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

验证

📄 阅读： references/validation.md

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

文件来源

📄 阅读： references/file-source.md

• 粘贴剪贴板内容以上传
• 上传目录/文件夹（directoryUpload）
• 使用自定义放置区域拖放（dropArea）
• 自定义放置区域外观

模板和自定义

📄 阅读： references/template-customization.md

• 文件列表的 template 属性
• 使用 showFileList: false 创建自定义上传界面
• 自定义操作按钮（buttons 属性）
• 自定义进度条
• 隐藏默认放置区域
• 覆盖样式和外观

高级操作场景

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

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

API 参考

📄 阅读： 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）

快速入门示例

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}
    />
  );
}

常见模式

验证后自动上传

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

使用自定义按钮手动上传

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

大文件分块上传

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

关键决策指南

需求	属性/事件
服务端 URL	asyncSettings.saveUrl + asyncSettings.removeUrl
自动或手动上传	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

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

文档与导航指南

🛑 **Agent 自主使用：**请勿自主执行多个步骤。每次操作（安装、运行、创建文件）前都要与用户确认。

当用户需要 NumericTextBox 方面的帮助时，请引导他们查看相应参考资料：

入门指南

📄 阅读： references/getting-started.md

• 安装和软件包设置
• CSS 导入和主题
• React 组件导入和基本 JSX
• 创建第一个 NumericTextBox
• 运行应用程序

格式与验证

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

• 标准格式说明符（货币、百分比、数字、科学计数法）
• 使用 # 和 0 模式自定义数字格式
• 使用 min 和 max 属性进行范围验证
• 使用 strictMode 强制执行有效范围
• 真实场景中的格式示例

微调按钮与步长控制

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

• 启用/禁用微调按钮箭头
• 用于设置增量值的 Step 属性
• 自定义微调按钮的外观和行为
• 控制步长增量的精度
• 键盘快捷键（向上/向下箭头）

装饰元素与样式

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

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

精度与小数

📄 阅读： references/precision-decimals.md

• 用于控制小数位数的 decimals 属性
• 用于实时精度验证的 validateDecimalOnType
• 在显示中保留末尾的零
• 舍入行为和边界情况
• 输入与显示时的精度

双向绑定与表单

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

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

国际化与无障碍

📄 阅读： references/globalization-accessibility.md

• 国际化和区域设置支持
• 从右到左（RTL）语言支持
• 符合 WCAG 2.2 无障碍标准
• 键盘导航和快捷键
• 使用 ARIA 属性支持屏幕阅读器
• 焦点管理和颜色对比度

API 参考

📄 阅读： references/api.md

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

快速入门示例

以下是一个最简可运行示例，帮助你快速上手：

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

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

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

要点：

• 从 @syncfusion/ej2-react-inputs 导入 NumericTextBoxComponent
• 导入所需的 CSS 主题（本例中为 material3）
• 使用 value 属性设置当前数值
• 使用 onChange 事件更新 React 状态
• 添加 min、max、step 进行验证和控制

常见模式

1. 货币输入

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

2. 百分比输入

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

3. 仅限整数的输入

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

4. 带验证的范围限制

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

5. 带标签的表单字段

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

关键属性参考

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

常见用例

1. 购物车 — 数量输入

• 仅限整数，min=1，step=1，使用微调按钮轻松调整

2. 价格计算器 — 货币字段

• format="c2"，min=0，前缀="$"，两位小数

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

• min=0，max=100，strictMode=true，不显示小数

4. 折扣百分比

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

5. 测量值输入

• decimals=2，后缀=" cm"，min=0，使用微调按钮进行精确调整

6. 财务表单

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

后续步骤

1. 软件包要求： 软件包 @syncfusion/ej2-react-inputs、@syncfusion/ej2-base 和 @syncfusion/ej2-buttons 必须包含在项目的 package.json 中。请确认这些软件包已安装，并且锁文件（例如 package-lock.json 或 yarn.lock）已固定其版本，以确保供应链完整性。添加软件包时，请使用明确的版本范围，例如 @syncfusion/ej2-react-inputs@^27.x.x，避免依赖版本未固定的风险。
2. 入门参考： 有关安装详情和基本设置，请参阅 references/getting-started.md。
3. 选择参考内容： 根据使用场景（格式化、验证、表单等），转到上方相关的参考部分。
4. 查看示例： 每个参考部分都包含可直接使用的代码示例，可根据需求进行调整。
5. 自定义： 修改示例，使其适用于具体的使用场景和应用需求。

---

如需详细的实施指南，请转到上方相应的参考文件。

TextBox

TextBox 组件是一种轻量级输入控件，可捕获用户输入的文本，并支持浮动标签、验证状态、图标和高级功能。本指南将带你了解如何在 React 应用中实现、配置和自定义 TextBox 组件。

导航指南

🛑 Agent 使用须知： 请勿自主执行多个步骤。每次操作（安装、运行、创建文件）前都要向用户确认。

入门

📄 阅读： references/getting-started.md

• 用于 React 开发的 Vite 设置
• 安装 @syncfusion/ej2-react-inputs 软件包 🛑 停止 — 请勿自主安装软件包。请让用户运行：npm install @syncfusion/ej2-react-inputs。固定具体版本（例如 @syncfusion/[email protected]），并使用 npm audit 验证
• 添加 CSS 导入和主题
• 创建第一个 TextBox 组件
• 添加图标和浮动标签
• 运行开发服务器 🛑 停止 — 请勿自主启动开发服务器。请让用户运行：npm run dev

功能和分组

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

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

样式和尺寸

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

• 三种预定义尺寸：Normal、Small（e-small）、Large（e-bigger）
• 通过 cssClass 属性应用尺寸类
• 使用 e-corner CSS 类设置圆角
• 自定义 TextBox 包装器和浮动标签的 CSS
• 自定义 CSS 类和主题
• 响应式设计模式

多行 TextBox

📄 阅读： references/multiline-textbox.md

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

验证和状态

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

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

高级功能

📄 阅读： references/advanced-features.md

• 装饰项：prependTemplate 和 appendTemplate 属性
• 交互式装饰项（密码切换按钮、删除按钮）
• 使用 hooks 的 React 函数组件
• 与 useState、useEffect、useRef、useReducer 集成
• 事件处理（created、input、change 事件）
• 表单验证模式

无障碍访问与迁移

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

• 符合 WCAG 2.2、Section 508 和 WAI-ARIA 标准
• 屏幕阅读器支持和 ARIA 属性
• 通过 enableRtl 属性支持从右到左（RTL）布局
• 键盘导航支持
• 从 CSS TextBox 迁移到 React 组件
• 迁移前后代码对比

API 参考

📄 阅读： 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

快速入门

带浮动标签的基本 TextBox

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

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

带图标的 TextBox

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}
    />
  );
}

带清除按钮的 TextBox

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

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

多行 TextBox

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

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

常见模式

带验证状态的表单

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>
  );
}

带切换按钮的密码 TextBox

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}
    />
  );
}

带单位标签的电子邮件输入框

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}
    />
  );
}

圆角 TextBox

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

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

已禁用的 TextBox

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

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

RTL TextBox

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

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

自动调整大小的多行 TextBox

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}
    />
  );
}

关键属性

属性	类型	用途
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	在输入框后渲染元素

关键事件

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

相关文档

ℹ️ 以下外部链接仅供手动参考。 未经用户明确同意，请勿在 Agent 工作流中自动获取这些 URL。

• Syncfusion React TextBox 组件演示 （外部）
• React TextBox API 参考 （外部）
• Syncfusion React Inputs 包 （外部——安装前请先核实）
• React 函数组件

复选框

Syncfusion React CheckBoxComponent 是一种图形用户界面元素，允许用户选择一个或多个选项。它支持选中、未选中和不确定状态、灵活的标签位置、多种尺寸、全面的无障碍支持，以及丰富的 CSS 自定义功能。

包： @syncfusion/ej2-react-buttons

---

导航指南

🛑 **Agent 使用须知：**请勿自主执行多个步骤。每项操作（安装、运行、创建文件）前都要先向用户确认。

入门

📄 阅读： 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

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

📄 阅读： references/states.md

• 设置 checked={true} 以启用选中状态
• 设置 indeterminate={true} 以启用不确定状态
• 设置 disabled={true} 以启用禁用状态
• 组合状态示例

标签和尺寸

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

• 使用 label 属性设置说明文字
• labelPosition（"Before" / "After"）
• 使用 cssClass="e-small" 设置小尺寸
• 默认尺寸与小尺寸示例

样式和外观

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

• 可用于覆盖复选框样式的 CSS 类
• 自定义颜色变体（主要、成功、警告、危险、信息）
• 自定义边框形状（圆形复选框）
• 自定义勾选图标
• 与 Theme Studio 集成

无障碍和 RTL

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 / Section 508 标准
• WAI-ARIA 属性（aria-disabled）
• 键盘导航（空格键）
• 支持从右向左（enableRtl）显示
• 屏幕阅读器支持

操作指南

📄 阅读： references/how-to.md

• 在表单提交中设置名称和值
• 启用从右向左显示
• 构建自定义复选框变体

API 参考

📄 阅读： references/api.md

• 所有属性：checked、cssClass、disabled、enableHtmlSanitizer、enablePersistence、enableRtl、htmlAttributes、indeterminate、label、labelPosition、locale、name、value
• 方法：click()、destroy()、focusIn()
• 事件：change、created

---

快速入门

npm install @syncfusion/ej2-react-buttons --save
# Then run: npm audit

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

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;

---

常见模式

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

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;

带不确定状态的父级 / 子级复选框

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;

使用名称和值提交表单

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;

---

关键属性一览

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

---

签名

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

包： @syncfusion/ej2-react-inputs

---

导航指南

🛑 Agentic 使用： 请勿自主执行多个步骤。每项操作（安装、运行、创建文件）前都要向用户确认。

开始使用

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-react-inputs 🛑 停止 — 请勿自主安装软件包。请用户运行：npm install @syncfusion/ej2-react-inputs --save。使用 npm audit 验证
• CSS 主题导入（Tailwind3）
• 最简 SignatureComponent 配置
• 运行应用 🛑 停止 — 请勿自主启动开发服务器。请用户运行：npm run dev

自定义

📄 阅读： references/customization.md

• 笔画宽度：maxStrokeWidth、minStrokeWidth、velocity
• 笔画颜色：strokeColor
• 背景颜色：backgroundColor
• 背景图像：backgroundImage

打开和保存

📄 阅读： references/open-save.md

• 从 base64 或 URL 加载签名（load）
• 保存为 base64（getSignature）
• 保存为 Blob（saveAsBlob、getBlob）
• 保存为图像文件 — PNG、JPEG、SVG（save）
• 连同背景一起保存（saveWithBackground）

用户交互

📄 阅读： references/user-interaction.md

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

工具栏集成

📄 阅读： references/toolbar-integration.md

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

无障碍访问

📄 阅读： references/accessibility.md

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

API 参考

📄 阅读： 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

---

快速入门

npm install @syncfusion/ej2-react-inputs --save
# Then run: npm audit

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

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;

---

常见模式

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

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;

将签名保存为 PNG

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;

---

主要属性一览

属性	类型	默认值	用途
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 输入

用于收集一次性密码、PIN 码和验证码的专用输入组件。可渲染可配置数量的单字符输入框，并支持完整的键盘导航、无障碍功能和多种视觉样式。

快速开始

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

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

安装：

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

常见模式

带验证回调的 6 位 OTP

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}
    />
  );
}

带错误状态的密码掩码 OTP

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="*"
    />
  );
}

带分隔符的字母数字 OTP

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"
    />
  );
}

主要属性

属性	类型	默认值	用途
length	number	4	OTP 输入框的数量
value	string | number	''	当前 OTP 值
type	'number' | 'text' | 'password'	'number'	输入字符类型
stylingMode	'outlined' | 'filled' | 'underlined'	'outlined'	视觉样式变体
placeholder	string	''	每个输入框的提示字符
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 属性

导航指南

安装、设置与基本用法

📄 阅读： references/getting-started.md

• 使用 npm 安装并设置 Vite 项目
• CSS 主题导入
• 最简可运行示例
• 设置 OTP 长度
• 设置默认值
• 加载时自动聚焦
• 故障排除

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

📄 阅读： references/configuration.md

• 输入类型：数字、文本、密码
• 样式模式：描边、填充、下划线
• 占位文本（统一设置／逐项设置）
• 分隔字符
• 禁用状态
• CSS 类自定义（e-success、e-warning、e-error）
• RTL 支持
• 文本转换（大写／小写）
• 状态持久化

事件与交互处理

📄 阅读： references/events.md

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

无障碍访问

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2、Section 508 标准
• WAI-ARIA 角色和属性
• 键盘导航快捷键
• 按字段配置 ariaLabels
• 使用 htmlAttributes 添加自定义无障碍元数据
• 支持 RTL
• 使用 Axe-core 和 accessibility-checker 进行验证

完整 API 参考

📄 阅读： references/api.md

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

选择指南

应该使用哪种类型？

• 用户仅输入数字 → 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 组件可在表单和应用中高效收集多行文本输入。它提供用户反馈、评论、描述以及任何需要输入较长文本的场景所需的基本功能。

导航指南

开始使用

📄 阅读： references/getting-started.md

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

核心功能与内容

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

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

浮动标签与占位符

📄 阅读： references/floating-label.md

• 浮动标签类型（Auto、Always、Never）
• 用户交互期间的占位符行为
• 使用浮动标签进行本地化
• 不同区域设置的占位符文本翻译

装饰元素（自定义元素）

📄 阅读： references/adornments.md

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

表单集成

📄 阅读： references/form-support.md

• 使用 textarea 提交 HTML 表单
• name 属性和表单数据
• 集成 FormValidator 配置验证规则
• 必填字段、最小/最大长度限制
• 验证消息和错误状态

内容限制

📄 阅读： references/max-length.md

• 使用 maxLength 限制字符数
• 防止用户输入超过限制
• 向用户说明字符限制
• 边缘情况和最佳实践

大小与尺寸

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

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

调整大小行为

📄 阅读： references/resize.md

• 调整大小模式：Vertical、Horizontal、Both、None
• 用户控制调整大小
• 自定义宽度
• 固定尺寸 textarea 的布局注意事项

样式与外观

📄 阅读： references/styling-appearance.md

• 尺寸类（e-small、e-bigger）
• 填充和轮廓外观模式
• 使用 cssClass 属性自定义 CSS
• 禁用和只读状态
• 验证状态样式（成功、警告、错误）
• 清除按钮配置
• 颜色自定义和圆角

事件与用户交互

📄 阅读： references/events.md

• created：初始化事件
• input：实时值变化检测
• change：失去焦点时触发的值变化
• focus：获得焦点
• blur：失去焦点
• destroyed：组件清理
• 事件参数和使用模式

方法与编程控制

📄 阅读： references/methods.md

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

完整 API 参考

📄 阅读： references/api.md

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

快速入门

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;

常见模式

模式 1：带验证的表单

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

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

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

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

模式 3：使用自定义 CSS 设置样式

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

模式 4：禁用和只读状态

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

模式 5：带装饰元素

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

关键属性摘要

属性	用途	常见值
value	设置/获取文本区域内容	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

Slider（RangeSlider）

这是一份全面指南，介绍如何在 React 应用中实现 Syncfusion Essential JS 2 SliderComponent。支持单值（Default）、最小范围填充（MinRange）和双滑块范围选择（Range），并提供工具提示、刻度、限制、颜色范围、自定义值、格式化、无障碍支持、事件等功能。

软件包： @syncfusion/ej2-react-inputs

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 三种滑块类型的基本实现
• CSS 导入和主题设置
• 最简可运行示例
• 初始配置

类型和方向

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

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

工具提示和刻度

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

• 工具提示配置和位置
• 工具提示显示模式（Always、Focus、Click）
• 刻度标记和刻度显示
• largeStep 和 smallStep 配置
• 小刻度显示
• 工具提示与刻度组合示例

格式化和限制

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

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

样式和自定义

📄 阅读： references/styling.md

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

无障碍功能

📄 阅读： 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 区域
• 焦点管理和颜色对比度要求
• 移动设备触控无障碍功能

颜色范围

📄 阅读： references/color-range.md

• colorRange 属性和 ColorRangeDataModel 接口
• 三区域和多区域模式（红色/琥珀色/绿色）
• 使用 Range 类型的颜色范围（双滑块）
• 根据运行时数据动态设置颜色区域
• 实际应用：电池、风险、性能、分数模式
• 将 colorRange 与 limits、ticks 和 tooltip 结合使用

事件和方法

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

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

API 参考

📄 阅读： 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'）

快速入门

基本单值滑块

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;

范围滑块（两个滑块）

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;

价格范围选择器

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;

常见模式

模式 1：带刻度的单值

使用 Default 类型进行简单的数值选择，并显示刻度。

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

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

使用 Range 类型和限制，将滑块的移动范围限定在特定区域内。

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

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

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

<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'
  }}
/>

模式 4：垂直方向

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

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

模式 5：带增减按钮

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

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

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

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

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' }}
/>

模式 7：自定义值刻度

使用 customValues 将非数字标签用作滑块值。

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

模式 8：只读显示

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

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

关键属性

属性	类型	默认值	用途
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 类

类型对比

类型	手柄数	填充行为	适用场景
Default	1	不填充	简单的数值选择
MinRange	1	从最小值开始填充	可视化进度或级别指示
Range	2	填充两个手柄之间的区域	最小值/最大值范围选择

常见使用场景

预算范围选择器

按步长选择最低和最高预算，并格式化货币。 → 使用 type="Range"、step={50}、格式 'C0'，并启用工具提示

时间范围选择器

选择时间范围（小时、分钟、天）。 → 使用 type="Range"，通过 renderingTicks 事件自定义格式

音量/亮度控制

使用单个手柄进行调节，并即时反馈。 → 使用 type="Default"，不显示刻度，并始终显示工具提示

分数/评分范围

使用 MinRange 模式，并通过阴影显示当前级别。 → 使用 type="MinRange"、min={0}、max={10}，并按步长调整

产品筛选器

为多个产品类别设置价格范围。 → 使用 type="Range"、为每个类别设置限制，并添加事件处理程序

事件

事件	触发时机	用途
created	组件创建并渲染后	执行一次性设置操作
change	拖动时值发生变化	实时反馈（连续触发）
changed	拖动完成（松开手柄）	获取最终提交的值
tooltipChange	工具提示即将渲染时	自定义工具提示文本格式
renderingTicks	每个刻度正在渲染时	自定义刻度标签文本
renderedTicks	所有刻度渲染完成后	对刻度 DOM 元素进行后处理

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

故障排查快速链接

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

值未更新？ → 使用 change（连续触发）或 changed（松开时触发）事件，而不是 onChange

格式设置无效？ → 查看 formatting-and-limits.md 中的格式 API 示例

存在无障碍问题？ → 参阅 accessibility.md，了解 ARIA 和键盘支持

垂直滑块未渲染？ → 将其放入具有明确 height 的容器中（例如，style={{ height: '300px' }}）

范围类型只有一个值？ → 对于 type="Range"，始终传入 value={[start, end]} 数组

颜色区域未显示？ → 检查 colorRange 数组是否包含有效的 start、end 和 color 属性

后续步骤

1. 根据使用场景选择滑块类型（Default、MinRange 或 Range）
2. 阅读 getting-started.md 了解安装方法
3. 根据所需功能，查阅相应的参考文档
4. 使用参考文件中的示例进行测试
5. 使用 styling.md 自定义样式
6. 参照 accessibility.md 确保无障碍访问
7. 根据 api-reference.md 验证所有 API 的用法

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

ColorPicker

Syncfusion React ColorPicker 支持用户通过可视化选色器（HSV + 不透明度）或色板选取颜色。默认情况下，它以 SplitButton 形式渲染（打开弹出窗口），也支持内联渲染，并支持 RGB、HSV 和 Hex 颜色格式。

包： @syncfusion/ej2-react-inputs
组件： <ColorPickerComponent>

导航指南

入门

📄 阅读： references/getting-started.md

• 使用 Vite 或 Create React App 安装
• npm 包设置
• CSS 主题导入
• 最简可运行示例
• 运行应用程序

模式和颜色值

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

• 内联渲染与弹出窗口（SplitButton）
• 选色器模式与色板模式
• 设置初始颜色值（Hex 代码）
• 不透明度支持
• 仅渲染色板（锁定模式）

色板功能

📄 阅读： references/palette-features.md

• 自定义调色板（presetColors）
• 自定义色板色块渲染（beforeTileRender）
• 支持无颜色／清除颜色（noColor）
• 自定义无颜色选项
• 显示最近使用的颜色（showRecentColors）
• 色板列数（columns）

UI 自定义

📄 阅读： references/ui-customization.md

• 隐藏输入值区域
• 自定义选色器手柄
• 使用图标自定义主按钮
• 在输入元素中显示 Hex 代码
• 隐藏控制按钮（Apply/Cancel）
• CSS 类覆盖和 Theme Studio
• 使用 SplitButton 和 Dialog 打造类似 Excel 的自定义 UI

集成与高级功能

📄 阅读： references/integration-and-advanced.md

• 在 DropDownButton 中嵌入 ColorPicker
• 弹出窗口切换控制
• 页面重新加载后保留状态
• 模式切换器的可见性和事件
• 禁用状态

本地化和 RTL

📄 阅读： references/localization-and-rtl.md

• 本地化 Apply / Cancel / ModeSwitcher 标签
• 使用 L10n 加载翻译对象
• 从右向左渲染（enableRtl）

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 / Section 508 标准
• WAI-ARIA 属性
• 键盘导航快捷键
• 无障碍验证

API 参考

📄 阅读： references/api.md

• 所有属性及其类型和默认值
• 所有方法及其签名
• 所有事件及其负载类型

---

快速开始

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

/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-react-inputs/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-splitbuttons/styles/tailwind3.css";

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

function App() {
  return (
    <div id="container">
      <div className="wrap">
        <h4>Choose Color</h4>
        <ColorPickerComponent id="color-picker" />
      </div>
    </div>
  );
}
export default App;

---

常见模式

内联选择器（无弹出窗口）

<ColorPickerComponent inline={true} showButtons={false} />

仅调色板模式

<ColorPickerComponent mode="Palette" modeSwitcher={false} showButtons={false} />

设置初始颜色并处理更改

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

function App() {
  function onChange(args: ColorPickerEventArgs): void {
    console.log(args.currentValue.hex);  // e.g. "#ff5733"
    console.log(args.currentValue.rgba); // e.g. "rgba(255,87,51,1)"
  }
  return <ColorPickerComponent value="#ff5733" change={onChange} />;
}

使用预设颜色的自定义调色板

const presets: { [key: string]: string[] } = {
  'brand': ['#0078d4', '#106ebe', '#005a9e', '#004578'],
  'accents': ['#e81123', '#ff8c00', '#00b294', '#68217a']
};

<ColorPickerComponent
  mode="Palette"
  presetColors={presets}
  columns={4}
  modeSwitcher={false}
  inline={true}
  showButtons={false}
/>

禁用不透明度滑块

<ColorPickerComponent enableOpacity={false} />

支持无颜色（清除选择）

<ColorPickerComponent
  mode="Palette"
  noColor={true}
  modeSwitcher={false}
  showButtons={false}
/>

本地化（德语）

import { L10n } from '@syncfusion/ej2-base';

L10n.load({
  'de-DE': {
    'colorpicker': { Apply: 'Anwenden', Cancel: 'Abbrechen', ModeSwitcher: 'Modus wechseln' }
  }
});

<ColorPickerComponent locale="de-DE" />

---

主要属性

属性	类型	默认值	用途
value	string	'#008000ff'	初始颜色（3/4/6/8 位十六进制）
mode	'Picker' | 'Palette'	'Picker'	初始显示的面板
inline	boolean	false	直接渲染组件（无弹出窗口）
showButtons	boolean	true	显示应用/取消按钮
modeSwitcher	boolean	true	显示模式切换按钮
noColor	boolean	false	在调色板中添加“无颜色”色块
presetColors	object	null	调色板的自定义颜色组
columns	number	10	调色板列数
enableOpacity	boolean	true	显示不透明度滑块
showRecentColors	boolean	false	显示最近使用的颜色色块（仅调色板模式）
disabled	boolean	false	禁用组件
cssClass	string	''	根元素上的自定义 CSS 类
enableRtl	boolean	false	从右向左渲染
locale	string	''	本地化的区域设置字符串

MaskedTextBox

Syncfusion React MaskedTextBox 组件通过应用掩码模式来强制使用特定的输入格式，引导用户按正确结构输入数据。它适用于电话号码、邮政编码、日期、IP 地址、产品密钥，以及任何输入必须遵循预定义格式的场景。

导航指南

开始使用

📄 阅读： references/getting-started.md

• 通过 npm 安装（@syncfusion/ej2-react-inputs）
• Vite / Create-React-App 设置
• 用于主题的 CSS 导入
• 渲染基本的 MaskedTextBox
• 设置 mask 属性以强制指定格式

掩码配置

📄 阅读： references/mask-configuration.md

• 标准掩码元素标记（0、9、#、L、?、&、C、A、a、<、>、|、\）
• 通过 customCharacters 属性自定义字符
• 用于灵活模式（例如 IP 地址）的正则表达式掩码
• 通过 promptChar 自定义提示字符

装饰元素（前置 / 后置元素）

📄 阅读： references/adornments.md

• 使用 prependTemplate 和 appendTemplate 在输入框前后添加图标或按钮
• 输入引导、快捷操作和上下文标签
• 类组件和函数组件示例

React Hooks 集成

📄 阅读： references/react-hooks.md

• 使用 useState 的受控组件
• 使用 useEffect + useRef + focusIn() 在挂载时自动聚焦
• 使用 useReducer 处理多个掩码输入框
• 在函数组件中处理 change 事件

样式、外观与自定义

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

• 使用 cssClass 自定义样式
• 覆盖包装器、悬停和聚焦状态的 CSS
• 使用 focus 事件设置光标位置（selectionStart、selectionEnd）
• 在移动设备上使用 type="tel" 显示数字键盘
• floatLabelType 选项（Never、Always、Auto）

表单验证

📄 阅读： references/form-validation.md

• 与 Syncfusion FormValidator 集成
• 使用 ej2_instances 定义自定义验证规则
• 使用 customPlacement 自定义错误位置
• 使用 promptChar 检查未完成的掩码值

API 参考

📄 阅读： references/api.md

• 所有属性：mask、value、placeholder、floatLabelType、promptChar、customCharacters、cssClass、enabled、readonly、showClearButton、enableRtl、enablePersistence、htmlAttributes、locale、width、prependTemplate、appendTemplate
• 方法：focusIn()、focusOut()、getMaskedValue()、destroy()、getPersistData()
• 事件：change、focus、blur、created、destroyed

快速开始

import * as React from 'react';
import { MaskedTextBoxComponent } from '@syncfusion/ej2-react-inputs';
import '../node_modules/@syncfusion/ej2-base/styles/tailwind3.css';
import '../node_modules/@syncfusion/ej2-react-inputs/styles/tailwind3.css';

export default function App() {
  return (
    <MaskedTextBoxComponent
      mask="000-000-0000"
      placeholder="Enter phone number"
      floatLabelType="Auto"
    />
  );
}

常见模式

电话号码输入

<MaskedTextBoxComponent mask="000-000-0000" placeholder="Phone" floatLabelType="Always" />

使用正则表达式掩码的 IP 地址

<MaskedTextBoxComponent
  mask="[0-2][0-9][0-9].[0-2][0-9][0-9].[0-2][0-9][0-9].[0-2][0-9][0-9]"
  placeholder="IP Address (ex: 212.212.111.222)"
  floatLabelType="Always"
/>

自定义 AM/PM 时间输入

const chars = { P: 'P,A,p,a', M: 'M,m' };
<MaskedTextBoxComponent
  mask="00:00 >PM"
  customCharacters={chars}
  placeholder="Time (ex: 10:00 PM)"
  floatLabelType="Always"
/>

以编程方式读取掩码值

const maskRef = React.useRef(null);
// Later:
const maskedVal = maskRef.current.getMaskedValue(); // e.g., "123-456-7890"
const rawVal = maskRef.current.value;               // e.g., "1234567890"

使用 Change 事件的受控输入

const [phone, setPhone] = React.useState('');
<MaskedTextBoxComponent
  mask="000-000-0000"
  value={phone}
  change={(e) => setPhone(e.value)}
  placeholder="Phone"
  floatLabelType="Auto"
/>

评分

Syncfusion React RatingComponent 可让用户从一组可视符号（默认是星形）中选择评分值。它支持精度模式、自定义模板、工具提示、标签、重置、只读/禁用状态、完全符合无障碍要求，以及丰富的 CSS 自定义选项。

软件包： @syncfusion/ej2-react-inputs

---

导航指南

入门

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-react-inputs
• 导入 Tailwind3 CSS 主题
• 最简 RatingComponent 设置
• 设置初始 value 属性
• 运行 Vite/React 应用

选择与重置

📄 阅读： references/selection.md

• 使用 value 设置评分值
• 使用 min 设置最低评分值
• 使用 enableSingleSelection 启用单选模式
• 使用 allowReset 显示/隐藏重置按钮
• 以编程方式调用 reset() 方法

精度模式

📄 阅读： references/precision-modes.md

• PrecisionType.Full — 按整数递增
• PrecisionType.Half — 按 0.5 递增
• PrecisionType.Quarter — 按 0.25 递增
• PrecisionType.Exact — 按 0.1 递增
• 将精度与初始值结合使用

外观与自定义

📄 阅读： references/appearance.md

• 使用 itemsCount 控制项目数量
• 使用 disabled 禁用组件
• 使用 visible 隐藏/显示组件
• 使用 readOnly 启用只读模式
• 使用 cssClass 自定义 CSS（边框颜色、填充颜色、项目间距、图标）
• 通过 CSS 更改评分图标

标签

📄 阅读： references/labels.md

• 使用 showLabel 显示当前值标签
• labelPosition 选项：Top、Bottom、Left、Right
• 使用 labelTemplate 自定义标签内容

工具提示

📄 阅读： references/tooltip.md

• 使用 showTooltip 启用工具提示
• 使用 tooltipTemplate 自定义工具提示内容
• 通过 cssClass 设置工具提示外观

模板

📄 阅读： references/templates.md

• 使用 emptyTemplate 设置未评分项目
• 使用 fullTemplate 设置已评分项目
• Emoji 评分符号
• SVG 图标评分符号
• PNG 图片评分符号
• 通过 --rating-value 在模板中支持精度

事件

📄 阅读： references/events.md

• beforeItemRender — 在渲染前自定义项目
• created — 组件初始化后触发
• onItemHover — 跟踪悬停的项目
• valueChanged — 响应用户评分变更

无障碍访问

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 / Section 508 / ADA 标准
• WAI-ARIA 属性（role=slider、aria-valuemin/max/now）
• 键盘导航快捷键
• 支持 RTL，可通过 enableRtl 启用
• 支持屏幕阅读器

API 参考

📄 阅读： references/api.md

• 所有属性、方法和事件及其类型与默认值
• RatingItemEventArgs、RatingHoverEventArgs、RatingChangedEventArgs
• LabelPosition 和 PrecisionType 枚举

---

快速开始

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

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

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

function App() {
  return (
    <RatingComponent id="rating" value={3} />
  );
}
export default App;

---

常见模式

带值变更处理程序的评分组件

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

function App() {
  const [rating, setRating] = React.useState(3);

  const handleValueChanged = (args: RatingChangedEventArgs) => {
    setRating(args.value);
  };

  return (
    <RatingComponent
      id="rating"
      value={rating}
      valueChanged={handleValueChanged}
    />
  );
}
export default App;

带标签的半精度评分

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

function App() {
  return (
    <RatingComponent
      id="rating"
      value={3.5}
      precision={PrecisionType.Half}
      showLabel={true}
    />
  );
}
export default App;

只读评分（仅用于显示）

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

function App() {
  return (
    <RatingComponent id="rating" value={4} readOnly={true} showTooltip={false} />
  );
}
export default App;

带重置按钮的评分组件

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

function App() {
  return (
    <RatingComponent id="rating" value={3} allowReset={true} />
  );
}
export default App;

---

主要属性一览

属性	类型	默认值	用途
value	number	0.0	当前评分值
itemsCount	number	5	评分项数量
min	number	0.0	可选择的最小值
precision	PrecisionType | string	Full	评分粒度
allowReset	boolean	false	显示重置按钮
readOnly	boolean	false	禁止用户交互
disabled	boolean	false	禁用组件
visible	boolean	true	显示／隐藏组件
showLabel	boolean	false	显示当前值标签
labelPosition	LabelPosition | string	Right	标签位置
showTooltip	boolean	true	显示悬停提示
enableSingleSelection	boolean	false	仅允许选择一项
enableAnimation	boolean	true	悬停动画
enableRtl	boolean	false	从右向左模式
cssClass	string	''	自定义 CSS 类

---