syncfusion-angular-inputs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion Angular Inputs

实现Syncfusion Angular输入组件

Uploader

Uploader组件

The Syncfusion Angular Uploader (
ejs-uploader
) is a full-featured file upload component that supports asynchronous uploads, chunk uploading of large files, drag-and-drop, clipboard paste, directory upload, file validation, templates, form integration, JWT authentication, and comprehensive event handling.
Syncfusion Angular Uploader(
ejs-uploader
)是一个功能完备的文件上传组件,支持异步上传、大文件分块上传、拖放、剪贴板粘贴、目录上传、文件验证、模板、表单集成、JWT认证以及全面的事件处理。

Component Overview

组件概述

The Syncfusion Angular Uploader provides:
  • Async upload modes: Auto upload (default) or manual upload with action buttons
  • Chunk upload: Split large files into configurable byte-size chunks with retry logic
  • Sequential upload: Process files one at a time to reduce server traffic
  • File sources: Browse dialog, drag-and-drop, clipboard paste, directory selection
  • Validation: File type (extensions), min/max size, custom count limits, duplicate prevention
  • Templates: Customize the file list item structure; build fully custom upload UIs
  • Form support: HTML form submission, template-driven forms (ngModel), reactive forms (FormGroup)
  • Accessibility: WCAG 2.2, Section 508, keyboard navigation, screen reader support
  • Localization: Customize all static text via L10n
Syncfusion Angular Uploader提供:
  • 异步上传模式:自动上传(默认)或带操作按钮的手动上传
  • 分块上传:将大文件拆分为可配置字节大小的块,并支持重试逻辑
  • 顺序上传:逐个处理文件以减少服务器流量
  • 文件来源:浏览对话框、拖放、剪贴板粘贴、目录选择
  • 验证:文件类型(扩展名)、最小/最大尺寸、自定义数量限制、重复文件预防
  • 模板:自定义文件列表项结构;构建完全自定义的上传UI
  • 表单支持:HTML表单提交、模板驱动表单(ngModel)、响应式表单(FormGroup)
  • 无障碍性:符合WCAG 2.2、Section 508标准,支持键盘导航、屏幕阅读器
  • 本地化:通过L10n自定义所有静态文本

Documentation & Navigation Guide

文档与导航指南

⚠️ Agentic use note: This guide links to multiple reference documents. AI agents should read only the sections relevant to the task at hand — do not chain through all references automatically. Follow least-privilege reading: fetch only what is needed.
⚠️ 智能代理使用说明:本指南链接了多个参考文档。AI代理应仅阅读与当前任务相关的部分——不要自动遍历所有参考内容。遵循最小权限读取原则:仅获取所需内容。

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Installation of
    @syncfusion/ej2-angular-inputs
    ⚠️ Always verify the package version and integrity before running
    npm install
    in production pipelines (supply-chain hygiene).
  • Package setup, CSS imports, and Angular standalone component usage
  • Adding the
    <ejs-uploader>
    component
  • Configuring async settings (saveUrl, removeUrl)
  • Handling success and failure events
  • Adding a custom drop area
📄 阅读references/getting-started.md
  • 安装
    @syncfusion/ej2-angular-inputs
    ⚠️ 在生产流水线中运行
    npm install
    前,务必验证包版本和完整性(供应链安全)。
  • 包设置、CSS导入和Angular独立组件使用
  • 添加
    <ejs-uploader>
    组件
  • 配置异步设置(saveUrl、removeUrl)
  • 处理成功和失败事件
  • 添加自定义拖放区域

Asynchronous Upload

异步上传

📄 Read: references/async-upload.md
  • Multiple and single file upload modes (
    multiple
    property)
  • Save action configuration and server-side handling
  • Remove action and
    postRawFile
    usage
  • Auto upload vs manual upload (
    autoUpload
    property)
  • Sequential upload (
    sequentialUpload
    )
  • Preloaded files (
    files
    property)
  • Adding custom HTTP headers to upload requests
📄 阅读references/async-upload.md
  • 多文件和单文件上传模式(
    multiple
    属性)
  • 保存操作配置与服务器端处理
  • 删除操作与
    postRawFile
    的使用
  • 自动上传 vs 手动上传(
    autoUpload
    属性)
  • 顺序上传(
    sequentialUpload
  • 预加载文件(
    files
    属性)
  • 为上传请求添加自定义HTTP头

Chunk Upload

分块上传

📄 Read: references/chunk-upload.md
  • Enabling chunk upload via
    asyncSettings.chunkSize
  • Pause, resume, and cancel chunk uploads
  • Retry configuration (
    retryCount
    ,
    retryAfterDelay
    )
  • chunkSuccess
    and
    chunkFailure
    events
  • Server-side chunk assembly implementation
📄 阅读references/chunk-upload.md
  • 通过
    asyncSettings.chunkSize
    启用分块上传
  • 暂停、恢复和取消分块上传
  • 重试配置(
    retryCount
    retryAfterDelay
  • chunkSuccess
    chunkFailure
    事件
  • 服务器端分块合并实现

File Validation

文件验证

📄 Read: references/validation.md
  • Restricting file types with
    allowedExtensions
  • Min/max file size constraints (
    minFileSize
    ,
    maxFileSize
    )
  • Limiting upload count via the
    selected
    event
  • Preventing duplicate file uploads
  • MIME type validation before upload
  • Image/* validation on drag-and-drop
📄 阅读references/validation.md
  • 使用
    allowedExtensions
    限制文件类型
  • 最小/最大文件大小约束(
    minFileSize
    maxFileSize
  • 通过
    selected
    事件限制上传数量
  • 防止重复文件上传
  • 上传前MIME类型验证
  • 拖放时的Image/*类型验证

File Sources

文件来源

📄 Read: references/file-sources.md
  • Paste images from clipboard
  • Directory (folder) upload with
    directoryUpload
  • Drag-and-drop with built-in and custom drop areas
  • Custom drop area styling (
    .e-upload-drag-hover
    )
  • Triggering file browse from an external button
📄 阅读references/file-sources.md
  • 从剪贴板粘贴图片
  • 启用目录(文件夹)上传(
    directoryUpload
  • 内置和自定义拖放区域的拖放功能
  • 自定义拖放区域样式(
    .e-upload-drag-hover
  • 通过外部按钮触发文件浏览

Templates & Custom UI

模板与自定义UI

📄 Read: references/templates-and-custom-ui.md
  • File list template with the
    template
    property
  • Building a completely custom upload UI (hiding default list with
    showFileList
    )
  • Customizing action buttons with HTML elements (
    buttons
    property)
  • Customizing the progress bar appearance
  • Preview images before uploading
  • Resize images before uploading to server
📄 阅读references/templates-and-custom-ui.md
  • 使用
    template
    属性实现文件列表模板
  • 构建完全自定义的上传UI(通过
    showFileList
    隐藏默认列表)
  • 使用HTML元素自定义操作按钮(
    buttons
    属性)
  • 自定义进度条外观
  • 上传前预览图片
  • 上传到服务器前调整图片大小

Form Integration

表单集成

📄 Read: references/form-integration.md
  • Using Uploader inside HTML forms (synchronous submission)
  • Template-driven forms with
    ngModel
  • Reactive forms with
    FormGroup
  • Required field validation (
    required
    attribute)
  • Reset behavior with form reset
📄 阅读references/form-integration.md
  • 在HTML表单中使用Uploader(同步提交)
  • ngModel
    的模板驱动表单
  • FormGroup
    的响应式表单
  • 必填字段验证(
    required
    属性)
  • 表单重置时的重置行为

Styling & Appearance

样式与外观

📄 Read: references/styling-and-appearance.md
  • Customizing the uploader wrapper dimensions
  • Styling the browse button
  • Customizing the drop area text
  • Customizing the file list container
  • Hiding the default drop area
  • CSS class reference for key Uploader elements
📄 阅读references/styling-and-appearance.md
  • 自定义上传器容器尺寸
  • 样式化浏览按钮
  • 自定义拖放区域文本
  • 自定义文件列表容器
  • 隐藏默认拖放区域
  • Uploader关键元素的CSS类参考

Accessibility & Localization

无障碍性与本地化

📄 Read: references/accessibility-and-localization.md
  • WCAG 2.2, Section 508, keyboard shortcuts
  • Screen reader and RTL support
  • Localizing all static labels and messages with L10n
📄 阅读references/accessibility-and-localization.md
  • WCAG 2.2、Section 508、键盘快捷键
  • 屏幕阅读器与RTL支持
  • 使用L10n本地化所有静态标签和消息

Advanced How-To Patterns

高级实现模式

📄 Read: references/advanced-patterns.md
  • Upload files programmatically with the
    upload()
    method
  • Invisible (background) upload
  • Adding additional form data with
    customFormData
  • JWT authentication for upload/remove requests
  • Show confirmation dialog before removing files
  • Get total size of selected files
  • Sort selected files in the file list
  • Open and edit uploaded files from the server
  • Convert uploaded images to binary format
📄 阅读references/advanced-patterns.md
  • 使用
    upload()
    方法程序化上传文件
  • 隐形(后台)上传
  • 使用
    customFormData
    添加额外表单数据
  • 上传/删除请求的JWT认证
  • 删除文件前显示确认对话框
  • 获取所选文件的总大小
  • 对文件列表中的所选文件排序
  • 从服务器打开并编辑已上传文件
  • 将上传的图片转换为二进制格式

API Reference

API参考

📄 Read: references/api.md
  • Complete properties, methods, and events reference
  • AsyncSettingsModel, ButtonsPropsModel, FilesPropModel
  • All event argument types and their fields
📄 阅读references/api.md
  • 完整的属性、方法和事件参考
  • AsyncSettingsModel、ButtonsPropsModel、FilesPropModel
  • 所有事件参数类型及其字段

Quick Start Example

快速入门示例

Minimal file uploader with async upload (Angular 21+ standalone):
typescript
import { Component } from '@angular/core';
import { UploaderModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  imports: [UploaderModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-uploader
      [asyncSettings]="asyncSettings"
      [autoUpload]="false"
      (success)="onSuccess($event)"
      (failure)="onFailure($event)">
    </ejs-uploader>
  `
})
export class AppComponent {
  public asyncSettings = {
    saveUrl: 'https://your-api/upload/save',    // Replace with your actual endpoint
    removeUrl: 'https://your-api/upload/remove' // Replace with your actual endpoint
  };

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

  onFailure(args: any): void {
    console.error('Upload failed:', args.file.name);
  }
}
CSS Theme Setup (
styles.css
):
css
@import 'node_modules/@syncfusion/ej2-base/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-angular-inputs/styles/material3.css';
带异步上传的极简文件上传器(Angular 21+独立组件):
typescript
import { Component } from '@angular/core';
import { UploaderModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  imports: [UploaderModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-uploader
      [asyncSettings]="asyncSettings"
      [autoUpload]="false"
      (success)="onSuccess($event)"
      (failure)="onFailure($event)">
    </ejs-uploader>
  `
})
export class AppComponent {
  public asyncSettings = {
    saveUrl: 'https://your-api/upload/save',    // Replace with your actual endpoint
    removeUrl: 'https://your-api/upload/remove' // Replace with your actual endpoint
  };

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

  onFailure(args: any): void {
    console.error('Upload failed:', args.file.name);
  }
}
CSS主题设置
styles.css
):
css
@import 'node_modules/@syncfusion/ej2-base/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-angular-inputs/styles/material3.css';

Common Patterns

常见模式

Pattern 1: Auto Upload with Drag-and-Drop

模式1:带拖放的自动上传

typescript
// Automatically uploads dropped or browsed files
<ejs-uploader
  [asyncSettings]="asyncSettings"
  [dropArea]="dropElement"
  [multiple]="true"
  (success)="onSuccess($event)">
</ejs-uploader>
typescript
// 自动上传拖放或浏览的文件
<ejs-uploader
  [asyncSettings]="asyncSettings"
  [dropArea]="dropElement"
  [multiple]="true"
  (success)="onSuccess($event)">
</ejs-uploader>

Pattern 2: Chunk Upload for Large Files

模式2:大文件分块上传

typescript
<ejs-uploader
  [asyncSettings]="chunkSettings"
  (chunkSuccess)="onChunkSuccess($event)"
  (chunkFailure)="onChunkFailure($event)">
</ejs-uploader>

// In component:
chunkSettings = {
  saveUrl: 'https://your-api/upload/save',    // Replace with your actual endpoint
  removeUrl: 'https://your-api/upload/remove', // Replace with your actual endpoint
  chunkSize: 500000  // 500 KB chunks
};
typescript
<ejs-uploader
  [asyncSettings]="chunkSettings"
  (chunkSuccess)="onChunkSuccess($event)"
  (chunkFailure)="onChunkFailure($event)">
</ejs-uploader>

// 在组件中:
chunkSettings = {
  saveUrl: 'https://your-api/upload/save',    // Replace with your actual endpoint
  removeUrl: 'https://your-api/upload/remove', // Replace with your actual endpoint
  chunkSize: 500000  // 500 KB chunks
};

Pattern 3: Validated Upload (Type + Size)

模式3:带验证的上传(类型 + 大小)

typescript
<ejs-uploader
  [asyncSettings]="asyncSettings"
  allowedExtensions=".jpg,.png,.pdf"
  [minFileSize]="1024"
  [maxFileSize]="5000000">
</ejs-uploader>
typescript
<ejs-uploader
  [asyncSettings]="asyncSettings"
  allowedExtensions=".jpg,.png,.pdf"
  [minFileSize]="1024"
  [maxFileSize]="5000000">
</ejs-uploader>

Pattern 4: Preloaded Files

模式4:预加载文件

typescript
<ejs-uploader
  [asyncSettings]="asyncSettings"
  [files]="preloadedFiles">
</ejs-uploader>

// In component:
preloadedFiles = [
  { name: 'report', size: 200000, type: '.pdf' },
  { name: 'photo', size: 500000, type: '.jpg' }
];
typescript
<ejs-uploader
  [asyncSettings]="asyncSettings"
  [files]="preloadedFiles">
</ejs-uploader>

// 在组件中:
preloadedFiles = [
  { name: 'report', size: 200000, type: '.pdf' },
  { name: 'photo', size: 500000, type: '.jpg' }
];

Pattern 5: JWT-Authenticated Upload

模式5:JWT认证上传

typescript
<ejs-uploader
  [asyncSettings]="asyncSettings"
  (uploading)="addAuthHeader($event)"
  (removing)="addAuthHeader($event)">
</ejs-uploader>

// ⚠️ Never hardcode tokens — always retrieve from a secure auth service (e.g., Angular AuthService or OAuth library).
// ⚠️ Always transmit tokens over HTTPS only. Never pass tokens as URL query parameters.
addAuthHeader(args: any): void {
  args.currentRequest.setRequestHeader('Authorization', `Bearer ${this.token}`);
}
typescript
<ejs-uploader
  [asyncSettings]="asyncSettings"
  (uploading)="addAuthHeader($event)"
  (removing)="addAuthHeader($event)">
</ejs-uploader>

// ⚠️ 切勿硬编码令牌——始终从安全认证服务(如Angular AuthService或OAuth库)获取。
// ⚠️ 始终仅通过HTTPS传输令牌。切勿将令牌作为URL查询参数传递。
addAuthHeader(args: any): void {
  args.currentRequest.setRequestHeader('Authorization', `Bearer ${this.token}`);
}

Key Properties

关键属性

PropertyTypeDefaultPurpose
[asyncSettings]
AsyncSettingsModel
{saveUrl:'',removeUrl:''}
Server save/remove URLs and chunk config
[autoUpload]
boolean
true
Upload immediately on file selection
[multiple]
boolean
true
Allow selecting multiple files
[allowedExtensions]
string
''
Comma-separated allowed extensions (e.g.,
.jpg,.png
)
[minFileSize]
number
0
Minimum file size in bytes
[maxFileSize]
number
30000000
Maximum file size in bytes (~28.6 MB)
[files]
FilesPropModel[]
[]
Preloaded files from server
[dropArea]
string | HTMLElement
null
Custom drop target element or selector
[directoryUpload]
boolean
false
Enable folder/directory upload
[sequentialUpload]
boolean
false
Upload files one at a time
[showFileList]
boolean
true
Show/hide default file list
[template]
any
null
Custom file list item template
[buttons]
ButtonsPropsModel
{browse,clear,upload}
Customize button text/HTML
[enabled]
boolean
true
Enable or disable the component
[cssClass]
string
''
Additional CSS classes on root element
[enableRtl]
boolean
false
Right-to-left rendering
[enableHtmlSanitizer]
boolean
true
Prevent XSS in filenames
[dropEffect]
DropEffect
'Default'
Drag effect: Copy, Move, Link, None
属性类型默认值用途
[asyncSettings]
AsyncSettingsModel
{saveUrl:'',removeUrl:''}
服务器保存/删除URL和分块配置
[autoUpload]
boolean
true
文件选择后立即上传
[multiple]
boolean
true
允许选择多个文件
[allowedExtensions]
string
''
逗号分隔的允许扩展名(例如
.jpg,.png
[minFileSize]
number
0
最小文件大小(字节)
[maxFileSize]
number
30000000
最大文件大小(字节,约28.6 MB)
[files]
FilesPropModel[]
[]
来自服务器的预加载文件
[dropArea]
string | HTMLElement
null
自定义拖放目标元素或选择器
[directoryUpload]
boolean
false
启用文件夹/目录上传
[sequentialUpload]
boolean
false
逐个上传文件
[showFileList]
boolean
true
显示/隐藏默认文件列表
[template]
any
null
自定义文件列表项模板
[buttons]
ButtonsPropsModel
{browse,clear,upload}
自定义按钮文本/HTML
[enabled]
boolean
true
启用或禁用组件
[cssClass]
string
''
根元素上的额外CSS类
[enableRtl]
boolean
false
从右到左渲染
[enableHtmlSanitizer]
boolean
true
防止文件名中的XSS攻击
[dropEffect]
DropEffect
'Default'
拖放效果:Copy、Move、Link、None

Key Events

关键事件

EventWhen it FiresKey Args
(selected)
Files selected or dropped
filesData
,
cancel
,
modifiedFilesData
(uploading)
Before each file upload starts
fileData
,
currentRequest
,
customFormData
,
cancel
(success)
Upload or remove succeeds
file
,
operation
(
upload
|
remove
),
event
(failure)
Upload or remove fails
file
,
operation
,
event
(progress)
Upload progress
file
,
event
(loaded, total)
(removing)
Before file remove request
filesData
,
postRawFile
,
currentRequest
(beforeRemove)
Before remove confirmation
filesData
,
cancel
(beforeUpload)
Before upload process
fileData
,
customFormData
(change)
File list changes
file
(clearing)
Before clear all action
cancel
(chunkSuccess)
Each chunk uploads OK
chunkIndex
,
totalChunk
,
chunkSize
,
file
(chunkFailure)
Each chunk fails
chunkIndex
,
totalChunk
,
chunkSize
,
file
,
cancel
(chunkUploading)
Before each chunk upload
fileData
,
currentRequest
,
customFormData
(pausing)
Chunk upload paused
file
,
chunkIndex
(resuming)
Chunk upload resumed
file
,
chunkIndex
(canceling)
Upload canceled
file
(fileListRendering)
Before each file item renders
element
,
fileInfo
(actionComplete)
All files processed
fileData
(created)
Component initialized
事件触发时机关键参数
(selected)
文件被选择或拖放时
filesData
,
cancel
,
modifiedFilesData
(uploading)
每个文件上传开始前
fileData
,
currentRequest
,
customFormData
,
cancel
(success)
上传或删除成功时
file
,
operation
upload
|
remove
),
event
(failure)
上传或删除失败时
file
,
operation
,
event
(progress)
上传进度更新时
file
,
event
(loaded, total)
(removing)
文件删除请求发送前
filesData
,
postRawFile
,
currentRequest
(beforeRemove)
删除确认前
filesData
,
cancel
(beforeUpload)
上传流程开始前
fileData
,
customFormData
(change)
文件列表变化时
file
(clearing)
清除所有操作前
cancel
(chunkSuccess)
每个分块上传成功时
chunkIndex
,
totalChunk
,
chunkSize
,
file
(chunkFailure)
每个分块上传失败时
chunkIndex
,
totalChunk
,
chunkSize
,
file
,
cancel
(chunkUploading)
每个分块上传开始前
fileData
,
currentRequest
,
customFormData
(pausing)
分块上传暂停时
file
,
chunkIndex
(resuming)
分块上传恢复时
file
,
chunkIndex
(canceling)
上传取消时
file
(fileListRendering)
每个文件项渲染前
element
,
fileInfo
(actionComplete)
所有文件处理完成时
fileData
(created)
组件初始化完成时

Key Methods

关键方法

MethodPurpose
upload(files?, custom?)
Programmatically start upload for selected or specific files
remove(fileData?, custom?, postRawFile?)
Remove a file from list or server
cancel(fileData?)
Cancel an in-progress chunk upload
pause(fileData?, custom?)
Pause a chunk upload
resume(fileData?, custom?)
Resume a paused chunk upload
retry(fileData?, fromCanceledStage?, custom?)
Retry a failed or canceled upload
clearAll()
Clear all files from the list
getFilesData(index?)
Get file data array shown in the list
createFileList(fileData)
Programmatically create file list items
sortFileList(filesData?)
Sort file list alphabetically
bytesToSize(bytes)
Convert bytes to human-readable KB/MB string
destroy()
Destroy the component and detach events
方法用途
upload(files?, custom?)
程序化启动所选或特定文件的上传
remove(fileData?, custom?, postRawFile?)
从列表或服务器中删除文件
cancel(fileData?)
取消进行中的分块上传
pause(fileData?, custom?)
暂停分块上传
resume(fileData?, custom?)
恢复暂停的分块上传
retry(fileData?, fromCanceledStage?, custom?)
重试失败或取消的上传
clearAll()
清除列表中的所有文件
getFilesData(index?)
获取列表中显示的文件数据数组
createFileList(fileData)
程序化创建文件列表项
sortFileList(filesData?)
按字母顺序对文件列表排序
bytesToSize(bytes)
将字节转换为人类可读的KB/MB字符串
destroy()
销毁组件并解绑事件

Common Use Cases

常见用例

Use Case 1: Profile Photo Upload
  • multiple="false"
    ,
    allowedExtensions=".jpg,.png,.gif,.webp"
    ,
    maxFileSize=5000000
  • Use
    selected
    event to preview before upload
  • Auto upload with progress indicator
Use Case 2: Document Upload Portal
  • Multiple files,
    allowedExtensions=".pdf,.doc,.docx,.xlsx"
  • Chunk upload for large files with pause/resume
  • Sequential upload to manage server load
Use Case 3: Image Gallery Batch Upload
  • Multiple files, directory upload enabled
  • Preview thumbnails using
    selected
    event + FileReader
  • Sort by file name before upload
Use Case 4: Secure File Upload (API-Authenticated)
  • JWT token injected via
    uploading
    event header
  • Custom
    customFormData
    to pass metadata
  • Server validates token before saving
Use Case 5: Form with Required File
  • autoUpload=false
    , synchronous form submission
  • Required attribute validation with
    data-required-message
  • Template-driven or reactive form binding
用例1:头像上传
  • multiple="false"
    ,
    allowedExtensions=".jpg,.png,.gif,.webp"
    ,
    maxFileSize=5000000
  • 使用
    selected
    事件在上传前预览
  • 带进度指示器的自动上传
用例2:文档上传门户
  • 多文件上传,
    allowedExtensions=".pdf,.doc,.docx,.xlsx"
  • 大文件分块上传,支持暂停/恢复
  • 顺序上传以管理服务器负载
用例3:图片库批量上传
  • 多文件上传,启用目录上传
  • 使用
    selected
    事件 + FileReader预览缩略图
  • 上传前按文件名排序
用例4:安全文件上传(API认证)
  • 通过
    uploading
    事件注入JWT令牌到请求头
  • 使用自定义
    customFormData
    传递元数据
  • 服务器在保存前验证令牌
用例5:带必填文件的表单
  • autoUpload=false
    ,同步表单提交
  • data-required-message
    的必填属性验证
  • 模板驱动或响应式表单绑定

Next Steps

下一步

  1. Getting Started → Install package and render basic uploader
  2. Async Upload → Configure save/remove URLs and upload modes
  3. Validation → Add extension and size constraints
  4. Chunk Upload → Handle large files with pause/resume
  5. Templates → Customize file list appearance
  6. Form Integration → Bind to Angular forms
  7. Advanced Patterns → JWT auth, programmatic upload, custom UI
  8. API Reference → Full properties, methods, events list

For detailed implementation, start with references/getting-started.md
  1. 快速入门 → 安装包并渲染基础上传器
  2. 异步上传 → 配置保存/删除URL和上传模式
  3. 验证 → 添加扩展名和大小约束
  4. 分块上传 → 处理大文件的暂停/恢复
  5. 模板 → 自定义文件列表外观
  6. 表单集成 → 绑定到Angular表单
  7. 高级模式 → JWT认证、程序化上传、自定义UI
  8. API参考 → 完整的属性、方法、事件列表

如需详细实现,请从references/getting-started.md开始

NumericTextBox

NumericTextBox组件

Component Overview

组件概述

The Syncfusion Angular NumericTextBox is a specialized input control for numeric values. It provides:
  • Numeric validation with min/max ranges and strict mode
  • Formatting (currency, percentage, decimals)
  • Spin buttons for value adjustment
  • Adornments (prepend/append templates for icons, labels)
  • Accessibility (WCAG 2.2, ARIA, keyboard navigation)
  • Localization (multiple cultures and RTL support)
  • Form integration (reactive forms, template-driven forms)

Syncfusion Angular NumericTextBox是一款专门用于数值输入的控件,提供:
  • 数值验证:支持最小/最大范围和严格模式
  • 格式化(货币、百分比、小数)
  • 微调按钮:用于调整数值
  • 装饰元素(前缀/后缀模板,用于图标、标签)
  • 无障碍性(WCAG 2.2、ARIA、键盘导航)
  • 本地化(多语言和RTL支持)
  • 表单集成(响应式表单、模板驱动表单)

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Installation and package setup
  • Angular 21+ standalone component setup
  • Basic NumericTextBox implementation
  • CSS imports and theme configuration
  • Range validation with min/max
  • Simple formatting example
  • Precision and decimals control
  • Two-way binding setup
  • Reactive forms integration
📄 阅读references/getting-started.md
  • 安装和包设置
  • Angular 21+独立组件设置
  • 基础NumericTextBox实现
  • CSS导入和主题配置
  • 最小/最大范围验证
  • 简单格式化示例
  • 精度和小数位数控制
  • 双向绑定设置
  • 响应式表单集成

Formats and Number Styling

格式与数值样式

📄 Read: references/formats-styling.md
  • Standard formats (currency
    c2
    , percentage
    p
    , numbers
    n
    )
  • Custom numeric format strings
  • Decimal place control
  • Currency symbols and localization
  • Styling NumericTextBox wrapper and icons
  • CSS customization patterns
📄 阅读references/formats-styling.md
  • 标准格式(货币
    c2
    、百分比
    p
    、数值
    n
  • 自定义数值格式字符串
  • 小数位数控制
  • 货币符号与本地化
  • NumericTextBox容器和图标样式
  • CSS自定义模式

Spinners and Step Control

微调按钮与步长控制

📄 Read: references/spinners-and-step.md
  • Spin button visibility (
    showSpinButton
    )
  • Step value configuration (
    step
    property)
  • Customizing spin up/down arrow icons
  • Arrow key interactions
  • Disabling spin buttons
📄 阅读references/spinners-and-step.md
  • 微调按钮可见性(
    showSpinButton
  • 步长值配置(
    step
    属性)
  • 自定义向上/向下箭头图标
  • 箭头键交互
  • 禁用微调按钮

Adornments and Templates

装饰元素与模板

📄 Read: references/adornments-and-templates.md
  • Adding prefix/suffix with
    prependTemplate
    and
    appendTemplate
  • Currency symbols and unit labels
  • Action buttons and icons
  • Status indicators without affecting validation
  • Template usage patterns
📄 阅读references/adornments-and-templates.md
  • 使用
    prependTemplate
    appendTemplate
    添加前缀/后缀
  • 货币符号和单位标签
  • 操作按钮和图标
  • 不影响验证的状态指示器
  • 模板使用模式

Validation and Form Integration

验证与表单集成

📄 Read: references/validation-and-forms.md
  • Range validation (min/max with strictMode)
  • Custom validation rules
  • Error and warning states
  • Reactive forms patterns
📄 阅读references/validation-and-forms.md
  • 范围验证(带strictMode的min/max)
  • 自定义验证规则
  • 错误和警告状态
  • 响应式表单模式

Advanced Patterns and Edge Cases

高级模式与边缘情况

📄 Read: references/advanced-patterns.md
  • Maintaining trailing zeros on focus
  • Preventing nullable input (always require a value)
  • Nullable input configuration
  • Clear button behavior
  • Read-only and disabled states
  • Focus and blur event handling
  • Float label types (Always, Auto, Never)
  • Performance optimization
📄 阅读references/advanced-patterns.md
  • 获取焦点时保留尾随零
  • 防止可空输入(始终要求值)
  • 可空输入配置
  • 清除按钮行为
  • 只读和禁用状态
  • 获取焦点和失去焦点事件处理
  • 浮动标签类型(Always、Auto、Never)
  • 性能优化

Accessibility and Migration

无障碍性与迁移

📄 Read: references/accessibility-and-migration.md
  • WCAG 2.2 Level AA compliance
  • ARIA attributes (spinbutton role, aria-valuemin, aria-valuemax, etc.)
  • Keyboard navigation (Arrow Up/Down)
  • Screen reader support
  • RTL support for right-to-left languages
  • EJ1 to EJ2 API migration guide
  • Localization and globalization
📄 阅读references/accessibility-and-migration.md
  • WCAG 2.2 Level AA合规
  • ARIA属性(spinbutton角色、aria-valuemin、aria-valuemax等)
  • 键盘导航(向上/向下箭头)
  • 屏幕阅读器支持
  • 从右到左语言的RTL支持
  • EJ1到EJ2 API迁移指南
  • 本地化与全球化

Globalization and Localization

全球化与本地化

📄 Read: references/globalization.md
  • Locale property configuration
  • Culture-specific number formatting
  • RTL (right-to-left) support
  • International number formats
📄 阅读references/globalization.md
  • 区域属性配置
  • 特定文化的数值格式化
  • RTL(从右到左)支持
  • 国际化数值格式

API Reference

API参考

📄 Read: references/api.md
  • All component properties with types, defaults, and descriptions
  • All public methods with signatures and usage examples
  • All events with argument interface details
  • ChangeEventArgs
    ,
    NumericBlurEventArgs
    ,
    NumericFocusEventArgs
    interfaces
  • Complete summary tables for quick lookup

📄 阅读references/api.md
  • 所有组件属性的类型、默认值和描述
  • 所有公共方法的签名和使用示例
  • 所有事件的参数接口详情
  • ChangeEventArgs
    NumericBlurEventArgs
    NumericFocusEventArgs
    接口
  • 用于快速查找的完整汇总表

Quick Start Example

快速入门示例

typescript
import { NumericTextBoxModule } from '@syncfusion/ej2-angular-inputs';
import { Component } from '@angular/core';

@Component({
  imports: [NumericTextBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-numerictextbox
      value="100"
      min="10"
      max="1000"
      step="5"
      format="c2"
      placeholder="Enter amount">
    </ejs-numerictextbox>
  `
})
export class AppComponent {}

typescript
import { NumericTextBoxModule } from '@syncfusion/ej2-angular-inputs';
import { Component } from '@angular/core';

@Component({
  imports: [NumericTextBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-numerictextbox
      value="100"
      min="10"
      max="1000"
      step="5"
      format="c2"
      placeholder="Enter amount">
    </ejs-numerictextbox>
  `
})
export class AppComponent {}

Common Patterns

常见模式

Currency Input with Validation

带验证的货币输入

typescript
<ejs-numerictextbox
  value="50.00"
  format="c2"
  currency="USD"
  min="0"
  max="10000"
  decimals="2"
  strictMode="true">
</ejs-numerictextbox>
typescript
<ejs-numerictextbox
  value="50.00"
  format="c2"
  currency="USD"
  min="0"
  max="10000"
  decimals="2"
  strictMode="true">
</ejs-numerictextbox>

Percentage Input

百分比输入

typescript
<ejs-numerictextbox
  value="25"
  format="p"
  min="0"
  max="100"
  step="1">
</ejs-numerictextbox>
typescript
<ejs-numerictextbox
  value="25"
  format="p"
  min="0"
  max="100"
  step="1">
</ejs-numerictextbox>

With Adornments (Unit Label)

带装饰元素(单位标签)

typescript
<ejs-numerictextbox
  value="100"
  [appendTemplate]="appendUnit">
</ejs-numerictextbox>

<ng-template #appendUnit>
  <span class="unit-label">kg</span>
</ng-template>
typescript
<ejs-numerictextbox
  value="100"
  [appendTemplate]="appendUnit">
</ejs-numerictextbox>

<ng-template #appendUnit>
  <span class="unit-label">kg</span>
</ng-template>

Two-Way Binding with Form Control

带表单控件的双向绑定

typescript
<ejs-numerictextbox
  [(ngModel)]="quantity"
  min="1"
  max="100"
  step="1">
</ejs-numerictextbox>

typescript
<ejs-numerictextbox
  [(ngModel)]="quantity"
  min="1"
  max="100"
  step="1">
</ejs-numerictextbox>

Key Properties

关键属性

PropertyTypePurposeDefault
value
numberCurrent numeric value
null
min
numberMinimum allowed value
Number.MIN_VALUE
max
numberMaximum allowed value
Number.MAX_VALUE
step
numberIncrement/decrement amount
1
decimals
numberDecimal places allowed
null
format
stringNumber format (e.g., 'c2', 'n2', 'p')
null
currency
stringCurrency code (e.g., 'USD', 'EUR')
null
strictMode
booleanEnforce min/max validation
false
showSpinButton
booleanShow up/down spinner buttons
true
showClearButton
booleanShow clear button
false
readonly
booleanPrevent editing
false
disabled
booleanDisable the component
false
locale
stringCulture code (e.g., 'de-DE', 'fr-FR')
'en-US'
enableRtl
booleanEnable right-to-left mode
false
placeholder
stringHint text
null
floatLabelType
stringLabel float behavior ('Auto', 'Always', 'Never')
'Never'

属性类型用途默认值
value
number当前数值
null
min
number允许的最小值
Number.MIN_VALUE
max
number允许的最大值
Number.MAX_VALUE
step
number增量/减量值
1
decimals
number允许的小数位数
null
format
string数值格式(例如'c2'、'n2'、'p')
null
currency
string货币代码(例如'USD'、'EUR')
null
strictMode
boolean强制min/max验证
false
showSpinButton
boolean显示向上/向下微调按钮
true
showClearButton
boolean显示清除按钮
false
readonly
boolean防止编辑
false
disabled
boolean禁用组件
false
locale
string文化代码(例如'de-DE'、'fr-FR')
'en-US'
enableRtl
boolean启用从右到左模式
false
placeholder
string提示文本
null
floatLabelType
string标签浮动行为('Auto'、'Always'、'Never')
'Never'

Common Use Cases

常见用例

  1. E-Commerce Quantity Input — Product quantity selector with min/max validation
  2. Financial Forms — Currency input with currency symbol and decimal places
  3. Scientific Applications — High-precision decimal inputs
  4. Survey/Form Data — Percentage inputs with 0-100 range
  5. Multi-Language Support — Numbers formatted per user locale
  6. Accessibility-First Forms — WCAG-compliant numeric inputs
  7. Mobile-Friendly — Touch-friendly spin buttons and keyboard input

  1. 电商数量输入 — 带最小/最大验证的产品数量选择器
  2. 财务表单 — 带货币符号和小数位数的货币输入
  3. 科学应用 — 高精度小数输入
  4. 调查/表单数据 — 0-100范围的百分比输入
  5. 多语言支持 — 根据用户区域格式化数值
  6. 无障碍优先表单 — 符合WCAG标准的数值输入
  7. 移动端友好 — 触控友好的微调按钮和键盘输入

See Also

另请参阅

TextBox

TextBox组件

The Syncfusion Angular TextBox component is a feature-rich input element that enhances the native HTML input with floating labels, validation states, adornments (prepended/appended elements), accessibility support, and comprehensive styling options. This skill guides you through implementation patterns, configuration, and best practices.
Syncfusion Angular TextBox组件是一个功能丰富的输入元素,在原生HTML输入的基础上增强了浮动标签、验证状态、装饰元素(前缀/后缀)、无障碍支持和全面的样式选项。本指南将指导您完成实现模式、配置和最佳实践。

Component Overview

组件概述

The TextBox component provides:
FeaturePurpose
Floating LabelsAnimated labels that float above input when focused or filled
Validation StatesVisual feedback (error, warning, success) with CSS classes
AdornmentsPrepend/append custom HTML elements (icons, buttons, units)
Clear ButtonBuilt-in clear functionality to reset input value
Disabled/Read-only StatesControl user interaction and editability
HTML AttributesSupport for standard input attributes (type, maxlength, etc.)
Multiline SupportTextarea configuration with row/column sizing
AccessibilityWCAG 2.2 compliance, keyboard navigation, ARIA attributes
RTL SupportRight-to-left language support
Styling OptionsCSS classes, validation colors, responsive sizing

TextBox组件提供:
功能用途
浮动标签获得焦点或填充时,标签会浮动到输入框上方的动画效果
验证状态带有CSS类的视觉反馈(错误、警告、成功)
装饰元素前缀/后缀自定义HTML元素(图标、按钮、单位)
清除按钮内置清除功能以重置输入值
禁用/只读状态控制用户交互和可编辑性
HTML属性支持标准输入属性(type、maxlength等)
多行支持带行/列尺寸的文本区域配置
无障碍性WCAG 2.2合规、键盘导航、ARIA属性
RTL支持从右到左语言支持
样式选项CSS类、验证颜色、响应式尺寸

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Installation and package setup
  • Create your first TextBox component
  • CSS imports and theme selection
  • Floating label implementation
  • Basic event binding and data binding
  • Common setup issues and solutions
📄 阅读references/getting-started.md
  • 安装和包设置
  • 创建您的第一个TextBox组件
  • CSS导入和主题选择
  • 浮动标签实现
  • 基础事件绑定和数据绑定
  • 常见设置问题与解决方案

Input Features and State Management

输入功能与状态管理

📄 Read: references/input-features.md
  • Clear button implementation (showClearButton)
  • Disabled state (enabled property)
  • Read-only state (readonly property)
  • HTML attributes configuration (htmlAttributes)
  • Supporting input types and attributes
  • State management patterns for forms
📄 阅读references/input-features.md
  • 清除按钮实现(showClearButton)
  • 禁用状态(enabled属性)
  • 只读状态(readonly属性)
  • HTML属性配置(htmlAttributes)
  • 支持的输入类型和属性
  • 表单状态管理模式

Adornments and Customization

装饰元素与自定义

📄 Read: references/adornments-customization.md
  • Prepend and append template usage
  • Icon adornments for visual context
  • Button adornments (password toggle, clear)
  • Validation status indicators
  • Unit indicators (currency, temperature, etc.)
  • Performance and accessibility considerations
📄 阅读references/adornments-customization.md
  • 前缀和后缀模板的使用
  • 用于视觉上下文的图标装饰
  • 按钮装饰(密码切换、清除)
  • 验证状态指示器
  • 单位指示器(货币、温度等)
  • 性能和无障碍性考虑

Validation States and Error Handling

验证状态与错误处理

📄 Read: references/validation-states.md
  • Error, warning, and success validation states
  • CSS class approach (e-error, e-warning, e-success)
  • Visual feedback patterns
  • Adding asterisk for required fields
  • Form integration with validation
  • Custom error message display
📄 阅读references/validation-states.md
  • 错误、警告和成功验证状态
  • CSS类方法(e-error、e-warning、e-success)
  • 视觉反馈模式
  • 为必填字段添加星号
  • 表单集成与验证
  • 自定义错误消息显示

Styling and Appearance Customization

样式与外观自定义

📄 Read: references/styling-appearance.md
  • CSS structure and class hierarchy
  • Basic sizing (height, font, padding)
  • Floating label color customization
  • Validation state color changes
  • Borders, rounded corners, and advanced styling
  • Dynamic styling based on input value
  • Theme integration and customization
📄 阅读references/styling-appearance.md
  • CSS结构和类层次
  • 基础尺寸(高度、字体、内边距)
  • 浮动标签颜色自定义
  • 验证状态颜色更改
  • 边框、圆角和高级样式
  • 根据输入值的动态样式
  • 主题集成与自定义

Multiline and Sizing Features

多行与尺寸功能

📄 Read: references/multiline-sizing.md
  • Multiline textarea configuration
  • Row and column sizing
  • Responsive sizing patterns
  • Height adjustments and constraints
  • Character counting implementation
  • Text wrapping and overflow handling
📄 阅读references/multiline-sizing.md
  • 多行文本区域配置
  • 行和列尺寸
  • 响应式尺寸模式
  • 高度调整和约束
  • 字符计数实现
  • 文本换行和溢出处理

Accessibility and Migration

无障碍性与迁移

📄 Read: references/accessibility-migration.md
  • WCAG 2.2 and Section 508 compliance
  • Keyboard navigation support
  • ARIA attributes (aria-labelledby, aria-invalid, aria-disabled)
  • Screen reader compatibility
  • Migration from CSS TextBox to Angular component
  • RTL and mobile accessibility

📄 阅读references/accessibility-migration.md
  • WCAG 2.2和Section 508合规
  • 键盘导航支持
  • ARIA属性(aria-labelledby、aria-invalid、aria-disabled)
  • 屏幕阅读器兼容性
  • 从CSS TextBox迁移到Angular组件
  • RTL和移动无障碍性

Quick Start Example

快速入门示例

Create a floating label TextBox:
typescript
import { Component } from '@angular/core';
import { TextBoxModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [TextBoxModule],
  template: `
    <div style="margin: 50px;">
      <h2>Angular TextBox Example</h2>
      <ejs-textbox 
        #textbox
        [floatLabelType]="'Auto'"
        placeholder="Enter your name"
        (input)="onInput($event)"
      ></ejs-textbox>
      <p>Value: {{ textValue }}</p>
    </div>
  `
})
export class AppComponent {
  textValue = '';

  onInput(event: any) {
    this.textValue = event.target.value;
  }
}
Key Points:
  • Use
    floatLabelType="'Auto'"
    for automatic floating labels
  • Import
    TextBoxModule
    from
    @syncfusion/ej2-angular-inputs
  • Use standard Angular
    (input)
    event binding
  • Set
    placeholder
    for the floating label text

创建带浮动标签的TextBox:
typescript
import { Component } from '@angular/core';
import { TextBoxModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [TextBoxModule],
  template: `
    <div style="margin: 50px;">
      <h2>Angular TextBox Example</h2>
      <ejs-textbox 
        #textbox
        [floatLabelType]="'Auto'"
        placeholder="Enter your name"
        (input)="onInput($event)"
      ></ejs-textbox>
      <p>Value: {{ textValue }}</p>
    </div>
  `
})
export class AppComponent {
  textValue = '';

  onInput(event: any) {
    this.textValue = event.target.value;
  }
}
关键点:
  • 使用
    floatLabelType="'Auto'"
    实现自动浮动标签
  • @syncfusion/ej2-angular-inputs
    导入
    TextBoxModule
  • 使用标准Angular
    (input)
    事件绑定
  • 设置
    placeholder
    作为浮动标签文本

Common Patterns

常见模式

Pattern 1: Email Input with Icon Adornment

模式1:带图标装饰的邮箱输入

typescript
<ejs-textbox
  placeholder="Email"
  [floatLabelType]="'Auto'"
  [appendTemplate]="'appendTemplate'"
></ejs-textbox>
<ng-template #appendTemplate>
  <span class="e-input-group-icon"></span>
</ng-template>
When to Use: Email, username, or other fields with visual context
typescript
<ejs-textbox
  placeholder="Email"
  [floatLabelType]="'Auto'"
  [appendTemplate]="'appendTemplate'"
></ejs-textbox>
<ng-template #appendTemplate>
  <span class="e-input-group-icon"></span>
</ng-template>
适用场景: 邮箱、用户名或其他需要视觉上下文的字段

Pattern 2: Password Toggle

模式2:密码切换

typescript
<ejs-textbox
  [type]="passwordVisible ? 'text' : 'password'"
  placeholder="Password"
  [floatLabelType]="'Auto'"
  [appendTemplate]="'toggleTemplate'"
></ejs-textbox>
<ng-template #toggleTemplate>
  <button (click)="togglePassword()">👁</button>
</ng-template>

// Component
togglePassword() {
  this.passwordVisible = !this.passwordVisible;
}
When to Use: Password fields requiring visibility toggle
typescript
<ejs-textbox
  [type]="passwordVisible ? 'text' : 'password'"
  placeholder="Password"
  [floatLabelType]="'Auto'"
  [appendTemplate]="'toggleTemplate'"
></ejs-textbox>
<ng-template #toggleTemplate>
  <button (click)="togglePassword()">👁</button>
</ng-template>

// 组件代码
togglePassword() {
  this.passwordVisible = !this.passwordVisible;
}
适用场景: 需要切换可见性的密码字段

Pattern 3: Validation with Error Display

模式3:带错误显示的验证

typescript
<ejs-textbox
  [cssClass]="isValid ? 'e-success' : 'e-error'"
  placeholder="Phone"
  (change)="validatePhone($event)"
></ejs-textbox>
<p *ngIf="!isValid" style="color: red;">{{ errorMessage }}</p>
When to Use: Form fields with validation feedback
typescript
<ejs-textbox
  [cssClass]="isValid ? 'e-success' : 'e-error'"
  placeholder="Phone"
  (change)="validatePhone($event)"
></ejs-textbox>
<p *ngIf="!isValid" style="color: red;">{{ errorMessage }}</p>
适用场景: 带验证反馈的表单字段

Pattern 4: Currency Input with Unit Indicator

模式4:带单位指示器的货币输入

typescript
<ejs-textbox
  type="number"
  placeholder="Amount"
  [prependTemplate]="'prependTemplate'"
></ejs-textbox>
<ng-template #prependTemplate>
  <span style="padding: 0 8px;">$</span>
</ng-template>
When to Use: Currency, temperature, or measurement inputs

typescript
<ejs-textbox
  type="number"
  placeholder="Amount"
  [prependTemplate]="'prependTemplate'"
></ejs-textbox>
<ng-template #prependTemplate>
  <span style="padding: 0 8px;">$</span>
</ng-template>
适用场景: 货币、温度或度量输入

Key Props and Configuration

关键属性与配置

Refer to the full API summary in references/api.md.
Property / MethodTypePurpose
floatLabelType
string'Auto'
placeholder
stringText shown when empty; used for floating labels
value
stringCurrent input value
enabled
booleanEnable/disable the input (default: true)
readonly
booleanMake input read-only (selectable but not editable)
showClearButton
booleanDisplay clear button when field has content
cssClass
stringCustom CSS classes (e.g., 'e-error', 'e-warning', 'e-success', 'e-small', 'e-bigger', 'e-outline', 'e-corner')
htmlAttributes
objectStandard HTML attributes (name, maxlength, type, etc.)
prependTemplate
templateTemplate for content prepended before the input
appendTemplate
templateTemplate for content appended after the input
multiline
booleanEnable textarea mode (renders a
<textarea>
)
addIcon(position, icons)
methodAdd icon(s) programmatically (
position
= 'append'
addAttributes(attributes)
methodAdd HTML attributes programmatically (e.g.,
maxlength
)
removeAttributes(names[])
methodRemove previously added attributes
focusIn()
/
focusOut()
methodProgrammatically focus or blur the component
destroy()
methodDestroy the component instance and detach handlers
getPersistData()
methodReturn persisted state string (when
enablePersistence
is used)
Notes:
  • Use CSS class
    e-corner
    together with
    e-outline
    to show rounded corners for box-model TextBoxes.
  • rows
    and
    cols
    are not component properties. To set them on a multiline TextBox, use
    addAttributes({rows: '5'} as any)
    in the
    (created)
    event handler (see
    references/multiline-sizing.md
    ).
  • For programmatic input creation (dynamic forms), use
    Input.createInput
    from
    @syncfusion/ej2-inputs
    (see
    references/input-features.md
    ).

请参阅references/api.md中的完整API摘要。
属性/方法类型用途
floatLabelType
string'Auto'
placeholder
string空值时显示的文本;用于浮动标签
value
string当前输入值
enabled
boolean启用/禁用输入(默认:true)
readonly
boolean设置输入为只读(可选择但不可编辑)
showClearButton
boolean字段有内容时显示清除按钮
cssClass
string自定义CSS类(例如'e-error'、'e-warning'、'e-success'、'e-small'、'e-bigger'、'e-outline'、'e-corner')
htmlAttributes
object标准HTML属性(name、maxlength、type等)
prependTemplate
template输入框前添加内容的模板
appendTemplate
template输入框后添加内容的模板
multiline
boolean启用文本区域模式(渲染
<textarea>
addIcon(position, icons)
method程序化添加图标(
position
= 'append'
addAttributes(attributes)
method程序化添加HTML属性(例如
maxlength
removeAttributes(names[])
method移除之前添加的属性
focusIn()
/
focusOut()
method程序化获取或失去焦点
destroy()
method销毁组件实例并解绑处理程序
getPersistData()
method返回持久化状态字符串(启用
enablePersistence
时)
注意:
  • 对于盒模型TextBox,使用CSS类
    e-corner
    配合
    e-outline
    以显示圆角。
  • rows
    cols
    不是组件属性。要为多行TextBox设置它们,请在
    (created)
    事件处理程序中使用
    addAttributes({rows: '5'} as any)
    (请参阅
    references/multiline-sizing.md
    )。
  • 对于程序化创建输入(动态表单),使用
    @syncfusion/ej2-inputs
    中的
    Input.createInput
    (请参阅
    references/input-features.md
    )。

Common Use Cases

常见用例

1. Contact Form

1. 联系表单

Multiple TextBox fields with floating labels, validation states, and required field indicators. See validation-states.md and accessibility-migration.md.
多个带浮动标签、验证状态和必填字段指示器的TextBox字段。请参阅validation-states.mdaccessibility-migration.md

2. Search Input with Clear Button

2. 带清除按钮的搜索输入

TextBox with
showClearButton=true
for quick input reset. See input-features.md.
设置
showClearButton=true
的TextBox,用于快速重置输入。请参阅input-features.md

3. Styled Input with Icon Prefix/Suffix

3. 带图标前缀/后缀的样式化输入

TextBox with
prependTemplate
or
appendTemplate
for visual context. See adornments-customization.md.
使用
prependTemplate
appendTemplate
的TextBox,用于视觉上下文。请参阅adornments-customization.md

4. Password Field with Toggle

4. 带切换按钮的密码字段

Password input with visibility toggle button via append template. See adornments-customization.md.
通过后缀模板实现可见性切换按钮的密码输入。请参阅adornments-customization.md

5. Multiline Comment Field

5. 多行评论字段

Textarea with row sizing and character counting. See multiline-sizing.md.
带行尺寸和字符计数的文本区域。请参阅multiline-sizing.md

6. Accessible Form Field

6. 无障碍表单字段

TextBox with proper ARIA attributes and keyboard support for compliance. See accessibility-migration.md.

带有适当ARIA属性和键盘支持的TextBox,以符合合规要求。请参阅accessibility-migration.md

Related Documentation

相关文档

Next Steps

下一步

  1. Start with references/textbox-getting-started.md to set up your first TextBox
  2. Explore references/textbox-input-features.md for state management
  3. Use references/textbox-adornments-customization.md for custom UI
  4. Reference references/textbox-validation-states.md for form validation
  5. Customize styling with references/textbox-styling-appearance.md
  6. Handle advanced cases in references/textbox-multiline-sizing.md and references/textbox-accessibility-migration.md

  1. references/textbox-getting-started.md开始,设置您的第一个TextBox
  2. 探索references/textbox-input-features.md以了解状态管理
  3. 使用references/textbox-adornments-customization.md实现自定义UI
  4. 参考references/textbox-validation-states.md进行表单验证
  5. 使用references/textbox-styling-appearance.md自定义样式
  6. 处理references/textbox-multiline-sizing.mdreferences/textbox-accessibility-migration.md中的高级场景

Signature

Signature组件

The Syncfusion Angular Signature component (
ejs-signature
) provides a smooth, canvas-based digital signature capture experience with comprehensive features including undo/redo operations, multiple export formats, customizable strokes, and full accessibility support.
Package:
@syncfusion/ej2-angular-inputs

Selector:
ejs-signature
(on a
<canvas>
element)
Module:
SignatureModule
Syncfusion Angular Signature组件(
ejs-signature
)提供流畅的基于画布的数字签名捕获体验,具备全面功能,包括撤销/重做操作、多种导出格式、可自定义笔触和完整的无障碍支持。
包:
@syncfusion/ej2-angular-inputs

选择器:
ejs-signature
(用于
<canvas>
元素)
模块:
SignatureModule

Component Overview

组件概述

The Signature component provides:
  • Smooth Stroke Rendering: Velocity-based stroke width adjustment for natural signing
  • Complete Action History: Undo/redo with snapshot tracking
  • Multiple Export Formats: PNG, JPEG, SVG, Base64, or Blob
  • Full Customization: Stroke properties, colors, and background images
  • Accessibility First: WCAG 2.2 compliant with keyboard shortcuts
  • Read-only and Disabled States: For view-only or restricted scenarios
  • Background Persistence: Option to include/exclude background in saved files
Signature组件提供:
  • 流畅笔触渲染:基于速度的笔触宽度调整,实现自然签名
  • 完整操作历史:带快照跟踪的撤销/重做
  • 多种导出格式:PNG、JPEG、SVG、Base64或Blob
  • 完全自定义:笔触属性、颜色和背景图片
  • 无障碍优先:符合WCAG 2.2标准,支持键盘快捷键
  • 只读和禁用状态:用于仅查看或受限场景
  • 背景持久化:保存文件时可选择是否包含背景

Documentation and Navigation Guide

文档与导航指南

⚠️ Agentic use note: Read only the sections relevant to your task — do not chain through all references automatically.
⚠️ 智能代理使用说明:仅阅读与您任务相关的部分——不要自动遍历所有参考内容。

Getting Started

快速入门

📄 Read: references/signature-getting-started.md
  • Angular 21 setup and standalone architecture
  • Package installation and dependencies
  • CSS theme imports and configuration
  • Basic component rendering
  • First running application
📄 阅读references/signature-getting-started.md
  • Angular 21设置和独立架构
  • 包安装和依赖
  • CSS主题导入和配置
  • 基础组件渲染
  • 第一个运行的应用

Drawing Signatures Programmatically

程序化绘制签名

📄 Read: references/signature-drawing-signatures.md
  • draw()
    method for text-based signatures
  • Font family and font size options
  • Render text as signature with custom styling
  • User input integration for drawing
📄 阅读references/signature-drawing-signatures.md
  • draw()
    方法用于基于文本的签名
  • 字体族和字体大小选项
  • 使用自定义样式将文本渲染为签名
  • 用户输入集成以进行绘制

User Interactions

用户交互

📄 Read: references/signature-user-interactions.md
  • Undo and redo functionality with
    canUndo()
    /
    canRedo()
    checks
  • Clear method for erasing signatures
  • Disabled state for preventing user input
  • Read-only mode for view-only scenarios
  • Button state management and change events
📄 阅读references/signature-user-interactions.md
  • canUndo()
    /
    canRedo()
    检查的撤销和重做功能
  • 清除方法以擦除签名
  • 禁用状态以防止用户输入
  • 只读模式用于仅查看场景
  • 按钮状态管理和变更事件

Customization and Styling

自定义与样式

📄 Read: references/signature-customization.md
  • Stroke width control (
    minStrokeWidth
    ,
    maxStrokeWidth
    ,
    velocity
    )
  • Stroke color customization with hex/RGB/named colors
  • Background color setup
  • Background image integration
  • Real-time property updates
📄 阅读references/signature-customization.md
  • 笔触宽度控制(
    minStrokeWidth
    maxStrokeWidth
    velocity
  • 使用十六进制/RGB/命名颜色自定义笔触颜色
  • 背景颜色设置
  • 背景图片集成
  • 实时属性更新

Opening and Saving Signatures

打开与保存签名

📄 Read: references/signature-open-save.md
  • Load pre-drawn signatures using
    load()
    method
  • Base64 encoding and URL support
  • Save as Base64 with
    getSignature()
  • Save as Blob with
    saveAsBlob()
  • Save as image file (
    save()
    method)
  • saveWithBackground
    property for background inclusion
📄 阅读references/signature-open-save.md
  • 使用
    load()
    方法加载预绘制的签名
  • Base64编码和URL支持
  • 使用
    getSignature()
    保存为Base64
  • 使用
    saveAsBlob()
    保存为Blob
  • 使用
    save()
    方法保存为图片文件
  • saveWithBackground
    属性用于是否包含背景

Toolbar Integration

工具栏集成

📄 Read: references/signature-toolbar-integration.md
  • Complete toolbar setup with undo/redo/save buttons
  • Color picker integration for stroke and background colors
  • Stroke width controls with dropdown
  • Clear and disable toggles
  • Button state management with change events
  • Full working toolbar example
📄 阅读references/signature-toolbar-integration.md
  • 带撤销/重做/保存按钮的完整工具栏设置
  • 笔触和背景颜色的颜色选择器集成
  • 带下拉菜单的笔触宽度控制
  • 清除和禁用切换
  • 带变更事件的按钮状态管理
  • 完整的工作工具栏示例

Accessibility

无障碍性

📄 Read: references/signature-accessibility.md
  • WCAG 2.2 and Section 508 compliance
  • Keyboard shortcuts (Ctrl+Z, Ctrl+Y, Ctrl+S, Delete)
  • Screen reader support and keyboard navigation
  • Color contrast and focus indicators
  • Mobile device support
📄 阅读references/signature-accessibility.md
  • WCAG 2.2和Section 508合规
  • 键盘快捷键(Ctrl+Z、Ctrl+Y、Ctrl+S、Delete)
  • 屏幕阅读器支持和键盘导航
  • 颜色对比度和焦点指示器
  • 移动设备支持

API Reference

API参考

📄 Read: references/signature-api.md
  • Complete properties reference (
    backgroundColor
    ,
    strokeColor
    ,
    disabled
    , etc.)
  • All methods (
    undo
    ,
    redo
    ,
    clear
    ,
    draw
    ,
    save
    ,
    load
    , etc.)
  • Events and event arguments (
    change
    ,
    beforeSave
    ,
    created
    )
  • Parameters and return types
📄 阅读references/signature-api.md
  • 完整的属性参考(
    backgroundColor
    strokeColor
    disabled
    等)
  • 所有方法(
    undo
    redo
    clear
    draw
    save
    load
    等)
  • 事件和事件参数(
    change
    beforeSave
    created
  • 参数和返回类型

Quick Start Example

快速入门示例

typescript
import { Component } from '@angular/core';
import { SignatureModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  imports: [SignatureModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div class="e-section-control">
      <h4>Sign here</h4>
      <canvas ejs-signature #signature id="signature"></canvas>
    </div>
  `
})
export class AppComponent {}
CSS Theme Setup (
styles.css
):
css
@import 'node_modules/@syncfusion/ej2-base/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-angular-inputs/styles/material3.css';
typescript
import { Component } from '@angular/core';
import { SignatureModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  imports: [SignatureModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div class="e-section-control">
      <h4>Sign here</h4>
      <canvas ejs-signature #signature id="signature"></canvas>
    </div>
  `
})
export class AppComponent {}
CSS主题设置
styles.css
):
css
@import 'node_modules/@syncfusion/ej2-base/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-angular-inputs/styles/material3.css';

Common Patterns

常见模式

Pattern 1: Capture and Save Signature

模式1:捕获并保存签名

typescript
import { Component, ViewChild } from '@angular/core';
import { SignatureComponent, SignatureModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  imports: [SignatureModule],
  standalone: true,
  selector: 'app-save-signature',
  template: `
    <canvas ejs-signature #signature id="signature"></canvas>
    <button (click)="saveSignature()">Save as PNG</button>
  `
})
export class SaveSignatureComponent {
  @ViewChild('signature') public signature?: SignatureComponent;

  saveSignature(): void {
    if (!this.signature?.isEmpty()) {
      this.signature?.save('Png', 'MySignature');
    }
  }
}
typescript
import { Component, ViewChild } from '@angular/core';
import { SignatureComponent, SignatureModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  imports: [SignatureModule],
  standalone: true,
  selector: 'app-save-signature',
  template: `
    <canvas ejs-signature #signature id="signature"></canvas>
    <button (click)="saveSignature()">Save as PNG</button>
  `
})
export class SaveSignatureComponent {
  @ViewChild('signature') public signature?: SignatureComponent;

  saveSignature(): void {
    if (!this.signature?.isEmpty()) {
      this.signature?.save('Png', 'MySignature');
    }
  }
}

Pattern 2: Undo/Redo with State Management

模式2:带状态管理的撤销/重做

typescript
change(): void {
  this.undoButton.disabled = !this.signature?.canUndo();
  this.redoButton.disabled = !this.signature?.canRedo();
  this.clearButton.disabled = this.signature?.isEmpty() ?? true;
}
typescript
change(): void {
  this.undoButton.disabled = !this.signature?.canUndo();
  this.redoButton.disabled = !this.signature?.canRedo();
  this.clearButton.disabled = this.signature?.isEmpty() ?? true;
}

Pattern 3: Load and Verify Signature

模式3:加载并验证签名

typescript
loadSignature(): void {
  const base64String = (document.getElementById('signatureInput') as any).value;
  try {
    this.signature?.load(base64String);
  } catch (error) {
    console.error('Invalid signature format');
  }
}
typescript
loadSignature(): void {
  const base64String = (document.getElementById('signatureInput') as any).value;
  try {
    this.signature?.load(base64String);
  } catch (error) {
    console.error('Invalid signature format');
  }
}

Key Properties

关键属性

PropertyTypeDefaultPurpose
strokeColor
string
'#000000'
Pen stroke color
backgroundColor
string
'#ffffff'
Canvas background color
backgroundImage
string
''
Background image URL ⚠️ Validate and allowlist URLs; avoid untrusted or user-supplied values to prevent mixed-content or open-redirect issues
minStrokeWidth
number
0.5
Minimum stroke width
maxStrokeWidth
number
2.0
Maximum stroke width
velocity
number
0.7
Stroke velocity factor
saveWithBackground
boolean
false
Include background when saving
disabled
boolean
false
Disable signature input
isReadOnly
boolean
false
Read-only (view-only) mode
enablePersistence
boolean
false
Persist signature across reloads
cssClass
string
''
Additional CSS classes
属性类型默认值用途
strokeColor
string
'#000000'
笔触颜色
backgroundColor
string
'#ffffff'
画布背景颜色
backgroundImage
string
''
背景图片URL ⚠️ 验证并允许列表URL;避免不受信任或用户提供的值,以防止混合内容或开放重定向问题
minStrokeWidth
number
0.5
最小笔触宽度
maxStrokeWidth
number
2.0
最大笔触宽度
velocity
number
0.7
笔触速度因子
saveWithBackground
boolean
false
保存时包含背景
disabled
boolean
false
禁用签名输入
isReadOnly
boolean
false
只读(仅查看)模式
enablePersistence
boolean
false
跨重载持久化签名
cssClass
string
''
额外CSS类

Key Methods

关键方法

MethodPurpose
undo()
Undo the last stroke
redo()
Redo the last undone stroke
canUndo()
Returns
true
if undo is available
canRedo()
Returns
true
if redo is available
clear()
Erase all strokes
isEmpty()
Returns
true
if no strokes drawn
draw(text, font?, fontSize?)
Draw text as a signature
save(type?, fileName?)
Save as PNG/JPEG/SVG file
getSignature(type?)
Get signature as Base64 string
saveAsBlob(type?)
Get signature as a Blob
getBlob(type?)
Returns a Blob of the signature
load(signature)
Load a Base64 or URL signature
refresh()
Refresh and redraw the canvas
destroy()
Destroy the component
方法用途
undo()
撤销最后一笔
redo()
重做最后一笔撤销的笔触
canUndo()
如果可以撤销则返回
true
canRedo()
如果可以重做则返回
true
clear()
擦除所有笔触
isEmpty()
如果没有绘制笔触则返回
true
draw(text, font?, fontSize?)
将文本绘制为签名
save(type?, fileName?)
保存为PNG/JPEG/SVG文件
getSignature(type?)
获取Base64格式的签名
saveAsBlob(type?)
获取Blob格式的签名
getBlob(type?)
返回签名的Blob
load(signature)
加载Base64或URL格式的签名
refresh()
刷新并重绘画布
destroy()
销毁组件

Key Events

关键事件

EventWhen it FiresKey Args
(change)
After each stroke completes
isEmpty
(beforeSave)
Before
save()
executes
fileName
,
fileType
,
cancel
(created)
Component initialized
事件触发时机关键参数
(change)
每一笔完成后
isEmpty
(beforeSave)
save()
执行前
fileName
,
fileType
,
cancel
(created)
组件初始化完成时

Common Use Cases

常见用例

  1. Contract/Agreement Signing — Capture user signature and save as Base64 for backend storage
  2. Feedback Forms — Embedded signature field with clear/undo controls
  3. Document Approval — Load existing signature, verify it is not empty before form submit
  4. Toolbar-Driven Signing — Full toolbar with color pickers, stroke width, undo/redo, save
  5. Programmatic Signature — Draw typed name as a styled signature via
    draw()
    method

For detailed implementation, start with references/signature-getting-started.md

  1. 合同/协议签署 — 捕获用户签名并保存为Base64以便后端存储
  2. 反馈表单 — 嵌入带清除/撤销控件的签名字段
  3. 文档审批 — 加载现有签名,提交前验证签名非空
  4. 工具栏驱动的签名 — 带颜色选择器、笔触宽度、撤销/重做、保存的完整工具栏
  5. 程序化签名 — 通过
    draw()
    方法将输入的名称绘制为样式化签名

如需详细实现,请从references/signature-getting-started.md开始

CheckBox

CheckBox组件

The Syncfusion Angular CheckBox (
ejs-checkbox
) is a graphical UI element that lets users select one or more options. It supports checked, unchecked, and indeterminate states, flexible label positioning, size variants, two-way binding with
ngModel
, full accessibility compliance, and rich CSS customization.
Package:
@syncfusion/ej2-angular-buttons

Selector:
ejs-checkbox

Module:
CheckBoxModule
Syncfusion Angular CheckBox(
ejs-checkbox
)是一个图形化UI元素,允许用户选择一个或多个选项。它支持选中未选中不确定状态,灵活的标签定位,尺寸变体,与
ngModel
的双向绑定,完整的无障碍合规性以及丰富的CSS自定义。
包:
@syncfusion/ej2-angular-buttons

选择器:
ejs-checkbox

模块:
CheckBoxModule

Component Overview

组件概述

The CheckBox component provides:
  • Three States: Checked, unchecked, and indeterminate (partial selection)
  • Label Control: Caption text with before/after positioning
  • Size Variants: Default and small (
    e-small
    ) sizes
  • Form Support:
    name
    /
    value
    attributes for HTML form submission,
    ngModel
    two-way binding
  • Accessibility: WCAG 2.2, Section 508, keyboard navigation (Space key), screen reader support
  • Custom Styling: Color variants, round frames, custom check icons via CSS classes
  • RTL Support: Right-to-left rendering
CheckBox组件提供:
  • 三种状态:选中、未选中和不确定(部分选择)
  • 标签控制:标题文本可置于复选框之前/之后
  • 尺寸变体:默认和小尺寸(
    e-small
  • 表单支持:HTML表单提交的
    name
    /
    value
    属性,
    ngModel
    双向绑定
  • 无障碍性:WCAG 2.2、Section 508合规,键盘导航(空格键),屏幕阅读器支持
  • 自定义样式:颜色变体、圆形边框、通过CSS类自定义勾选图标
  • RTL支持:从右到左渲染

Documentation and Navigation Guide

文档与导航指南

⚠️ Agentic use note: Read only the sections relevant to your task — do not chain through all references automatically.
⚠️ 智能代理使用说明:仅阅读与您任务相关的部分——不要自动遍历所有参考内容。

Getting Started

快速入门

📄 Read: references/checkbox-getting-started.md
  • Installing
    @syncfusion/ej2-angular-buttons
    via
    ng add
  • CheckBoxModule
    import in standalone component's
    imports[]
  • CSS theme imports (material theme)
  • Minimal
    ejs-checkbox
    setup and running the app
  • Checked, unchecked, and indeterminate states
📄 阅读references/checkbox-getting-started.md
  • 通过
    ng add
    安装
    @syncfusion/ej2-angular-buttons
  • 在独立组件的
    imports[]
    中导入
    CheckBoxModule
  • CSS主题导入(material主题)
  • 最小化
    ejs-checkbox
    设置并运行应用
  • 选中、未选中和不确定状态

Label and Size

标签与尺寸

📄 Read: references/checkbox-label-and-size.md
  • label
    property for caption text
  • labelPosition
    (
    "Before"
    /
    "After"
    )
  • Small size via
    cssClass="e-small"
  • Default vs. small size examples
📄 阅读references/checkbox-label-and-size.md
  • label
    属性用于标题文本
  • labelPosition
    "Before"
    /
    "After"
  • 通过
    cssClass="e-small"
    设置小尺寸
  • 默认与小尺寸示例

Style and Appearance

样式与外观

📄 Read: references/checkbox-style-and-appearance.md
  • Color variant customization (primary, success, warning, danger, info) via
    cssClass
  • Custom checkbox frame shapes (round checkbox with
    e-custom
    )
  • Custom check icon with
    e-checkicon
  • CSS rules for appearance override
📄 阅读references/checkbox-style-and-appearance.md
  • 通过
    cssClass
    自定义颜色变体(primary、success、warning、danger、info)
  • 自定义复选框边框形状(使用
    e-custom
    实现圆形复选框)
  • 使用
    e-checkicon
    自定义勾选图标
  • 用于覆盖外观的CSS规则

Accessibility and RTL

无障碍性与RTL

📄 Read: references/checkbox-accessibility.md
  • WCAG 2.2 / Section 508 compliance
  • WAI-ARIA attributes (
    aria-disabled
    )
  • Keyboard navigation (Space key)
  • Right-to-left (
    enableRtl
    ) support
  • Screen reader support
📄 阅读references/checkbox-accessibility.md
  • WCAG 2.2 / Section 508合规
  • WAI-ARIA属性(
    aria-disabled
  • 键盘导航(空格键)
  • 从右到左(
    enableRtl
    )支持
  • 屏幕阅读器支持

How-To Guides

操作指南

📄 Read: references/checkbox-how-to.md
  • Name and value in form submission
  • Two-way binding with
    ngModel
  • Enabling right-to-left display
  • Customized checkbox appearance variants
📄 阅读references/checkbox-how-to.md
  • 表单提交中的名称和值
  • ngModel
    的双向绑定
  • 启用从右到左显示
  • 自定义复选框外观变体

API Reference

API参考

📄 Read: references/checkbox-api.md
  • All properties:
    checked
    ,
    cssClass
    ,
    disabled
    ,
    enableHtmlSanitizer
    ,
    enablePersistence
    ,
    enableRtl
    ,
    htmlAttributes
    ,
    indeterminate
    ,
    label
    ,
    labelPosition
    ,
    locale
    ,
    name
    ,
    value
  • Methods:
    click()
    ,
    destroy()
    ,
    focusIn()
  • Events:
    change
    ,
    created
📄 阅读references/checkbox-api.md
  • 所有属性:
    checked
    cssClass
    disabled
    enableHtmlSanitizer
    enablePersistence
    enableRtl
    htmlAttributes
    indeterminate
    label
    labelPosition
    locale
    name
    value
  • 方法:
    click()
    destroy()
    focusIn()
  • 事件:
    change
    created

Quick Start Example

快速入门示例

typescript
import { CheckBoxModule } from '@syncfusion/ej2-angular-buttons';
import { Component } from '@angular/core';

@Component({
  imports: [CheckBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div class="e-section-control">
      <ejs-checkbox label="Default"></ejs-checkbox>
    </div>`
})
export class AppComponent { }
CSS Theme Setup (
styles.css
):
css
@import '../node_modules/@syncfusion/ej2-base/styles/material.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material.css';
typescript
import { CheckBoxModule } from '@syncfusion/ej2-angular-buttons';
import { Component } from '@angular/core';

@Component({
  imports: [CheckBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div class="e-section-control">
      <ejs-checkbox label="Default"></ejs-checkbox>
    </div>`
})
export class AppComponent { }
CSS主题设置
styles.css
):
css
@import '../node_modules/@syncfusion/ej2-base/styles/material.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material.css';

Common Patterns

常见模式

Checked, Unchecked, and Indeterminate States

选中、未选中和不确定状态

typescript
@Component({
  imports: [CheckBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ul>
      <li><ejs-checkbox label="Checked" [checked]="true"></ejs-checkbox></li>
      <li><ejs-checkbox label="Unchecked"></ejs-checkbox></li>
      <li><ejs-checkbox label="Indeterminate" [indeterminate]="true"></ejs-checkbox></li>
    </ul>`
})
export class AppComponent { }
typescript
@Component({
  imports: [CheckBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ul>
      <li><ejs-checkbox label="Checked" [checked]="true"></ejs-checkbox></li>
      <li><ejs-checkbox label="Unchecked"></ejs-checkbox></li>
      <li><ejs-checkbox label="Indeterminate" [indeterminate]="true"></ejs-checkbox></li>
    </ul>`
})
export class AppComponent { }

Change Event Handler

变更事件处理程序

typescript
import { CheckBoxModule, ChangeEventArgs } from '@syncfusion/ej2-angular-buttons';
import { Component } from '@angular/core';

@Component({
  imports: [CheckBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-checkbox label="Subscribe" (change)="onChange($event)"></ejs-checkbox>`
})
export class AppComponent {
  onChange(args: ChangeEventArgs): void {
    console.log('Checked:', args.checked);
  }
}
typescript
import { CheckBoxModule, ChangeEventArgs } from '@syncfusion/ej2-angular-buttons';
import { Component } from '@angular/core';

@Component({
  imports: [CheckBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-checkbox label="Subscribe" (change)="onChange($event)"></ejs-checkbox>`
})
export class AppComponent {
  onChange(args: ChangeEventArgs): void {
    console.log('Checked:', args.checked);
  }
}

Form Submission with Name and Value

带名称和值的表单提交

typescript
@Component({
  imports: [CheckBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <form>
      <ejs-checkbox name="Sport" value="Cricket" label="Cricket" [checked]="true"></ejs-checkbox>
      <ejs-checkbox name="Sport" value="Hockey" label="Hockey" [checked]="true"></ejs-checkbox>
      <ejs-checkbox name="Sport" value="Tennis" label="Tennis" [disabled]="true"></ejs-checkbox>
      <button type="submit">Submit</button>
    </form>`
})
export class AppComponent { }
typescript
@Component({
  imports: [CheckBoxModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <form>
      <ejs-checkbox name="Sport" value="Cricket" label="Cricket" [checked]="true"></ejs-checkbox>
      <ejs-checkbox name="Sport" value="Hockey" label="Hockey" [checked]="true"></ejs-checkbox>
      <ejs-checkbox name="Sport" value="Tennis" label="Tennis" [disabled]="true"></ejs-checkbox>
      <button type="submit">Submit</button>
    </form>`
})
export class AppComponent { }

Two-Way Binding with ngModel

与ngModel的双向绑定

typescript
import { CheckBoxModule } from '@syncfusion/ej2-angular-buttons';
import { FormsModule } from '@angular/forms';
import { Component } from '@angular/core';

@Component({
  imports: [CheckBoxModule, FormsModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-checkbox [(ngModel)]="isChecked" label="Enable Feature"></ejs-checkbox>
    <p>State: {{ isChecked }}</p>`
})
export class AppComponent {
  public isChecked: boolean = false;
}
typescript
import { CheckBoxModule } from '@syncfusion/ej2-angular-buttons';
import { FormsModule } from '@angular/forms';
import { Component } from '@angular/core';

@Component({
  imports: [CheckBoxModule, FormsModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-checkbox [(ngModel)]="isChecked" label="Enable Feature"></ejs-checkbox>
    <p>State: {{ isChecked }}</p>`
})
export class AppComponent {
  public isChecked: boolean = false;
}

Key Properties

关键属性

PropertyTypeDefaultPurpose
label
string
''
Caption text next to checkbox
checked
boolean
false
Checked state
indeterminate
boolean
false
Indeterminate (partial) state
disabled
boolean
false
Disabled state
labelPosition
'Before' | 'After'
'After'
Label placement
cssClass
string
''
Custom CSS class(es)
name
string
''
Form field name
value
string
''
Form field value
enableRtl
boolean
false
Right-to-left rendering
enablePersistence
boolean
false
Persist state across page reloads via browser
localStorage
⚠️ Do not enable for sensitive or security-critical state
htmlAttributes
object
{}
Additional HTML attributes
属性类型默认值用途
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
通过浏览器
localStorage
跨页面重载持久化状态 ⚠️ 不要对敏感或安全关键状态启用此功能
htmlAttributes
object
{}
额外HTML属性

Key Methods

关键方法

MethodPurpose
click()
Programmatically toggle the checkbox
focusIn()
Set focus to the checkbox element
destroy()
Destroy the component instance
方法用途
click()
程序化切换复选框
focusIn()
将焦点设置到复选框元素
destroy()
销毁组件实例

Key Events

关键事件

EventWhen it FiresKey Args
(change)
Checked state changes
checked
,
event
(created)
Component initialized
事件触发时机关键参数
(change)
选中状态变化时
checked
,
event
(created)
组件初始化完成时

Common Use Cases

常见用例

  1. Multi-Select Form Fields — Group checkboxes with
    name
    /
    value
    for form POST
  2. Select All / Indeterminate — Parent checkbox with
    [indeterminate]
    based on child states
  3. Feature Toggles — Single checkbox with
    ngModel
    two-way binding
  4. Accessible Forms — WCAG-compliant checkboxes with keyboard and screen reader support
  5. Styled Checkboxes — Round or color-variant checkboxes via
    cssClass

For detailed implementation, start with references/checkbox-getting-started.md
  1. 多选表单字段 — 使用
    name
    /
    value
    分组复选框以进行表单POST提交
  2. 全选/不确定状态 — 父复选框根据子状态设置
    [indeterminate]
  3. 功能切换 — 带
    ngModel
    双向绑定的单个复选框
  4. 无障碍表单 — 符合WCAG标准的复选框,支持键盘和屏幕阅读器
  5. 样式化复选框 — 通过
    cssClass
    实现圆形或颜色变体复选框

如需详细实现,请从references/checkbox-getting-started.md开始

OTP Input

OTP Input组件

A focused skill for implementing and customizing the Syncfusion Angular
ejs-otpinput
component — a multi-box input control designed for one-time password (OTP) and verification code entry flows.
Package:
@syncfusion/ej2-angular-inputs

Selector:
ejs-otpinput

Module:
OtpInputModule
本指南专注于实现和自定义Syncfusion Angular
ejs-otpinput
组件——一款专为一次性密码(OTP)和验证码输入流程设计的多框输入控件。
包:
@syncfusion/ej2-angular-inputs

选择器:
ejs-otpinput

模块:
OtpInputModule

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Installation via
    ng add
  • Angular standalone vs module setup
  • Basic component rendering
  • CSS/SCSS theme imports
  • autoFocus and pre-filled value
📄 阅读references/getting-started.md
  • 通过
    ng add
    安装
  • Angular独立组件 vs 模块设置
  • 基础组件渲染
  • CSS/SCSS主题导入
  • autoFocus和预填充值

Input Types & Value

输入类型与值

📄 Read: references/input-types-and-value.md
  • Number type (digits only, default)
  • Text type (alphanumeric OTP)
  • Password type (masked entry)
  • textTransform (uppercase/lowercase/none)
  • Setting and reading the value property
📄 阅读references/input-types-and-value.md
  • 数字类型(仅数字,默认)
  • 文本类型(字母数字OTP)
  • 密码类型(掩码输入)
  • textTransform(大写/小写/无)
  • 设置和读取value属性

Appearance & Layout

外观与布局

📄 Read: references/appearance.md
  • Configuring OTP length
  • Disabled state
  • CSS classes (e-success, e-warning, e-error)
  • Separator between fields
  • Placeholder (single char or per-field string)
  • Styling modes: outlined, filled, underlined
📄 阅读references/appearance.md
  • 配置OTP长度
  • 禁用状态
  • CSS类(e-success、e-warning、e-error)
  • 字段间分隔符
  • 占位符(单个字符或每个字段的字符串)
  • 样式模式:outlined、filled、underlined

Events

事件

📄 Read: references/events.md
  • created
    — component ready
  • focus
    /
    blur
    — field focus events
  • input
    — per-character change
  • valueChanged
    — full OTP entered/changed
  • Practical: validate and submit on OTP completion
📄 阅读references/events.md
  • created
    — 组件就绪
  • focus
    /
    blur
    — 字段焦点事件
  • input
    — 逐字符变更
  • valueChanged
    — OTP完整输入/变更
  • 实践:OTP完成时验证并提交

Accessibility

无障碍性

📄 Read: references/accessibility.md
  • WCAG 2.2 / Section 508 / ADA compliance table
  • ARIA attributes (
    role=group
    ,
    aria-label
    )
  • ariaLabels
    property for per-field screen reader text
  • htmlAttributes
    for extra HTML attributes
  • Keyboard navigation shortcuts
  • RTL support (
    enableRtl
    )
📄 阅读references/accessibility.md
  • WCAG 2.2 / Section 508 / ADA合规表
  • ARIA属性(
    role=group
    aria-label
  • ariaLabels
    属性用于每个字段的屏幕阅读器文本
  • htmlAttributes
    用于额外HTML属性
  • 键盘导航快捷键
  • RTL支持(
    enableRtl

API Reference

API参考

📄 Read: references/api.md
  • All properties with types and defaults
  • Methods:
    focusIn
    ,
    focusOut
    ,
    destroy
  • All events with argument interfaces
  • Enum types: OtpInputStyle, OtpInputType, TextTransform

📄 阅读references/api.md
  • 所有属性的类型和默认值
  • 方法:
    focusIn
    focusOut
    destroy
  • 所有事件的参数接口
  • 枚举类型:OtpInputStyle、OtpInputType、TextTransform

Quick Start

快速入门

typescript
// app.ts (Angular 19+ standalone)
import { Component } from '@angular/core';
import { OtpInputModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  standalone: true,
  imports: [OtpInputModule],
  selector: 'app-root',
  template: `
    <div style="width: 350px;">
      <div ejs-otpinput
        id="otpinput"
        [length]="6"
        placeholder="x"
        (valueChanged)="onOtpComplete($event)">
      </div>
    </div>
  `
})
export class AppComponent {
  onOtpComplete(args: any) {
    console.log('OTP entered:', args.value);
  }
}
css
/* styles.css */
@import '@syncfusion/ej2-base/styles/material3.css';
@import '@syncfusion/ej2-inputs/styles/material3.css';

typescript
// app.ts (Angular 19+独立组件)
import { Component } from '@angular/core';
import { OtpInputModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  standalone: true,
  imports: [OtpInputModule],
  selector: 'app-root',
  template: `
    <div style="width: 350px;">
      <div ejs-otpinput
        id="otpinput"
        [length]="6"
        placeholder="x"
        (valueChanged)="onOtpComplete($event)">
      </div>
    </div>
  `
})
export class AppComponent {
  onOtpComplete(args: any) {
    console.log('OTP entered:', args.value);
  }
}
css
/* styles.css */
@import '@syncfusion/ej2-base/styles/material3.css';
@import '@syncfusion/ej2-inputs/styles/material3.css';

Common Patterns

常见模式

Numeric PIN (4 digits)

数字PIN(4位)

html
<div ejs-otpinput [length]="4" type="number"></div>
html
<div ejs-otpinput [length]="4" type="number"></div>

Masked password entry

掩码密码输入

html
<div ejs-otpinput [length]="6" type="password"></div>
html
<div ejs-otpinput [length]="6" type="password"></div>

OTP with separator and filled style

带分隔符和填充样式的OTP

html
<div ejs-otpinput [length]="6" separator="-" stylingMode="filled"></div>
html
<div ejs-otpinput [length]="6" separator="-" stylingMode="filled"></div>

Auto-submit when OTP is complete

OTP完成时自动提交

html
<div ejs-otpinput [length]="6" (valueChanged)="submitOtp($event)"></div>
html
<div ejs-otpinput [length]="6" (valueChanged)="submitOtp($event)"></div>

Error state after failed verification

验证失败后的错误状态

html
<div ejs-otpinput [length]="6" cssClass="e-error" [disabled]="false"></div>
html
<div ejs-otpinput [length]="6" cssClass="e-error" [disabled]="false"></div>

Accessible OTP with ARIA labels

带ARIA标签的无障碍OTP

html
<div ejs-otpinput
  [length]="4"
  [ariaLabels]="['Digit 1', 'Digit 2', 'Digit 3', 'Digit 4']">
</div>
html
<div ejs-otpinput
  [length]="4"
  [ariaLabels]="['Digit 1', 'Digit 2', 'Digit 3', 'Digit 4']">
</div>

Implementing Syncfusion Angular Range Slider

实现Syncfusion Angular Range Slider组件

The Range Slider is a versatile input component from Syncfusion EJ2 Angular that enables users to select single values or ranges from a continuous range. It supports multiple slider types, custom formatting, keyboard navigation, and advanced accessibility features.
Range Slider是Syncfusion EJ2 Angular的一款多功能输入组件,允许用户从连续范围中选择单个值或范围。它支持多种滑块类型、自定义格式化、键盘导航和高级无障碍功能。

Component Overview

组件概述

The Syncfusion Angular Range Slider (
ejs-slider
) provides:
  • Three slider types: Default (single), MinRange (start to current), Range (dual handles)
  • Orientations: Horizontal and vertical
  • Interactive elements: Tooltips, increment/decrement buttons, tick marks, limits
  • Advanced features: Custom formatting, keyboard shortcuts, RTL support
  • Full accessibility: WCAG 2.2, Section 508, keyboard navigation, ARIA attributes
  • Form integration: Reactive forms and template-driven forms support
Syncfusion Angular Range Slider(
ejs-slider
)提供:
  • 三种滑块类型:默认(单个值)、MinRange(从最小值到当前值)、Range(双滑块)
  • 方向:水平和垂直
  • 交互元素:工具提示、增量/减量按钮、刻度标记、限制
  • 高级功能:自定义格式化、键盘快捷键、RTL支持
  • 完整无障碍性:WCAG 2.2、Section 508、键盘导航、ARIA属性
  • 表单集成:响应式表单和模板驱动表单支持

Slider Types at a Glance

滑块类型概览

TypeUse CaseHandlesVisual
DefaultSingle value selection1Plain slider with one thumb
MinRangeStart-to-current range1Shows selection from min to thumb
RangeMin/max range selection2Shows selection between two thumbs
类型适用场景滑块数量视觉效果
Default单个值选择1带一个滑块的普通滑块
MinRange从最小值到当前值的范围选择1显示从最小值到滑块的选中区域
Range最小/最大范围选择2显示两个滑块之间的选中区域

Documentation & Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Installation of
    @syncfusion/ej2-angular-inputs
  • Package setup and imports
  • CSS theme configuration
  • First working example
  • Understanding slider types overview
📄 阅读references/getting-started.md
  • 安装
    @syncfusion/ej2-angular-inputs
  • 包设置和导入
  • CSS主题配置
  • 第一个工作示例
  • 滑块类型概述

Slider Types & Orientation

滑块类型与方向

📄 Read: references/slider-types-and-orientation.md
  • When to use Default vs MinRange vs Range types
  • Horizontal slider implementation (default)
  • Vertical slider for space-saving layouts
  • Practical implementation examples
  • Type selection decision matrix
📄 阅读references/slider-types-and-orientation.md
  • 何时使用Default vs MinRange vs Range类型
  • 水平滑块实现(默认)
  • 垂直滑块用于节省空间的布局
  • 实践实现示例
  • 类型选择决策矩阵

Ticks, Marks & Limits

刻度、标记与限制

📄 Read: references/ticks-and-limits.md
  • Adding tick marks to slider track
  • Configuring tick labels and format
  • Setting min/max limits and boundaries
  • Step value configuration
  • Custom tick positioning
📄 阅读references/ticks-and-limits.md
  • 为滑块轨道添加刻度标记
  • 配置刻度标签和格式
  • 设置最小/最大限制和边界
  • 步长值配置
  • 自定义刻度位置

Tooltips & Buttons

工具提示与按钮

📄 Read: references/tooltips-and-buttons.md
  • Enable/disable tooltips
  • Tooltip placement (Before, After, Above, Below)
  • Increment/decrement buttons setup
  • Button behavior in range sliders
  • Keyboard focus management
📄 阅读references/tooltips-and-buttons.md
  • 启用/禁用工具提示
  • 工具提示位置(Before、After、Above、Below)
  • 增量/减量按钮设置
  • 范围滑块中的按钮行为
  • 键盘焦点管理

Formatting & Value Display

格式化与值显示

📄 Read: references/formatting-and-values.md
  • Format API for numeric, percentage, currency formatting
  • Custom value formatting with events
  • Internationalization support
  • Using
    renderingTicks
    event for label transformation
  • Using
    tooltipChange
    event for tooltip customization
📄 阅读references/formatting-and-values.md
  • 用于数值、百分比、货币格式化的Format API
  • 使用事件自定义值格式化
  • 国际化支持
  • 使用
    renderingTicks
    事件转换标签
  • 使用
    tooltipChange
    事件自定义工具提示

Styling & Customization

样式与自定义

📄 Read: references/styling-and-customization.md
  • CSS classes for track, handle, buttons, ticks
  • Customizing colors and dimensions
  • Theme Studio integration
  • RTL (right-to-left) language support
  • Responsive design patterns
📄 阅读references/styling-and-customization.md
  • 轨道、滑块、按钮、刻度的CSS类
  • 自定义颜色和尺寸
  • 主题工作室集成
  • RTL(从右到左)语言支持
  • 响应式设计模式

Forms, Validation & Accessibility

表单、验证与无障碍性

📄 Read: references/form-integration-and-accessibility.md
  • Reactive forms with FormControl
  • Template-driven forms with ngModel
  • Form validation and error states
  • WCAG 2.2 and Section 508 compliance
  • Keyboard shortcuts (Arrow keys, Home, End, PageUp/PageDown)
  • ARIA attributes and screen reader support
📄 阅读references/form-integration-and-accessibility.md
  • 带FormControl的响应式表单
  • 带ngModel的模板驱动表单
  • 表单验证和错误状态
  • WCAG 2.2和Section 508合规
  • 键盘快捷键(箭头键、Home、End、PageUp/PageDown)
  • ARIA属性和屏幕阅读器支持

Advanced Scenarios

高级场景

📄 Read: references/advanced-scenarios.md
  • Date range slider implementation
  • Time range slider implementation
  • Numeric range slider with formatting
  • Reveal slider from hidden state
  • Performance optimization tips
  • Common pitfalls and troubleshooting
📄 阅读references/advanced-scenarios.md
  • 日期范围滑块实现
  • 时间范围滑块实现
  • 带格式化的数值范围滑块
  • 从隐藏状态显示滑块
  • 性能优化技巧
  • 常见陷阱与故障排除

API Reference

API参考

📄 Read: references/api.md
  • Complete property listing (
    value
    ,
    type
    ,
    min
    ,
    max
    ,
    step
    ,
    orientation
    ,
    ticks
    ,
    tooltip
    ,
    limits
    ,
    colorRange
    ,
    enabled
    ,
    readonly
    ,
    showButtons
    ,
    customValues
    ,
    enableRtl
    ,
    cssClass
    ,
    width
    ,
    enableAnimation
    ,
    enablePersistence
    )
  • All events (
    change
    ,
    changed
    ,
    created
    ,
    renderingTicks
    ,
    renderedTicks
    ,
    tooltipChange
    )
  • Methods (
    destroy
    ,
    reposition
    )
  • Data models:
    TicksDataModel
    ,
    TooltipDataModel
    ,
    LimitDataModel
    ,
    ColorRangeDataModel
  • EJ1 → EJ2 migration table
  • Verified code examples using only documented APIs
📄 阅读references/api.md
  • 完整属性列表(
    value
    type
    min
    max
    step
    orientation
    ticks
    tooltip
    limits
    colorRange
    enabled
    readonly
    showButtons
    customValues
    enableRtl
    cssClass
    width
    enableAnimation
    enablePersistence
  • 所有事件(
    change
    changed
    created
    renderingTicks
    renderedTicks
    tooltipChange
  • 方法(
    destroy
    reposition
  • 数据模型:
    TicksDataModel
    TooltipDataModel
    LimitDataModel
    ColorRangeDataModel
  • EJ1 → EJ2迁移表
  • 使用仅文档化API的验证代码示例

Quick Start Example

快速入门示例

Here's a minimal range slider in Angular 21+ (standalone):
typescript
import { SliderModule } from '@syncfusion/ej2-angular-inputs';
import { Component } from '@angular/core';

@Component({
  imports: [SliderModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div id="container">
      <h3>Range Slider</h3>
      <ejs-slider 
        id="range-slider"
        type="Range"
        [min]="0"
        [max]="100"
        [value]="[20, 80]"
        (change)="onSliderChange($event)">
      </ejs-slider>
      <p>Selected range: {{ selectedRange | json }}</p>
    </div>
  `,
  styles: [`
    #container {
      padding: 20px;
    }
    ejs-slider {
      width: 300px;
    }
  `]
})
export class App {
  selectedRange = [20, 80];

  onSliderChange(event: any) {
    this.selectedRange = event.value;
    console.log('Range changed:', this.selectedRange);
  }
}
CSS Theme Setup (in
styles.css
):
css
@import 'node_modules/@syncfusion/ej2-base/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-angular-inputs/styles/material3.css';
以下是Angular 21+(独立组件)中的最小范围滑块:
typescript
import { SliderModule } from '@syncfusion/ej2-angular-inputs';
import { Component } from '@angular/core';

@Component({
  imports: [SliderModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div id="container">
      <h3>Range Slider</h3>
      <ejs-slider 
        id="range-slider"
        type="Range"
        [min]="0"
        [max]="100"
        [value]="[20, 80]"
        (change)="onSliderChange($event)">
      </ejs-slider>
      <p>Selected range: {{ selectedRange | json }}</p>
    </div>
  `,
  styles: [`
    #container {
      padding: 20px;
    }
    ejs-slider {
      width: 300px;
    }
  `]
})
export class App {
  selectedRange = [20, 80];

  onSliderChange(event: any) {
    this.selectedRange = event.value;
    console.log('Range changed:', this.selectedRange);
  }
}
CSS主题设置(在
styles.css
中):
css
@import 'node_modules/@syncfusion/ej2-base/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-angular-inputs/styles/material3.css';

Common Patterns

常见模式

Pattern 1: Range Slider with Limits

模式1:带限制的范围滑块

typescript
<ejs-slider 
  type="Range"
  [min]="0"
  [max]="100"
  [value]="[25, 75]"
  [limits]="{ enabled: true, minStart: 10, minEnd: 90 }">
</ejs-slider>
typescript
<ejs-slider 
  type="Range"
  [min]="0"
  [max]="100"
  [value]="[25, 75]"
  [limits]="{ enabled: true, minStart: 10, minEnd: 90 }">
</ejs-slider>

Pattern 2: Slider with Ticks and Tooltip

模式2:带刻度和工具提示的滑块

typescript
<ejs-slider 
  type="Default"
  [value]="50"
  [ticks]="{ placement: 'Before', largeStep: 10, smallStep: 5 }"
  [tooltip]="{ isVisible: true, placement: 'After' }">
</ejs-slider>
typescript
<ejs-slider 
  type="Default"
  [value]="50"
  [ticks]="{ placement: 'Before', largeStep: 10, smallStep: 5 }"
  [tooltip]="{ isVisible: true, placement: 'After' }">
</ejs-slider>

Pattern 3: Vertical Slider

模式3:垂直滑块

typescript
<ejs-slider 
  type="Range"
  [value]="[30, 70]"
  orientation="Vertical"
  [style.height]="'300px'">
</ejs-slider>
typescript
<ejs-slider 
  type="Range"
  [value]="[30, 70]"
  orientation="Vertical"
  [style.height]="'300px'">
</ejs-slider>

Pattern 4: Percentage Formatted Slider

模式4:百分比格式化滑块

typescript
<ejs-slider 
  type="Range"
  [value]="[20, 80]"
  [ticks]="{ format: 'P0' }"
  [tooltip]="{ format: 'P0' }">
</ejs-slider>
typescript
<ejs-slider 
  type="Range"
  [value]="[20, 80]"
  [ticks]="{ format: 'P0' }"
  [tooltip]="{ format: 'P0' }">
</ejs-slider>

Key Props & Configuration

关键属性与配置

Properties

属性

PropTypeDefaultPurpose
type
string
'Default'
Slider type:
'Default'
,
'MinRange'
,
'Range'
value
number | number[]
null
Current value; use
number[]
for Range type
min
number
0
Minimum slider value
max
number
100
Maximum slider value
step
number
1
Increment/decrement amount per interaction
orientation
string
'Horizontal'
'Horizontal'
or
'Vertical'
ticks
TicksDataModel
Tick marks (placement, largeStep, smallStep, format)
tooltip
TooltipDataModel
Tooltip (isVisible, placement, showOn, format)
limits
LimitDataModel
Restrict thumb movement; must set
enabled: true
colorRange
ColorRangeDataModel[]
Color segments applied to the track
enabled
boolean
true
Enable/disable slider
readonly
boolean
false
Show value but block user interaction
showButtons
boolean
false
Show increment/decrement buttons
enableRtl
boolean
false
Right-to-left rendering
customValues
string[] | number[]
null
Discrete value array; overrides min/max/step
cssClass
string
''
Custom CSS class(es) on the slider host element
width
number | string
null
Slider width (px or CSS string)
enableAnimation
boolean
true
Animate thumb movement
enablePersistence
boolean
false
Persist value in localStorage across reloads
locale
string
''
Locale override for value formatting
属性类型默认值用途
type
string
'Default'
滑块类型:
'Default'
'MinRange'
'Range'
value
number | number[]
null
当前值;Range类型使用
number[]
min
number
0
滑块最小值
max
number
100
滑块最大值
step
number
1
每次交互的增量/减量值
orientation
string
'Horizontal'
'Horizontal'
'Vertical'
ticks
TicksDataModel
刻度标记(位置、largeStep、smallStep、格式)
tooltip
TooltipDataModel
工具提示(isVisible、位置、showOn、格式)
limits
LimitDataModel
限制滑块移动;必须设置
enabled: true
colorRange
ColorRangeDataModel[]
应用于轨道的颜色分段
enabled
boolean
true
启用/禁用滑块
readonly
boolean
false
显示值但阻止用户交互
showButtons
boolean
false
显示增量/减量按钮
enableRtl
boolean
false
从右到左渲染
customValues
string[] | number[]
null
离散值数组;覆盖min/max/step
cssClass
string
''
滑块宿主元素上的自定义CSS类(多个)
width
number | string
null
滑块宽度(px或CSS字符串)
enableAnimation
boolean
true
滑块移动动画
enablePersistence
boolean
false
跨重载在localStorage中持久化值
locale
string
''
值格式化的区域覆盖

Events

事件

EventFires whenArgs key properties
(change)
During drag (continuous)
args.value
,
args.previousValue
(changed)
After drag completes (once)
args.value
,
args.previousValue
(created)
Slider is initialized
(renderingTicks)
Each tick is rendering
args.value
, assign
args.text
(renderedTicks)
All ticks have rendered
args.ticksWrapper
(DOM)
(tooltipChange)
Tooltip is about to show
args.value
, assign
args.text
事件触发时机关键属性参数
(change)
拖动过程中(连续触发)
args.value
,
args.previousValue
(changed)
拖动完成后(触发一次)
args.value
,
args.previousValue
(created)
滑块初始化完成时
(renderingTicks)
每个刻度渲染时
args.value
, 赋值
args.text
(renderedTicks)
所有刻度渲染完成时
args.ticksWrapper
(DOM元素)
(tooltipChange)
工具提示即将显示时
args.value
, 赋值
args.text

Methods (via
@ViewChild
)

方法(通过
@ViewChild
调用)

MethodReturnsPurpose
reposition()
void
Re-render after reveal from hidden state
destroy()
void
Remove component and detach event listeners
方法返回值用途
reposition()
void
从隐藏状态显示后重新渲染
destroy()
void
移除组件并解绑事件监听器

Common Use Cases

常见用例

Use Case 1: Price Filter
  • Type: Range
  • Range: $0-$1000 with $100 steps
  • Format: Currency (e.g., "$250")
  • Tooltips: Visible with currency format
Use Case 2: Date Range Selector
  • Type: Range
  • Range: 0-365 (days)
  • Format: Custom (date string from number)
  • Ticks: Monthly intervals
Use Case 3: Volume Control
  • Type: Default
  • Range: 0-100
  • Format: Percentage (0% - 100%)
  • Orientation: Vertical
Use Case 4: Form Input with Validation
  • Type: Range
  • Integration: Reactive FormControl
  • Validation: Min 20, Max 80
  • Error display on invalid state
用例1:价格筛选
  • 类型:Range
  • 范围:$0-$1000,步长$100
  • 格式:货币(例如"$250")
  • 工具提示:可见并带货币格式
用例2:日期范围选择器
  • 类型:Range
  • 范围:0-365(天)
  • 格式:自定义(将数字转换为日期字符串)
  • 刻度:月度间隔
用例3:音量控制
  • 类型:Default
  • 范围:0-100
  • 格式:百分比(0% - 100%)
  • 方向:垂直
用例4:带验证的表单输入
  • 类型:Range
  • 集成:响应式FormControl
  • 验证:最小值20,最大值80
  • 无效状态时显示错误

Next Steps

下一步

  1. Start with Getting Started - Set up the component and understand types
  2. Choose your slider type - Read "Slider Types & Orientation"
  3. Configure features - Add ticks, tooltips, buttons as needed
  4. Format values - Implement percentage, currency, or custom formats
  5. Add accessibility - Review keyboard nav and ARIA attributes
  6. Style & customize - Apply theme and CSS customization
  7. Integrate with forms - Bind to FormControl or ngModel with validation
  8. Handle edge cases - Review advanced scenarios and troubleshooting

For detailed implementation, start with references/getting-started.md
  1. 从快速入门开始 - 设置组件并了解类型
  2. 选择滑块类型 - 阅读"滑块类型与方向"
  3. 配置功能 - 添加刻度、工具提示、按钮等
  4. 格式化值 - 实现百分比、货币或自定义格式
  5. 添加无障碍性 - 查看键盘导航和ARIA属性
  6. 样式与自定义 - 应用主题和CSS自定义
  7. 与表单集成 - 绑定到FormControl或ngModel并添加验证
  8. 处理边缘情况 - 查看高级场景和故障排除

如需详细实现,请从references/getting-started.md开始

Syncfusion Angular TextArea Component

Syncfusion Angular TextArea组件

The Syncfusion Angular TextArea (
ejs-textarea
) provides a feature-rich multiline text input with floating labels, resize modes, adornments, form integration, and full accessibility support.
Syncfusion Angular TextArea(
ejs-textarea
)提供功能丰富的多行文本输入,支持浮动标签、调整大小模式、装饰元素、表单集成和完整的无障碍支持。

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Package installation (
    @syncfusion/ej2-angular-inputs
    )
  • Standalone Angular 19+ component setup
  • CSS/theme imports
  • Basic TextArea rendering
  • Getting and setting values (value property, ngModel, change event)
📄 阅读references/getting-started.md
  • 包安装(
    @syncfusion/ej2-angular-inputs
  • Angular 19+独立组件设置
  • CSS/主题导入
  • 基础TextArea渲染
  • 获取和设置值(value属性、ngModel、change事件)

Configuration

配置

📄 Read: references/configuration.md
  • Floating label (
    floatLabelType
    : Auto / Always / Never)
  • Placeholder with localization (
    locale
    property)
  • Rows and columns (
    rows
    /
    cols
    properties)
  • Max length (
    maxLength
    property)
  • Resize modes (
    resizeMode
    : Vertical / Horizontal / Both / None)
  • Width customization (
    width
    property)
📄 阅读references/configuration.md
  • 浮动标签(
    floatLabelType
    : Auto / Always / Never)
  • 带本地化的占位符(
    locale
    属性)
  • 行和列(
    rows
    /
    cols
    属性)
  • 最大长度(
    maxLength
    属性)
  • 调整大小模式(
    resizeMode
    : Vertical / Horizontal / Both / None)
  • 宽度自定义(
    width
    属性)

Adornments

装饰元素

📄 Read: references/adornments.md
  • Prepend/append custom templates (
    prependTemplate
    /
    appendTemplate
    )
  • Adornment flow and orientation (
    adornmentFlow
    /
    adornmentOrientation
    )
  • Common patterns: icons, formatting buttons, action buttons
📄 阅读references/adornments.md
  • 前缀/后缀自定义模板(
    prependTemplate
    /
    appendTemplate
  • 装饰元素流和方向(
    adornmentFlow
    /
    adornmentOrientation
  • 常见模式:图标、格式化按钮、操作按钮

Events

事件

📄 Read: references/events.md
  • created
    ,
    destroyed
    lifecycle events
  • input
    — real-time value changes (
    InputEventArgs
    )
  • change
    — value changed on blur (
    ChangedEventArgs
    )
  • focus
    /
    blur
    — focus state events (
    FocusInEventArgs
    /
    FocusOutEventArgs
    )
📄 阅读references/events.md
  • created
    ,
    destroyed
    生命周期事件
  • input
    — 实时值变更(
    InputEventArgs
  • change
    — 失去焦点时值变更(
    ChangedEventArgs
  • focus
    /
    blur
    — 焦点状态事件(
    FocusInEventArgs
    /
    FocusOutEventArgs

Style & Appearance

样式与外观

📄 Read: references/style-appearance.md
  • Size variants (
    e-small
    ,
    e-bigger
    )
  • Filled and outline modes (
    e-filled
    ,
    e-outline
    )
  • Custom CSS via
    cssClass
    property
  • Disabled (
    enabled: false
    ) and read-only (
    readonly: true
    ) states
  • Show/hide clear button (
    showClearButton
    )
  • Rounded corners, static clear button, RTL (
    enableRtl
    )
  • Custom background, text, and border color overrides
  • Floating label color for validation states
📄 阅读references/style-appearance.md
  • 尺寸变体(
    e-small
    ,
    e-bigger
  • 填充和轮廓模式(
    e-filled
    ,
    e-outline
  • 通过
    cssClass
    属性自定义CSS
  • 禁用(
    enabled: false
    )和只读(
    readonly: true
    )状态
  • 显示/隐藏清除按钮(
    showClearButton
  • 圆角、静态清除按钮、RTL(
    enableRtl
  • 自定义背景、文本和边框颜色覆盖
  • 验证状态的浮动标签颜色

Form Support

表单支持

📄 Read: references/form-support.md
  • HTML form integration
  • FormValidator integration (required, minLength, maxLength, pattern)
  • State persistence (
    enablePersistence
    )
  • Custom HTML attributes (
    htmlAttributes
    )
📄 阅读references/form-support.md
  • HTML表单集成
  • FormValidator集成(required、minLength、maxLength、pattern)
  • 状态持久化(
    enablePersistence
  • 自定义HTML属性(
    htmlAttributes

API Reference

API参考

📄 Read: references/api.md
  • All properties, methods, and events with types and defaults
  • Enum types:
    FloatLabelType
    ,
    Resize
    ,
    AdornmentsDirection
📄 阅读references/api.md
  • 所有属性、方法和事件的类型和默认值
  • 枚举类型:
    FloatLabelType
    ,
    Resize
    ,
    AdornmentsDirection

Quick Start

快速入门

bash
ng add @syncfusion/ej2-angular-inputs
typescript
import { Component } from '@angular/core';
import { TextAreaModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  standalone: true,
  imports: [TextAreaModule],
  selector: 'app-root',
  template: `
    <ejs-textarea
      id="comments"
      placeholder="Enter your comments"
      [floatLabelType]="'Auto'"
      [rows]="4"
      [maxLength]="500">
    </ejs-textarea>
  `
})
export class AppComponent {}
css
/* styles.css */
@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
bash
ng add @syncfusion/ej2-angular-inputs
typescript
import { Component } from '@angular/core';
import { TextAreaModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  standalone: true,
  imports: [TextAreaModule],
  selector: 'app-root',
  template: `
    <ejs-textarea
      id="comments"
      placeholder="Enter your comments"
      [floatLabelType]="'Auto'"
      [rows]="4"
      [maxLength]="500">
    </ejs-textarea>
  `
})
export class AppComponent {}
css
/* styles.css */
@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';

Common Patterns

常见模式

Two-Way Binding with ngModel

与ngModel的双向绑定

typescript
import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { TextAreaModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  standalone: true,
  imports: [TextAreaModule, FormsModule],
  selector: 'app-root',
  template: `<ejs-textarea [(ngModel)]="comment" placeholder="Add comment"></ejs-textarea>`
})
export class AppComponent {
  comment: string = '';
}
typescript
import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { TextAreaModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  standalone: true,
  imports: [TextAreaModule, FormsModule],
  selector: 'app-root',
  template: `<ejs-textarea [(ngModel)]="comment" placeholder="Add comment"></ejs-textarea>`
})
export class AppComponent {
  comment: string = '';
}

Disabled TextArea

禁用的TextArea

html
<ejs-textarea [enabled]="false" value="Read-only content"></ejs-textarea>
html
<ejs-textarea [enabled]="false" value="Read-only content"></ejs-textarea>

Resize Control

调整大小控制

html
<!-- Vertical resize only -->
<ejs-textarea resizeMode="Vertical" [rows]="4"></ejs-textarea>

<!-- No resize -->
<ejs-textarea resizeMode="None" [rows]="4" [cols]="50"></ejs-textarea>
html
<!-- 仅垂直调整大小 -->
<ejs-textarea resizeMode="Vertical" [rows]="4"></ejs-textarea>

<!-- 不可调整大小 -->
<ejs-textarea resizeMode="None" [rows]="4" [cols]="50"></ejs-textarea>

With Floating Label

带浮动标签

html
<ejs-textarea floatLabelType="Auto" placeholder="Description"></ejs-textarea>
html
<ejs-textarea floatLabelType="Auto" placeholder="Description"></ejs-textarea>