syncfusion-javascript-inputs

Syncfusion JavaScript 输入组件

ColorPicker

ColorPicker 组件是用于选择和调整颜色值的用户界面。它支持 HEX、RGB 和 HSV 颜色模型、调色板和拾色器模式、不透明度控制、内嵌渲染、自定义预设调色板以及双模式切换。

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置（@syncfusion/ej2-inputs）
• 必需的 CSS 导入和主题配置
• 使用 <input type="color"> 进行基本初始化
• 拾色器模式与调色板模式
• 使用 inline: true 进行内嵌渲染
• 预设颜色值
• 生命周期事件：created

模式与显示

📄 阅读： references/modes-display.md

• mode: 'Picker' — HSV 渐变区域、色相滑块、不透明度滑块
• mode: 'Palette' — 颜色网格色块
• modeSwitcher — 显示/隐藏模式切换按钮
• inline: true — 内嵌渲染，不显示弹出窗口
• createPopupOnClick — 延迟创建弹出窗口
• showButtons — 显示/隐藏“应用”和“取消”按钮
• showRecentColors — 最近使用的颜色条（仅限调色板模式）

调色板自定义

📄 阅读： references/palette-customization.md

• 默认调色板颜色（100 色网格）
• presetColors — 带命名分组的自定义颜色组
• columns — 每行的色块数
• noColor — 表示无颜色的透明色块
• beforeTileRender 事件 — 自定义色块元素
• 自定义调色板分组（多个命名分组）

颜色值与转换

📄 阅读： references/color-value-conversion.md

• value 属性 — HEX8 格式（#rrggbbaa）
• getValue(value?, type?) — 在 HEX、HEXA、RGB、RGBA、HSV、HSVA 格式之间转换
• 从 change 和 select 事件读取颜色（currentValue.hex、currentValue.rgba）
• 使用 enableOpacity 控制不透明度
• 使用 value + dataBind() 以编程方式设置颜色

不透明度与无障碍功能

📄 阅读： references/opacity-accessibility.md

• enableOpacity — 显示/隐藏不透明度滑块和 alpha 通道
• enableRtl — 从右向左布局
• disabled — 禁用组件
• enablePersistence — 在重新加载后保留所选值
• cssClass — 用于设置样式的自定义 CSS 类
• 拾色器和调色板模式下的键盘导航
• focusIn() — 以编程方式设置焦点

事件

📄 阅读： references/events.md

• change — 应用颜色时触发（点击“应用”按钮，或在 showButtons: false 时立即触发）
• select — 在 showButtons: true 时，选择颜色后触发
• beforeOpen / open — 弹出窗口打开生命周期（支持取消）
• beforeClose — 弹出窗口关闭生命周期（支持取消）
• beforeModeSwitch / onModeSwitch — 模式切换生命周期
• beforeTileRender — 调色板色块自定义
• created — 组件就绪

API 参考

📄 阅读： references/api.md

• 全部 14 个属性及其类型和默认值
• 全部 11 个方法及其参数表
• 全部 9 个事件及其参数接口
• 事件参数接口：ColorPickerEventArgs、PaletteTileEventArgs、BeforeOpenCloseEventArgs、OpenEventArgs、ModeSwitchEventArgs

---

快速开始

最简拾色器（弹出模式）

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

const colorPicker: ColorPicker = new ColorPicker({
  value: '#008000ff',
  change: (args) => {
    console.log('Selected hex:', args.currentValue.hex);
    console.log('Selected rgba:', args.currentValue.rgba);
  }
});
colorPicker.appendTo('#color-picker');

<input type="color" id="color-picker" />

调色板模式（内嵌）

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

const colorPicker: ColorPicker = new ColorPicker({
  mode: 'Palette',
  inline: true,
  showButtons: false,
  change: (args) => {
    document.getElementById('preview').style.backgroundColor = args.currentValue.rgba;
  }
});
colorPicker.appendTo('#color-picker');

---

常见模式

目标	属性 / 方法
设置初始颜色	value: '#ff5733ff'
调色板网格布局	mode: 'Palette'
嵌入页面	inline: true
隐藏应用 / 取消按钮	showButtons: false
自定义颜色组	presetColors: { primary: [...], accent: [...] }
禁用不透明度	enableOpacity: false
透明选项	noColor: true（仅限调色板模式）
显示最近使用的颜色	showRecentColors: true（仅限调色板模式）
转换颜色格式	colorPicker.getValue(hex, 'rgba')
切换弹出窗口	colorPicker.toggle()
聚焦组件	colorPicker.focusIn()
应用更改	colorPicker.value = '#ff0000'; colorPicker.dataBind()

MaskedTextBox

MaskedTextBox（@syncfusion/ej2-inputs）通过应用掩码模式来约束结构化输入，逐字符引导并验证用户输入。当你需要确保输入符合特定格式时，例如电话号码、日期、IP 地址、SSN、邮政编码等，请使用它。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 CSS 导入
• 基本的 MaskedTextBox 设置
• 设置 mask 属性
• 占位符和浮动标签
• 最小可运行示例

掩码配置

📄 阅读： references/mask-configuration.md

• 标准掩码元素表（0、9、#、L、?、&、C、A、a、<、>、|、\）
• 通过 customCharacters 使用自定义字符
• 正则表达式掩码
• 自定义提示字符（promptChar）

值访问和编程控制

📄 阅读： references/value-access.md

• value 属性（原始、未掩码）
• getMaskedValue() 方法（带掩码格式）
• 以编程方式设置值
• 在 change 事件中读取输入
• focusIn() / focusOut() 方法

自定义和外观

📄 阅读： references/customization.md

• 使用 cssClass 自定义样式
• floatLabelType（Never / Always / Auto）
• enableRtl、enabled、readonly
• showClearButton
• 使用 htmlAttributes 添加额外的 HTML 属性
• width、placeholder
• 用于包装器和悬停状态的 CSS 覆盖样式

附加元素

📄 阅读： references/adornments.md

• prependTemplate — 在输入框前注入 HTML（图标、标签、国家代码）
• appendTemplate — 在输入框后注入 HTML（按钮、图标、单位后缀）
• 用于视觉分隔线的 e-input-separator 类
• 常见附加元素模式表
• ⚠️ 安全： 如果模板 HTML 包含源自用户输入或远程来源的值，请在绑定前对其进行清理 / 编码，以防止 XSS 注入。

事件和交互

📄 阅读： references/events.md

• 带有 MaskChangeEventArgs 的 change 事件
• 带有 MaskFocusEventArgs 的 focus 事件（光标定位）
• 带有 MaskBlurEventArgs 的 blur 事件
• created 和 destroyed 事件
• 在起始位置 / 末尾位置 / 自定义位置设置光标位置

验证和操作指南

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

• 与自定义规则集成 FormValidator
• 在移动设备上使用数字键盘（htmlAttributes: { type: 'tel' }）
• 检查输入是完整还是部分内容
• 无障碍功能（ARIA 属性、WCAG 合规性）

API 参考

📄 阅读： references/api.md

• 所有属性、方法、事件和接口
• 完整的 MaskedTextBox API

---

快速入门

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

// CSS in styles.css:
// @import '../node_modules/@syncfusion/ej2-base/styles/material.css';
// @import '../node_modules/@syncfusion/ej2-inputs/styles/material.css';

// HTML: <input id="mask" type="text" />

let mask: MaskedTextBox = new MaskedTextBox({
    mask: '000-000-0000',
    placeholder: 'Phone Number',
    floatLabelType: 'Always'
});
mask.appendTo('#mask');

---

常见模式

场景	模式
电话号码	mask: '(999) 999-9999'
美国邮政编码	mask: '00000' 或 mask: '00000-9999'
日期	mask: '00/00/0000'
IP 地址	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]'
信用卡	mask: '0000 0000 0000 0000'
时间（AM/PM）	mask: '00:00 >PM'，并使用 customCharacters: { P: 'P,A,p,a', M: 'M,m' }
仅限字母	mask: 'LLLLLL'
字母数字	mask: 'AAAAAA'
大小写控制	mask: '>LLL<LLL'（前 3 个大写，后 3 个小写）

读取原始值

let mask: MaskedTextBox = new MaskedTextBox({
    mask: '(999) 999-9999',
    change: (args) => {
        console.log('Raw value:', args.value);           // digits only
        console.log('Masked value:', args.maskedValue);  // with mask chars
    }
});
mask.appendTo('#mask');

// Or programmatically:
const raw = mask.value;
const formatted = mask.getMaskedValue();

带预填值的浮动标签

let mask: MaskedTextBox = new MaskedTextBox({
    mask: '(999) 9999-999',
    value: '8674321756',
    placeholder: 'Mobile Number',
    floatLabelType: 'Auto'
});
mask.appendTo('#mask');

OTP 输入

OTP 输入（@syncfusion/ej2-inputs）会渲染一组独立的输入框，用于输入一次性密码。它支持配置长度、输入类型（数字/文本/密码）、样式模式、分隔符、占位符、无障碍属性以及完整的事件处理。可用于双重身份验证屏幕、OTP 验证表单和 PIN 输入流程。

导航指南

开始使用

📄 阅读： references/getting-started.md

• 安装和 CSS 导入
• OTP 输入的基本初始化
• 设置和读取 value 属性
• 使用 autoFocus 在渲染时自动聚焦
• 最小可运行示例

输入类型和值

📄 阅读： references/input-types.md

• type — number（默认）、text、password
• value — 预设或读取 OTP 值
• 为数字型与字母数字型 OTP 选择合适的类型

外观和配置

📄 阅读： references/appearance.md

• length — OTP 输入框数量（默认值为 4）
• disabled — 禁用整个控件
• cssClass — 自定义类和预定义类（e-success、e-warning、e-error）
• enableRtl — 从右向左渲染

样式模式

📄 阅读： references/styling-modes.md

• stylingMode — outlined（默认）、filled、underlined
• 各模式的适用场景

占位符

📄 阅读： references/placeholder.md

• 单字符占位符（所有输入框使用相同占位符）
• 多字符占位符（每个输入框对应一个字符）

分隔符

📄 阅读： references/separator.md

• separator — 显示在每个输入框之间的字符
• 常见分隔符模式（/、-、·）

事件

📄 阅读： references/events.md

• created — 组件渲染后触发
• focus / blur — 聚焦/失焦事件（OtpFocusEventArgs）
• input — 每个独立输入框内容变化时触发（OtpInputEventArgs）
• valueChanged — 所有输入框填写完毕并失去焦点时触发（OtpChangedEventArgs）

无障碍功能

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2、Section 508 和 ARIA 标准
• ariaLabels — 每个输入框对应的 ARIA 标签数组
• htmlAttributes — 自定义 HTML 属性
• 键盘导航（箭头键、Tab、Shift+Tab）

API 参考

📄 阅读： references/api.md

• 所有属性、方法、事件和接口
• 完整的 OTP 输入 API

---

快速开始

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

// CSS in styles.css:
// @import '../node_modules/@syncfusion/ej2-base/styles/material.css';
// @import '../node_modules/@syncfusion/ej2-inputs/styles/material.css';

// HTML: <div id="otp_input"></div>

let otpInput: OtpInput = new OtpInput({
    length: 6,
    placeholder: 'x',
    stylingMode: 'outlined'
});
otpInput.appendTo('#otp_input');

---

常见模式

场景	关键属性
4 位数字 OTP	type: 'number'（默认）
6 位数字 OTP	length: 6
字母数字代码	type: 'text'
隐藏/密码输入	type: 'password'
短横线分隔符	separator: '-'
加载时自动聚焦	autoFocus: true
描边样式（默认）	stylingMode: 'outlined'
填充样式	stylingMode: 'filled'
下划线样式	stylingMode: 'underlined'
预填值	value: '1234'
禁用状态	disabled: true
成功状态样式	cssClass: 'e-success'
错误状态样式	cssClass: 'e-error'

捕获已完成的 OTP 值

import { OtpInput, OtpChangedEventArgs } from '@syncfusion/ej2-inputs';

let otpInput: OtpInput = new OtpInput({
    length: 6,
    valueChanged: (args: OtpChangedEventArgs) => {
        console.log('Entered OTP:', args.value);
        // Trigger verification here
    }
});
otpInput.appendTo('#otp_input');

带分隔符的密码掩码 OTP

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

let otpInput: OtpInput = new OtpInput({
    length: 6,
    type: 'password',
    separator: '-',
    stylingMode: 'outlined',
    autoFocus: true
});
otpInput.appendTo('#otp_input');

范围滑块

范围滑块（@syncfusion/ej2-inputs）允许用户通过在轨道上拖动手柄来选择单个值或一系列值。它支持三种类型（Default、MinRange、Range）、刻度线、工具提示、限制、方向、格式设置、无障碍功能和表单验证。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和依赖项（@syncfusion/ej2-inputs、@syncfusion/ej2-base、@syncfusion/ej2-popups、@syncfusion/ej2-buttons）
• CSS 主题导入
• 初始化基本滑块并使用 appendTo
• 设置 value、min、max、step
• 方向（水平/垂直）
• 显示/隐藏按钮（showButtons）

滑块类型和核心配置

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

• type — Default、MinRange、Range
• 单个值与范围值（value: 30 与 value: [30, 70]）
• min、max、step 配置
• enabled、readonly、enableRtl
• enableAnimation、cssClass、width
• 可反转滑块（交换最小值/最大值）

刻度线和格式设置

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

• ticks 对象：placement、largeStep、smallStep、showSmallTicks、format
• 刻度线位置选项：Before、After、Both、None
• 格式 API（Numeric N、Percentage P、Currency C、# 格式说明符）
• 通过 renderingTicks 和 tooltipChange 事件自定义格式
• 日期/时间格式模式
• 自定义数值格式

工具提示

📄 阅读： references/tooltip-and-buttons.md

• tooltip 对象：isVisible、placement、showOn、format、cssClass
• 工具提示位置：Before、After
• showOn 值：Auto、Always、Hover、Focus、Click
• showButtons — 增加/减少按钮
• 使用 L10n 本地化按钮标签

限制

📄 阅读： references/limits.md

• limits 对象：enabled、minStart、minEnd、maxStart、maxEnd、startHandleFixed、endHandleFixed
• 限制手柄的移动范围
• 将手柄锁定在原位
• Default/MinRange 限制与 Range 限制

自定义和样式设置

📄 阅读： references/customization.md

• 覆盖轨道、手柄、限制、刻度线和按钮的 CSS 类
• 通过 change 事件动态更改颜色
• 渐变/色带样式
• 自定义滑块形状（正方形、圆形、椭圆形、图像）
• 通过 renderedTicks 事件自定义刻度标签

高级使用指南

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

• 日期格式滑块（基于毫秒）
• 时间格式滑块
• 自定义数值格式（Km、小数、前导零）
• 可反转滑块模式
• 使用 refresh() 显示原本隐藏的滑块
• 使用 FormValidator 和 changed 事件进行表单验证

无障碍功能

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2、Section 508 标准
• WAI-ARIA 属性（role=slider、aria-valuemin/max/now/text、aria-orientation、aria-label）
• 键盘导航（方向键、Home、End、Page Up/Down）

API 参考

📄 阅读： references/api.md

• 所有属性、方法、事件和子模型接口
• TicksDataModel、TooltipDataModel、LimitDataModel
• 事件参数类型

---

快速开始

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

// CSS in styles.css:
// @import '../node_modules/@syncfusion/ej2-base/styles/material.css';
// @import '../node_modules/@syncfusion/ej2-inputs/styles/material.css';
// @import '../node_modules/@syncfusion/ej2-popups/styles/material.css';
// @import '../node_modules/@syncfusion/ej2-buttons/styles/material.css';

// HTML: <div id="slider"></div>

let slider: Slider = new Slider({
    value: 30,
    min: 0,
    max: 100,
    step: 1
});
slider.appendTo('#slider');

---

常见模式

场景	关键配置
单值滑块	type: 'Default'（默认），value: 30
最小值范围阴影	type: 'MinRange'，value: 30
带两个滑块的范围	type: 'Range'，value: [30, 70]
垂直方向	orientation: 'Vertical'
显示刻度	ticks: { placement: 'After', largeStep: 20 }
始终显示工具提示	tooltip: { isVisible: true, showOn: 'Always' }
增减按钮	showButtons: true
限制滑块移动	limits: { enabled: true, minStart: 10, minEnd: 40 }
货币格式工具提示	tooltip: { isVisible: true, format: 'C2' }
百分比格式	ticks: { format: 'P0' }
反向（降序）	min: 100, max: 0
RTL 布局	enableRtl: true
禁用滑块	enabled: false
只读滑块	readonly: true

带刻度和工具提示的范围滑块

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

let rangeSlider: Slider = new Slider({
    type: 'Range',
    value: [20, 80],
    min: 0,
    max: 100,
    step: 5,
    ticks: { placement: 'After', largeStep: 20, smallStep: 5, showSmallTicks: true },
    tooltip: { isVisible: true, placement: 'Before', showOn: 'Always' }
});
rangeSlider.appendTo('#range-slider');

监听值变化

import { Slider, SliderChangeEventArgs } from '@syncfusion/ej2-inputs';

let slider: Slider = new Slider({
    value: 30,
    changed: (args: SliderChangeEventArgs) => {
        console.log('Final value:', args.value);
    },
    change: (args: SliderChangeEventArgs) => {
        console.log('While dragging:', args.value);
    }
});
slider.appendTo('#slider');

文本区域

文本区域（@syncfusion/ej2-inputs）提供功能丰富的多行文本输入，内置支持浮动标签、调整大小模式、装饰项、最大长度限制、表单集成和完整的事件处理。需要多行用户输入时，请使用它，例如评论框、反馈表单、描述字段等。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包依赖项
• CSS 导入和主题设置
• 文本区域的基本初始化
• 设置和获取值（value 属性）
• 从 change 事件读取值
• 最小可用示例

浮动标签和本地化

📄 阅读： references/floating-label.md

• floatLabelType — Never、Always、Auto 行为
• placeholder 属性的用法
• 使用 locale 属性进行本地化
• 使用 L10n 加载翻译

调整大小和尺寸

📄 阅读： references/resize.md

• resizeMode — Vertical、Horizontal、Both、None
• 使用 width 属性显式控制宽度
• 使用 rows 和 cols 属性设置可见尺寸

样式和外观

📄 阅读： references/styles-appearance.md

• 尺寸类：e-small、e-bigger
• 填充（e-filled）和轮廓（e-outline）模式
• 使用 cssClass 自定义样式
• enabled（禁用状态）和 readonly 属性
• showClearButton 和 e-static-clear 类
• 圆角、背景色和文本颜色自定义
• 浮动标签颜色（成功／警告状态）
• 占位符上的必填星号

装饰项

📄 阅读： references/adornments.md

• prependTemplate — 文本区域前的 HTML（图标、按钮）
• appendTemplate — 文本区域后的 HTML（操作按钮）
• adornmentFlow — Horizontal 或 Vertical 布局
• adornmentOrientation — 装饰项内部元素的排列方式
• AdornmentsDirection 类型的用法

最大长度

📄 阅读： references/max-length.md

• 使用 maxLength 属性限制字符数
• 达到限制时向用户提供反馈

事件

📄 阅读： references/events.md

• created、destroyed 事件
• input 事件 — 每次按键时触发（InputEventArgs）
• change 事件 — 失去焦点且值已更改时触发（ChangedEventArgs）
• focus 事件 — 获得焦点时触发（FocusInEventArgs）
• blur 事件 — 失去焦点时触发（FocusOutEventArgs）

方法

📄 阅读： references/methods.md

• focusIn() — 以编程方式设置焦点
• focusOut() — 以编程方式移除焦点
• getPersistData() — 获取持久化状态属性
• addAttributes() / removeAttributes() — 动态 HTML 属性
• dataBind() — 立即应用待处理的属性更改
• refresh() — 重新渲染组件
• destroy() — 从 DOM 中移除组件

表单支持

📄 阅读： references/form-support.md

• HTML 表单集成
• FormValidator 与验证规则集成
• 必填、minLength、maxLength 规则
• 自定义错误消息位置

API 参考

📄 阅读： references/api.md

• 所有属性、方法、事件和接口
• 完整的 TextArea API

---

快速入门

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

// CSS in styles.css:
// @import '../node_modules/@syncfusion/ej2-base/styles/material.css';
// @import '../node_modules/@syncfusion/ej2-inputs/styles/material.css';

// HTML: <textarea id="default"></textarea>

let textareaObj: TextArea = new TextArea({
    placeholder: 'Enter your comments',
    floatLabelType: 'Auto',
    resizeMode: 'Vertical'
});
textareaObj.appendTo('#default');

---

常见模式

场景	关键属性
自动浮动标签	floatLabelType: 'Auto'
最多 200 个字符	maxLength: 200
仅垂直调整大小	resizeMode: 'Vertical'
轮廓样式（Material）	cssClass: 'e-outline'
填充样式（Material）	cssClass: 'e-filled'
只读内容	readonly: true
禁用状态	enabled: false
始终显示清除按钮	showClearButton: true, cssClass: 'e-static-clear'
预设值	value: 'Initial text'
自定义尺寸	rows: 5, cols: 40
RTL 布局	enableRtl: true

值更改时读取

import { TextArea, ChangedEventArgs } from '@syncfusion/ej2-inputs';

let textareaObj: TextArea = new TextArea({
    placeholder: 'Enter your comments',
    floatLabelType: 'Auto',
    change: (args: ChangedEventArgs) => {
        console.log('Value:', args.value);
    }
});
textareaObj.appendTo('#default');

带浮动标签和最大长度的轮廓 TextArea

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

let textareaObj: TextArea = new TextArea({
    placeholder: 'Feedback',
    floatLabelType: 'Auto',
    cssClass: 'e-outline',
    maxLength: 500,
    resizeMode: 'Vertical',
    rows: 4
});
textareaObj.appendTo('#default');

NumericTextBox

Syncfusion EJ2 TypeScript NumericTextBox（@syncfusion/ej2-inputs）是一款功能丰富的数字输入控件，支持范围验证、数字格式化（标准格式和自定义格式）、小数精度、微调按钮、装饰元素、本地化、RTL 以及完整的 WCAG 2.2 无障碍支持。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包依赖项
• 项目设置（webpack 快速入门）
• CSS 主题导入
• NumericTextBox 基本初始化
• 使用 min、max、step 进行范围验证
• 使用 format 进行格式化
• 使用 decimals 和 validateDecimalOnType 设置小数精度

格式

📄 阅读： references/formats.md

• 标准格式：n、p（百分比）、c（货币）
• 使用 # 和 0 占位符的自定义格式字符串
• 将格式与 min、max 结合用于百分比输入
• 使用 currency 属性设置货币格式

装饰元素（前缀/后缀模板）

📄 阅读： references/adornments.md

• prependTemplate – 在输入框前添加元素（货币符号、图标）
• appendTemplate – 在输入框后添加元素（单位、操作按钮）
• 通过 change 事件关联两个 NumericTextBox 实例
• 使用点击事件处理程序自定义操作图标

全球化与本地化

📄 阅读： references/globalization.md

• 使用 locale 属性进行特定区域格式化
• 使用 L10n.load() 覆盖微调按钮提示文本
• 为非英语区域设置 CLDR 数据
• 使用 enableRtl 支持 RTL
• 使用 currency 和 format: 'c2' 设置货币格式

样式与外观

📄 阅读： references/style-appearance.md

• 自定义包装元素的高度和字体大小
• 自定义微调按钮图标 CSS
• 应用自定义 cssClass 更改 UI 外观
• 覆盖 e-spin-up 和 e-spin-down 图标字形

操作指南

📄 阅读： references/how-to.md

• 自定义微调按钮的向上／向下箭头图标
• 自定义步进值并隐藏微调按钮
• 使用 cssClass 自定义 UI 外观
• 聚焦时保留末尾的零
• 使用 FormValidator 执行自定义验证
• 禁止输入空值（默认设为 0，而非 null）

无障碍访问

📄 阅读： references/accessibility.md

• WAI-ARIA 角色和属性（spinbutton 角色）
• 键盘交互（向上／向下箭头键）
• 符合 WCAG 2.2、Section 508 标准
• 屏幕阅读器支持详情

API 参考

📄 阅读： references/api.md

• 所有属性及其类型和默认值
• 所有方法（increment、decrement、getText、focusIn、focusOut、dataBind 等）
• 所有事件（change、blur、focus、created、destroyed）
• 事件参数类型（ChangeEventArgs、NumericBlurEventArgs、NumericFocusEventArgs）

---

快速开始

npm install @syncfusion/ej2-inputs
npm audit

<input id="numeric" type="text" />

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

let numeric: NumericTextBox = new NumericTextBox({
  value: 10,
  min: 0,
  max: 100,
  step: 1,
  format: 'n2',
  placeholder: 'Enter a number',
  floatLabelType: 'Auto'
});

numeric.appendTo('#numeric');

/* styles.css – import one theme */
@import '../../node_modules/@syncfusion/ej2-base/styles/material.css';
@import '../../node_modules/@syncfusion/ej2-inputs/styles/material.css';

---

常见模式

货币输入

let currency: NumericTextBox = new NumericTextBox({
  format: 'c2',
  value: 100,
  placeholder: 'Price',
  floatLabelType: 'Auto'
});
currency.appendTo('#currency');

百分比输入

let percent: NumericTextBox = new NumericTextBox({
  format: 'p2',
  value: 0.5,
  min: 0,
  max: 1,
  step: 0.01,
  placeholder: 'Percentage',
  floatLabelType: 'Auto'
});
percent.appendTo('#percent');

隐藏微调按钮并自定义步进值

let numeric: NumericTextBox = new NumericTextBox({
  step: 5,
  showSpinButton: false,
  min: 0,
  max: 100,
  value: 20
});
numeric.appendTo('#numeric');

只读 NumericTextBox

let numeric: NumericTextBox = new NumericTextBox({
  value: 42,
  readonly: true
});
numeric.appendTo('#numeric');

以编程方式递增／递减

numeric.increment(5);   // increase value by 5
numeric.decrement(2);   // decrease value by 2

禁用组件

let numeric: NumericTextBox = new NumericTextBox({
  value: 10,
  enabled: false
});
numeric.appendTo('#numeric');

清除按钮

let numeric: NumericTextBox = new NumericTextBox({
  value: 10,
  showClearButton: true
});
numeric.appendTo('#numeric');

禁用鼠标滚轮

let numeric: NumericTextBox = new NumericTextBox({
  value: 10,
  allowMouseWheel: false
});
numeric.appendTo('#numeric');

---

关键属性一览

属性	类型	默认值	用途
value	number	null	当前数值
min	number	null	允许的最小值
max	number	null	允许的最大值
step	number	1	递增／递减步长
format	string	'n2'	未聚焦时的显示格式
decimals	number	null	聚焦时的小数精度
validateDecimalOnType	boolean	false	输入时限制小数位数
strictMode	boolean	true	失焦时将值限制在最小值／最大值范围内
floatLabelType	FloatLabelType	'Never'	标签浮动行为
placeholder	string	null	提示文本／浮动标签
showSpinButton	boolean	true	显示／隐藏微调按钮
showClearButton	boolean	false	显示清除（×）图标
readonly	boolean	false	只读模式
enabled	boolean	true	启用／禁用控件
enableRtl	boolean	false	从右向左布局
locale	string	''	区域设置代码
currency	string	null	ISO 4217 货币代码
cssClass	string	null	自定义 CSS 类
width	number|string	null	组件宽度
allowMouseWheel	boolean	true	启用鼠标滚轮修改值
enablePersistence	boolean	false	重新加载后保留值
prependTemplate	string|Function	null	输入框前的 HTML
appendTemplate	string|Function	null	输入框后的 HTML
htmlAttributes	object	{}	额外的 HTML 属性

评分

Rating 组件（@syncfusion/ej2-inputs）允许用户通过点击或轻触符号（默认是星形）在数值刻度上选择值。它支持精确评分、自定义模板、标签、工具提示，并全面符合无障碍访问标准。

依赖项

@syncfusion/ej2-inputs
  └── @syncfusion/ej2-base
  └── @syncfusion/ej2-popups

快速开始

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

let rating: Rating = new Rating({ value: 3.0 });
rating.appendTo('#rating');

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

<input id="rating" />

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包配置
• CSS 导入和主题配置
• 初始化 Rating
• 设置 value 属性
• 运行应用程序

选择与值控制

📄 阅读： references/selection.md

• 设置和读取评分值
• 使用 min 属性设置最小值
• 单选模式（enableSingleSelection）
• 显示／隐藏重置按钮（allowReset）
• 通过 reset() 方法以编程方式重置

精度模式

📄 阅读： references/precision-modes.md

• 全精度（整数）
• 半精度（以 0.5 为增量）
• 四分之一精度（以 0.25 为增量）
• 精确精度（以 0.1 为增量）
• PrecisionType 枚举的用法

标签

📄 阅读： references/labels.md

• 将当前值显示为标签（showLabel）
• 标签位置：顶部、底部、左侧、右侧（labelPosition）
• 自定义标签模板（labelTemplate）
• LabelPosition 枚举值

工具提示

📄 阅读： references/tooltip.md

• 启用或禁用悬停时的工具提示（showTooltip）
• 自定义工具提示模板（tooltipTemplate）
• 通过 cssClass 自定义工具提示的外观

模板（自定义符号）

📄 阅读： references/templates.md

• 未评分项目使用 emptyTemplate
• 已评分项目使用 fullTemplate
• 将表情符号图标用作评分符号
• 将 SVG 图标用作评分符号
• 将 PNG 图片用作评分符号
• 模板上下文：value 和 index

外观和样式

📄 阅读： references/appearance.md

• 更改项目数量（itemsCount）
• 禁用状态（disabled）
• 可见性控制（visible）
• 只读模式（readOnly）
• 使用 cssClass 自定义 CSS
• 更改图标边框颜色、填充颜色和项目间距
• 使用 CSS 替换默认图标

事件

📄 阅读： references/events.md

• valueChanged – 评分变化时触发
• beforeItemRender – 每个项目渲染前触发
• onItemHover – 悬停在项目上时触发
• created – 渲染完成后触发
• 事件参数类型：RatingChangedEventArgs、RatingItemEventArgs、RatingHoverEventArgs

无障碍功能

📄 阅读： references/accessibility.md

• WAI-ARIA 属性（role=slider、aria-valuenow 等）
• 键盘导航快捷键
• 符合 WCAG 2.2 / Section 508 标准
• 支持 RTL

API 参考

📄 阅读： references/api.md

• 全部 16 个属性及其类型和默认值
• 全部 7 个方法
• 全部 4 个事件及其参数类型

---

常见模式

带重置按钮和标签的评分

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

let rating: Rating = new Rating({
  value: 3.0,
  allowReset: true,
  showLabel: true
});
rating.appendTo('#rating');

带变化处理程序的半精度评分

import { Rating, PrecisionType, RatingChangedEventArgs } from '@syncfusion/ej2-inputs';

let rating: Rating = new Rating({
  value: 2.5,
  precision: PrecisionType.Half,
  valueChanged: (args: RatingChangedEventArgs) => {
    console.log('New rating:', args.value);
  }
});
rating.appendTo('#rating');

只读显示评分

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

let rating: Rating = new Rating({
  value: 4.0,
  readOnly: true,
  showLabel: true
});
rating.appendTo('#rating');

自定义项目数量并设置最小值

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

let rating: Rating = new Rating({
  value: 3,
  itemsCount: 10,
  min: 1
});
rating.appendTo('#rating');

签名

Syncfusion EJ2 TypeScript Signature（@syncfusion/ej2-inputs）是一种基于画布的控件，允许用户通过鼠标、触控或手写笔输入，使用可变宽度的贝塞尔曲线插值绘制流畅的签名。它支持文本绘制、笔画和背景自定义、保存/加载操作、撤销/重做历史记录，以及全面符合 WCAG 2.2 无障碍标准。

导航指南

入门

📄 阅读： references/getting-started.md

• 软件包依赖项（@syncfusion/ej2-inputs、@syncfusion/ej2-base）
• 使用 webpack quickstart 设置项目
• CSS 主题导入
• HTML 画布元素设置
• Signature 基本初始化
• 默认画布尺寸（300 × 150）

自定义

📄 阅读： references/customization.md

• 笔画宽度：maxStrokeWidth、minStrokeWidth、velocity
• 使用 strokeColor 设置笔画颜色（十六进制、RGB、命名颜色）
• 使用 backgroundColor 设置背景颜色
• 使用 backgroundImage 设置背景图片
• 使用 saveWithBackground 保存背景

打开和保存

📄 阅读： references/open-save.md

• 通过 load(url, width?, height?) 加载预先绘制的签名（Base64 或托管 URL）
• 通过 save(type?, fileName?) 保存为图片（PNG/JPEG/SVG）
• 通过 getSignature() 获取 Base64 字符串
• 通过 saveAsBlob() 保存为 Blob
• 通过 getBlob(url) 获取 Blob
• 使用 saveWithBackground 控制是否包含背景

用户交互

📄 阅读： references/user-interaction.md

• 使用 undo() 撤销，并通过 canUndo() 检查是否可撤销
• 使用 redo() 重做，并通过 canRedo() 检查是否可重做
• 使用 clear() 清空画布
• 使用 isEmpty() 检查是否为空
• 通过 disabled 属性禁用组件
• 使用 isReadOnly 属性启用只读模式
• 使用 change 事件响应笔画、撤销、重做和清空操作
• 首次渲染时触发 created 事件
• 使用 beforeSave 事件自定义键盘保存（Ctrl+S）行为

工具栏集成

📄 阅读： references/toolbar-integration.md

• 将 Signature 与 EJ2 Toolbar 组件集成
• 连接工具栏中的撤销/重做/清空/保存按钮
• 添加 ColorPicker 以设置笔画和背景颜色
• 添加 DropDownList 以控制笔画宽度
• 根据 canUndo、canRedo、isEmpty 启用或禁用工具栏项
• 使用 change 事件同步工具栏状态

无障碍访问

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• 键盘快捷键（Ctrl+Z、Ctrl+Y、Ctrl+S、Delete）
• 屏幕阅读器支持
• 支持移动设备和触摸设备

API 参考

📄 阅读： references/api.md

• 所有属性及其类型和默认值
• 所有方法（draw、load、save、saveAsBlob、getSignature、getBlob、undo、redo、clear、canUndo、canRedo、isEmpty、refresh、destroy）
• 所有事件（change、created、beforeSave）
• 支持的类型（SignatureFileType、SignatureChangeEventArgs、SignatureBeforeSaveEventArgs）

---

快速开始

npm install @syncfusion/ej2-inputs
npm audit

<canvas id="signature"></canvas>

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

let signature: Signature = new Signature({}, '#signature');

/* styles.css */
@import '../../node_modules/@syncfusion/ej2-base/styles/material.css';
@import '../../node_modules/@syncfusion/ej2-inputs/styles/material.css';

如果未在 canvas 元素上明确设置 width 或 height，Signature 组件将以默认 HTML canvas 大小（300 × 150）渲染。

---

常见模式

将文本绘制为签名

// Draw "John Doe" in Arial, size 30
signature.draw('John Doe', 'Arial', 30);

将签名保存为 PNG

signature.save('Png', 'my-signature');

获取 Base64 并重新加载

const base64 = signature.getSignature();       // returns base64 PNG string
signature.load(base64);                         // reload the same signature

带保护检查的撤销/重做

if (signature.canUndo()) { signature.undo(); }
if (signature.canRedo()) { signature.redo(); }

禁用和只读

signature.disabled   = true;   // user cannot draw; opacity shows disabled state
signature.isReadOnly = true;   // focusable but drawing is prevented

响应签名更改

let signature: Signature = new Signature({
  change: (args) => {
    console.log('Signature changed; empty?', signature.isEmpty());
  }
}, '#signature');

TextBox

Syncfusion EJ2 TypeScript TextBox（@syncfusion/ej2-inputs）是一款功能丰富的文本输入组件，支持浮动标签、多行（textarea）模式、图标组、装饰项、验证状态、尺寸调整、RTL、自动完成，并完全符合 WCAG 2.2 无障碍访问标准。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包依赖项
• 项目设置（webpack 快速入门）
• CSS 主题导入
• TextBox 基本初始化
• 使用 addIcon() 添加图标
• 使用 floatLabelType 设置浮动标签

多行（Textarea）模式

📄 阅读： references/multiline.md

• 使用 multiline: true 启用多行模式
• 在多行输入框上使用浮动标签
• 根据内容自动调整大小
• 通过 CSS 禁用调整大小
• 使用 addAttributes({ maxlength }) 限制文本长度
• 在 input 事件中统计字符数

分组、图标和清除按钮

📄 阅读： references/groups.md

• 使用 addIcon('append' | 'prepend', iconClass) 添加图标
• 添加带浮动标签的图标
• 使用 showClearButton 显示清除（×）图标
• 不带 required 属性的浮动标签
• 带浮动标签的多行输入框

装饰项（前缀/后缀模板）

📄 阅读： references/adornments.md

• prependTemplate——在输入框前添加图标或文本
• appendTemplate——在输入框后添加图标或按钮
• 密码可见性切换模式
• 使用 dataBind() 实现删除/清除图标模式

验证状态

📄 阅读： references/validation.md

• 通过 cssClass 应用 e-warning、e-error、e-success
• 更改不同验证状态下浮动标签的颜色（CSS）
• 根据值更改 TextBox 颜色（keyup + regex）

尺寸

📄 阅读： references/sizing.md

• 常规尺寸（默认）
• 通过 cssClass: 'e-small' 设置小尺寸
• 通过 cssClass: 'e-bigger' 设置大尺寸
• 将尺寸与图标和浮动标签结合使用

样式与外观

📄 阅读： references/style-appearance.md

• 填充模式：cssClass: 'e-filled'
• 描边模式：cssClass: 'e-outline'
• 自定义背景颜色和文本颜色（CSS 覆盖）
• 自定义浮动标签颜色（CSS）
• 通过 cssClass: 'e-corner' 设置圆角
• 使用 cssClass 限定样式作用范围

操作指南

📄 阅读： references/how-to.md

• 使用 Input.createInput() 以编程方式添加 TextBox
• 以编程方式添加浮动标签
• 为只读 TextBox 添加浮动标签
• 设置禁用状态（enabled: false）
• 设置只读状态（readonly: true）
• 设置圆角（cssClass: 'e-corner'）
• 更改验证状态下的浮动标签颜色
• 根据值更改 TextBox 颜色（keyup 正则表达式）
• 自定义背景颜色和文本颜色

无障碍访问

📄 阅读： references/accessibility.md

• WAI-ARIA 角色 textbox 和属性
• aria-placeholder、aria-labelledby
• WCAG 2.2、Section 508、屏幕阅读器支持
• RTL 支持

API 参考

📄 阅读： references/api.md

• 所有属性及其类型和默认值
• 所有方法（addIcon、addAttributes、removeAttributes、focusIn、focusOut、dataBind 等）
• 所有事件（change、input、blur、focus、created、destroyed）
• 事件参数类型

---

快速入门

npm install @syncfusion/ej2-inputs
npm audit

<input id="firstName" />

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

let textBox: TextBox = new TextBox({
  placeholder: 'Enter your name',
  floatLabelType: 'Auto'
});

textBox.appendTo('#firstName');

/* styles.css */
@import '../../node_modules/@syncfusion/ej2-base/styles/material.css';
@import '../../node_modules/@syncfusion/ej2-inputs/styles/material.css';

---

常见模式

浮动标签类型

// Auto – floats label above on focus or when value entered
let autoFloat: TextBox = new TextBox({ placeholder: 'Name', floatLabelType: 'Auto' });
autoFloat.appendTo('#auto');

// Always – label always floats above
let alwaysFloat: TextBox = new TextBox({ placeholder: 'Name', floatLabelType: 'Always' });
alwaysFloat.appendTo('#always');

// Never – label stays as placeholder (default)
let neverFloat: TextBox = new TextBox({ placeholder: 'Name', floatLabelType: 'Never' });
neverFloat.appendTo('#never');

带图标的 TextBox

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

let iconTextBox: TextBox = new TextBox({
  placeholder: 'Enter Date',
  created: () => {
    iconTextBox.addIcon('append', 'e-icons e-date-range');
  }
});
iconTextBox.appendTo('#textbox');

多行 / 文本区域

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

let textarea: TextBox = new TextBox({
  placeholder: 'Enter your address',
  multiline: true,
  floatLabelType: 'Auto'
});
textarea.appendTo('#textarea');

带可见性切换的密码输入框

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

let passwordBox: TextBox = new TextBox({
  placeholder: 'Password',
  type: 'password',
  floatLabelType: 'Auto',
  appendTemplate: '<span class="e-input-separator"></span><span id="eye-icon" class="e-icons e-eye"></span>',
  created: () => {
    const eyeIcon = document.querySelector('#eye-icon') as HTMLElement;
    if (eyeIcon) {
      eyeIcon.addEventListener('click', () => {
        if (passwordBox.type === 'password') {
          passwordBox.type = 'text';
          eyeIcon.className = 'e-icons e-eye-slash';
        } else {
          passwordBox.type = 'password';
          eyeIcon.className = 'e-icons e-eye';
        }
        passwordBox.dataBind();
      });
    }
  }
});
passwordBox.appendTo('#password');

验证状态

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

let errorBox: TextBox = new TextBox({ placeholder: 'Error state', cssClass: 'e-error' });
errorBox.appendTo('#error');

let warningBox: TextBox = new TextBox({ placeholder: 'Warning state', cssClass: 'e-warning' });
warningBox.appendTo('#warning');

let successBox: TextBox = new TextBox({ placeholder: 'Success state', cssClass: 'e-success' });
successBox.appendTo('#success');

禁用和只读

// Disabled
let disabled: TextBox = new TextBox({ placeholder: 'Disabled', enabled: false });
disabled.appendTo('#disabled');

// Read-only
let readOnly: TextBox = new TextBox({ placeholder: 'Read-only', readonly: true });
readOnly.appendTo('#readonly');

清除按钮

let clearable: TextBox = new TextBox({
  placeholder: 'Type to clear',
  showClearButton: true,
  floatLabelType: 'Auto'
});
clearable.appendTo('#clearable');

---

主要属性一览

属性	类型	默认值	用途
value	string	null	文本内容
placeholder	string	null	提示文本 / 浮动标签
floatLabelType	FloatLabelType	'Never'	标签浮动行为
multiline	boolean	false	启用文本区域模式
type	string	'text'	输入类型（text、password、email 等）
enabled	boolean	true	启用/禁用控件
readonly	boolean	false	只读模式
showClearButton	boolean	false	显示清除（×）图标
cssClass	string	''	自定义 CSS 类
width	number|string	null	组件宽度
enableRtl	boolean	false	从右向左布局
autocomplete	string	'on'	浏览器自动补全（'on'|'off'）
locale	string	''	覆盖文化设置/区域设置
enablePersistence	boolean	false	在重新加载后保留值
prependTemplate	string|Function	null	输入框前的 HTML
appendTemplate	string|Function	null	输入框后的 HTML
htmlAttributes	object	{}	额外的 HTML 属性

Uploader

Syncfusion Uploader 组件为 TypeScript 应用提供了功能强大的文件上传解决方案。它支持多种上传模式、文件验证、拖放、大文件分块上传，以及丰富的自定义选项。

组件概览

Uploader 组件提供：

• 多种上传模式：异步、分块和基于表单的上传
• 全面验证：文件类型、大小和数量限制
• 丰富的 UI：可自定义的模板、主题和样式选项
• 高级功能：JWT 身份验证、本地化、图像预览/调整大小、进度跟踪
• 开发者友好：提供完整的 TypeScript 支持、类型定义、事件和方法

文档导航指南

快速入门

📄 阅读： references/uploader-getting-started.md

• 依赖项和软件包要求
• 通过快速入门项目、npm 或 CDN 安装
• TypeScript 模块导入
• 基本组件初始化
• HTML 结构和 CSS 导入
• 放置区域配置
• 异步设置配置
• 成功和失败事件处理
• 第一个上传示例
• 关键配置选项

文件验证

📄 阅读： references/uploader-file-validation.md

• 使用 allowedExtensions 验证文件类型
• 文件大小限制（minFileSize、maxFileSize）
• 使用 isModified 标志限制文件数量
• 重复文件验证
• 上传前验证策略
• 自定义验证逻辑
• 验证事件处理

上传模式与功能

📄 阅读： references/uploader-upload-modes.md

• 异步上传配置（单个/多个/顺序）
• 使用 files 属性预加载文件
• 保存/移除操作及服务端示例
• 为上传请求添加自定义 HTTP 标头
• 分块上传及 retryCount 和 retryAfterDelay
• 使用 dropArea 属性支持拖放
• 从剪贴板粘贴并上传
• 使用 directoryUpload 属性上传目录
• 提交表单并上传文件
• 文件来源选项和事件
• 事件处理和回调（暂停/恢复/取消）

自定义与样式

📄 阅读： references/uploader-customization-and-styling.md

• 组件专用 CSS 选择器（包装器、浏览按钮、放置文本、文件容器）
• CSS 自定义和主题
• 按钮模板自定义
• 进度条样式
• 外观修改
• RTL（从右向左）支持
• 响应式设计模式

高级功能

📄 阅读： references/uploader-advanced-features.md

• JWT 身份验证（使用 currentRequest 处理上传和移除事件）
• 服务端 JWT 验证（ASP.NET Core 示例）
• 本地化及完整键参考表
• 文件预览功能
• 上传前调整图像大小
• 文件列表模板和自定义模板（showFileList）
• 表单数据绑定
• 文件移除和清理处理程序

操作指南与模式

📄 阅读： references/uploader-how-to-guides.md

• 以编程方式触发上传
• 不可见/隐藏的上传器 UI
• 随上传附加额外数据
• 移除操作的确认对话框
• 自定义按钮元素
• MIME 类型验证
• 将图像转换为二进制格式
• 使用 bytesToSize 方法检查文件大小
• 隐藏放置区域
• 打开/编辑已上传的文件
• 对已选文件排序
• 通过外部按钮触发
• 放置时验证图像
• 符合 WAI-ARIA 无障碍标准并支持键盘快捷键

故障排除与模式

📄 阅读： references/uploader-troubleshooting-and-examples.md

• 常见问题和解决方案（包括 name 属性不匹配）
• 浏览器兼容性说明
• 性能优化技巧
• 边缘情况和注意事项
• 表单支持模式（使用 FormValidator 进行非异步上传）
• 实际应用模式
• 调试提示和技巧

API 参考

📄 阅读： references/uploader-api.md

• 完整的属性参考，包含类型、说明和默认值
• 所有公共方法，包含参数表和返回类型
• 所有事件，包含事件参数详情和用法示例
• 支持的接口：AsyncSettingsModel、ButtonsPropsModel、FilesPropModel、FileInfo、ValidationMessages
• 事件参数接口：SelectedEventArgs、UploadingEventArgs、RemovingEventArgs、BeforeRemoveEventArgs、BeforeUploadEventArgs、ActionCompleteEventArgs、CancelEventArgs、ClearingEventArgs、FileListRenderingEventArgs、PauseResumeEventArgs
• DropEffect 枚举值
• 已注明弃用的 API 及推荐替代方案

---

安装

npm install @syncfusion/ej2-inputs
npm audit

快速入门示例

以下是一个简洁的 TypeScript 示例，帮助你快速入门：

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

// Initialize Uploader component
// ⚠️ DEMO ONLY: Replace saveUrl and removeUrl with your own production server endpoints.
//    Do NOT use services.syncfusion.com URLs in production applications.
const uploaderObj = new Uploader({
  asyncSettings: {
    saveUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/Save',  // Replace in production
    removeUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/Remove'  // Replace in production
  },
  allowedExtensions: '.jpg,.png,.pdf'
});

// Render to DOM element with id 'fileupload'
uploaderObj.appendTo('#fileupload');

// Handle file selection
uploaderObj.selected = (args: any) => {
  console.log('Files selected:', args.filesData);
};

// Handle upload completion
uploaderObj.success = (args: any) => {
  console.log('Upload successful:', args.responseText);
};

HTML 元素：

<input type="file" id="fileupload" name="UploadFiles" />

---

常见模式

模式 1：经过验证的文件上传

将上传限制为特定文件类型和大小：

// ⚠️ Replace saveUrl and removeUrl with your own server endpoints before deploying to production.
const uploader = new Uploader({
  asyncSettings: {
    saveUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/save',  // Replace in production
    removeUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/remove'  // Replace in production
  },
  allowedExtensions: '.jpg,.jpeg,.png,.gif',
  minFileSize: 5000,      // 5 KB
  maxFileSize: 5242880    // 5 MB
});
uploader.appendTo('#fileupload');

模式 2：拖放上传

启用现代化的文件上传体验：

// ⚠️ Replace saveUrl and removeUrl with your own server endpoints before deploying to production.
const uploader = new Uploader({
  asyncSettings: {
    saveUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/save',  // Replace in production
    removeUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/remove'  // Replace in production
  },
  dropEffect: 'Copy',
  multiple: true,
  allowedExtensions: '.pdf,.doc,.docx'
});
uploader.appendTo('#fileupload');

// Files that are dropped also trigger the selected event
uploader.selected = (args: SelectedEventArgs) => {
  console.log('Files selected/dropped:', args.filesData);
};

模式 3：大文件分块上传

使用可恢复的分块处理大文件：

// ⚠️ Replace saveUrl and removeUrl with your own server endpoints before deploying to production.
const uploader = new Uploader({
  asyncSettings: {
    saveUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/save-chunk',  // Replace in production
    removeUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/remove',  // Replace in production
    chunkSize: 5242880 // 5 MB chunks
  },
  allowedExtensions: '.iso,.zip,.rar',
  minFileSize: 26214400  // 25 MB minimum
});
uploader.appendTo('#fileupload');

uploader.chunkSuccess = (args: any) => {
  console.log('Chunk uploaded:', args.chunkIndex, 'size:', args.chunkSize);
};

uploader.chunkFailure = (args: any) => {
  console.log('Chunk failed for:', args.file.name, 'chunk:', args.chunkIndex);
};

模式 4：上传前预览文件

在上传前显示图片和详细信息：

// ⚠️ Replace saveUrl and removeUrl with your own server endpoints before deploying to production.
const uploader = new Uploader({
  asyncSettings: {
    saveUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/save',  // Replace in production
    removeUrl: 'https://services.syncfusion.com/js/production/api/FileUploader/remove'  // Replace in production
  },
  allowedExtensions: '.jpg,.jpeg,.png'
});
uploader.appendTo('#fileupload');

uploader.selected = (args: any) => {
  // Render preview for each file
  args.filesData.forEach((file: any) => {
    const reader = new FileReader();
    reader.onload = (e: any) => {
      const preview = document.createElement('img');
      preview.src = e.target.result;
      preview.style.maxWidth = '100px';
      document.getElementById('preview')?.appendChild(preview);
    };
    reader.readAsDataURL(file.rawFile);
  });
};

---

关键属性和事件

如需包含所有属性、方法、事件和类型定义的完整 API 参考，请参阅 references/uploader-api.md。

基本属性

属性	类型	用途
asyncSettings	AsyncSettingsModel	配置上传端点和行为
allowedExtensions	string	允许的文件扩展名，以逗号分隔
minFileSize	number	文件最小大小，单位为字节
maxFileSize	number	文件最大大小，单位为字节
multiple	boolean	允许选择多个文件
autoUpload	boolean	选择文件后自动上传
sequentialUpload	boolean	依次上传文件
showFileList	boolean	显示或隐藏默认文件列表
template	string | Function	自定义文件项模板
directoryUpload	boolean	启用文件夹/目录上传
dropArea	string | HTMLElement	自定义拖放目标
dropEffect	DropEffect	拖放时的视觉效果
files	FilesPropModel[]	渲染时预加载的文件
enabled	boolean	启用或禁用组件
enableRtl	boolean	从右到左渲染
enableHtmlSanitizer	boolean	防止文件名中的 XSS
buttons	ButtonsPropsModel	自定义按钮标签/内容
cssClass	string	根元素上的自定义 CSS 类
htmlAttributes	object	其他 HTML 属性
locale	string	覆盖全局本地化设置

关键事件

事件	触发时机	用例
selected	选择文件	验证、预览或修改文件
uploading	上传开始前	添加标头、元数据，显示进度
beforeUpload	上传过程开始前	向上传请求添加参数
success	上传成功完成	处理服务器响应
failure	上传失败	重试逻辑、错误处理
removing	正在移除文件	确认移除、添加自定义数据
beforeRemove	向服务器发送移除请求前	阻止或修改移除请求
actionComplete	所有文件均已处理	处理批次完成事件
chunkUploading	每个分块开始上传	向分块请求添加数据
chunkSuccess	分块上传完成	跟踪进度
chunkFailure	分块上传失败	重试或错误处理
pausing	分块上传已暂停	跟踪暂停状态
resuming	已恢复暂停的上传	跟踪恢复状态
canceling	分块上传已取消	跟踪取消状态
clearing	正在清空文件列表	阻止或确认清空操作
fileListRendering	每个文件项渲染时	自定义文件项结构
progress	文件正在上传（AJAX 进度）	实时更新进度条
change	文件列表发生变化	响应添加/移除操作
created	组件已创建	初始化后的设置

---

常见用例

用例 1：产品图片上传
验证图片、上传前调整大小、显示预览 → 参阅 references/uploader-advanced-features.md

用例 2：文档管理
支持多种文件类型、大文件支持、表单集成 → 参阅 references/uploader-upload-modes.md 和 references/uploader-advanced-features.md

用例 3：用户头像上传
单张图片、大小验证、自定义样式 → 参阅 references/uploader-getting-started.md 和 references/uploader-customization-and-styling.md

用例 4：安全文件上传
JWT 身份验证、服务器验证、错误处理 → 参阅 references/uploader-advanced-features.md 和 references/uploader-troubleshooting-and-examples.md

---

相关技能

• 实现表单验证
• 在 TypeScript 中处理异步操作
• 自定义事件处理

---

下一步： 从 references/uploader-getting-started.md 开始，了解安装和基本设置；直接跳转到与用例匹配的参考文档；或参阅 references/uploader-api.md 查看完整的 API 参考。

CheckBox

CheckBox 组件（@syncfusion/ej2-buttons）是一种选择控件，允许用户从一组选项中选择一个或多个选项。它支持三种状态（选中、未选中、不确定）、标签、自定义样式、表单集成，并完全符合 WCAG 2.2 无障碍标准。

快速入门

npm install @syncfusion/ej2-buttons
npm audit

<input type="checkbox" id="checkbox" />

import { CheckBox, ChangeEventArgs } from '@syncfusion/ej2-buttons';

let checkbox: CheckBox = new CheckBox({
  label: 'Accept terms and conditions',
  checked: false,
  change: (args: ChangeEventArgs) => {
    console.log('Checked:', args.checked);
  }
});
checkbox.appendTo('#checkbox');

文档和导航指南

入门

📄 阅读： references/checkbox-getting-started.md

• 安装和软件包设置（@syncfusion/ej2-buttons）
• 必需的 CSS 导入和主题配置
• CheckBox 基本初始化
• 标签配置
• 波纹效果设置
• 运行应用程序

标签和大小

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

• label 属性 — 字符串和 HTML 标签
• labelPosition — 前置或后置（默认）
• cssClass: 'e-small' — 小尺寸变体
• 使用 CSS 覆盖自定义大小
• 带链接和格式的富文本标签

状态

📄 阅读： references/checkbox-states.md

• 三种状态：选中、未选中、不确定
• disabled 属性 — 禁止交互
• readonly 属性 — 不可编辑但可聚焦
• 以编程方式控制状态
• 搭配 ChangeEventArgs 的 change 事件
• 主从 / 全选模式
• 表单集成

样式和外观

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

• 自定义选中颜色
• 边框宽度和圆角
• 胶囊式／开关式复选框
• 自定义形状（方形、圆形）
• 悬停和焦点效果
• 深色和浅色主题
• 渐变和玻璃拟态效果
• 动画勾选标记

使用模式

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

• 使用 name 和 value 提交表单
• 主项-明细全选模式
• 必填字段验证
• 动态启用／禁用
• 三态复选框循环
• 分组选择（类似单选按钮的行为）
• 使用 localStorage 持久化状态
• AJAX 表单提交
• 标签中的自定义 HTML（链接等）

无障碍访问

📄 阅读： references/checkbox-accessibility.md

• WAI-ARIA 属性（role="checkbox"、aria-checked）
• 键盘导航（Tab、Space、Enter）
• 符合 WCAG 2.2、Section 508 和 ADA 标准
• 屏幕阅读器支持（JAWS、NVDA、VoiceOver）
• 焦点管理和可见指示器
• 颜色对比度（最低 4.5:1）
• 适合触控的目标尺寸（44x44px）
• RTL 支持

API 参考

📄 阅读： references/checkbox-api.md

• 所有属性及其类型和默认值
• 所有方法（check、uncheck、toggle、focusIn、focusOut、click、destroy）
• 所有事件（change、created、destroyed）
• ChangeEventArgs 接口
• CheckBoxModel 接口
• LabelPosition 枚举

---

常见模式

简单复选框

import { CheckBox } from '@syncfusion/ej2-buttons';

let checkbox: CheckBox = new CheckBox({
  label: 'I agree to the terms',
  checked: false
});
checkbox.appendTo('#checkbox');

预先选中并进行验证

import { CheckBox, ChangeEventArgs } from '@syncfusion/ej2-buttons';
import { Button } from '@syncfusion/ej2-buttons';

let terms: CheckBox = new CheckBox({
  label: 'I accept the terms and conditions',
  change: (args: ChangeEventArgs) => {
    const submitBtn: Button = (document.getElementById('submit-btn') as any).ej2_instances[0];
    submitBtn.disabled = !args.checked;
  }
});
terms.appendTo('#terms');

let submitButton: Button = new Button({
  content: 'Continue',
  disabled: true,
  cssClass: 'e-primary'
});
submitButton.appendTo('#submit-btn');

主项-明细（全选）

import { CheckBox, ChangeEventArgs } from '@syncfusion/ej2-buttons';

const childCheckboxes: CheckBox[] = [];

let selectAll: CheckBox = new CheckBox({
  label: 'Select All',
  change: (args: ChangeEventArgs) => {
    childCheckboxes.forEach(cb => {
      cb.checked = args.checked;
    });
  }
});
selectAll.appendTo('#select-all');

['Option 1', 'Option 2', 'Option 3'].forEach((label, index) => {
  let child: CheckBox = new CheckBox({
    label: label,
    change: () => updateSelectAllState()
  });
  child.appendTo(`#child-${index}`);
  childCheckboxes.push(child);
});

function updateSelectAllState(): void {
  const checkedCount: number = childCheckboxes.filter(cb => cb.checked).length;
  if (checkedCount === 0) {
    selectAll.checked = false;
    selectAll.indeterminate = false;
  } else if (checkedCount === childCheckboxes.length) {
    selectAll.checked = true;
    selectAll.indeterminate = false;
  } else {
    selectAll.checked = false;
    selectAll.indeterminate = true;
  }
}

不确定状态

import { CheckBox } from '@syncfusion/ej2-buttons';

let parentCheckbox: CheckBox = new CheckBox({
  label: 'Select all (partial)',
  indeterminate: true
});
parentCheckbox.appendTo('#parent');

禁用的复选框

import { CheckBox } from '@syncfusion/ej2-buttons';

let disabledCheckbox: CheckBox = new CheckBox({
  label: 'This option is unavailable',
  disabled: true,
  checked: false
});
disabledCheckbox.appendTo('#disabled-checkbox');

小尺寸

import { CheckBox } from '@syncfusion/ej2-buttons';

let smallCheckbox: CheckBox = new CheckBox({
  label: 'Compact option',
  cssClass: 'e-small'
});
smallCheckbox.appendTo('#small-checkbox');

自定义样式

import { CheckBox } from '@syncfusion/ej2-buttons';

let customCheckbox: CheckBox = new CheckBox({
  label: 'Custom branded',
  checked: true,
  cssClass: 'brand-checkbox'
});
customCheckbox.appendTo('#custom-checkbox');

.brand-checkbox .e-checkbox-wrapper .e-frame.e-check {
  background-color: #ff6b35;
  border-color: #ff6b35;
}

表单提交

import { CheckBox } from '@syncfusion/ej2-buttons';

let newsletter: CheckBox = new CheckBox({
  label: 'Subscribe to newsletter',
  name: 'newsletter',
  value: 'subscribed'
});
newsletter.appendTo('#newsletter');

<form id="signup-form">
  <input type="checkbox" id="newsletter" />
  <button type="submit">Submit</button>
</form>

---

常用属性一览

属性	类型	默认值	用途
label	string | HTMLElement	''	复选框标签文本
checked	boolean	false	选中状态
indeterminate	boolean	false	不确定状态（父级复选框）
disabled	boolean	false	禁用交互
readonly	boolean	false	只读模式
labelPosition	string	'After'	标签位置：Before 或 After
name	string	''	表单提交名称
value	string	''	表单提交值
cssClass	string	''	自定义 CSS 类（小尺寸请使用 e-small）
enableRtl	boolean	false	从右向左布局
enablePersistence	boolean	false	在重新加载后保留状态
locale	string	'en-US'	区域设置代码

常用方法一览

方法	用途
check()	将选中状态设为 true
uncheck()	将选中状态设为 false
toggle()	在选中／未选中状态之间切换
focusIn()	以编程方式将焦点设到复选框上
focusOut()	将焦点从复选框移除
click()	以编程方式点击复选框
destroy()	销毁组件实例

常用事件一览

事件	触发条件	用例
change	选中状态发生变化	表单验证、条件逻辑
created	组件就绪	初始化后设置
destroyed	组件销毁	清理

---

常见用例

用例 1：条款确认 — 要求用户在提交表单前接受条款 用例 2：订阅新闻简报 — 允许用户选择订阅或取消订阅通信内容 用例 3：多选列表 — 让用户从列表中选择多个项目 用例 4：设置开关 — 在用户偏好设置中启用或禁用功能 用例 5：筛选控件 — 根据选定的条件筛选数据 用例 6：批量操作 — 选择多个项目以执行批处理操作 用例 7：主从关系 — 使用父项与子项关系的全选模式 用例 8：表单验证 — 要求选中特定复选框才能提交表单

---

常见 CSS 类

类	用途
e-small	小尺寸复选框
e-success	绿色成功色
e-warning	黄色警告色
e-danger	红色错误色
e-info	蓝色信息色

---

相关技能

• 实现表单验证
• 构建切换 / 开关 UI
• RadioButton（单选对应项）
• ButtonGroup（多按钮选择）

---

下一步： 从 references/checkbox-getting-started.md 开始，了解安装和基本设置；直接跳转到与你的用例匹配的参考文档；或查阅 references/checkbox-api.md 获取完整的 API 参考。