syncfusion-blazor-inputs
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion Blazor FileUpload
实现Syncfusion Blazor FileUpload组件
This skill covers the Syncfusion Blazor FileUpload component, a robust solution for file handling in Blazor applications. Learn to implement single and multiple file uploads, configure validation rules, enable drag-drop interactions, handle large files with chunked uploads, and leverage comprehensive events for complete upload control and user feedback.
本内容介绍Syncfusion Blazor FileUpload组件,这是Blazor应用中处理文件的可靠解决方案。学习实现单文件和多文件上传、配置验证规则、启用拖拽交互、通过分块上传处理大文件,以及利用丰富的事件实现完整的上传控制和用户反馈。
FileUpload
FileUpload
Learn to implement Syncfusion Blazor File Upload component with async/sync uploads, validation, events, customization, and always get immediate file handling with drag-drop or form integration for web and server applications.
学习实现Syncfusion Blazor文件上传组件,支持异步/同步上传、验证、事件、自定义,在Web和服务器应用中通过拖拽或表单集成实现即时文件处理。
Documentation
文档
Getting Started
快速入门
📄 Read: references/file-upload-getting-started.md
- Installation and NuGet package setup
- Visual Studio/Visual Studio Code setup steps
- Blazor WebAssembly vs Server configuration
- Basic SfUploader component rendering
- CSS and script imports
- Minimal working example
📄 阅读: references/file-upload-getting-started.md
- 安装和NuGet包配置
- Visual Studio/Visual Studio Code设置步骤
- Blazor WebAssembly与Server配置对比
- 基础SfUploader组件渲染
- CSS和脚本导入
- 最简运行示例
Core Configuration
核心配置
📄 Read: references/file-upload-configuration.md
- ID property for component identification
- AllowedExtensions for file type restriction
- AllowMultiple vs single file uploads
- AutoUpload behavior configuration
- SequentialUpload for ordered processing
- DirectoryUpload capability
- Enabled state and component control
📄 阅读: references/file-upload-configuration.md
- 用于组件标识的ID属性
- 限制文件类型的AllowedExtensions
- 多文件上传与单文件上传的AllowMultiple配置
- AutoUpload行为配置
- 有序处理的SequentialUpload
- 目录上传能力
- 组件启用状态控制
Upload Methods & Behavior
上传方法与行为
📄 Read: references/file-upload-file-upload-methods.md
- Synchronous vs asynchronous uploads
- Save URL and Remove URL configuration
- Upload button click handlers
- Automatic vs manual upload triggering
- Upload progress tracking mechanisms
- Backend API requirements
📄 阅读: references/file-upload-file-upload-methods.md
- 同步与异步上传
- Save URL和Remove URL配置
- 上传按钮点击处理器
- 自动与手动上传触发
- 上传进度跟踪机制
- 后端API要求
Events & Handlers
事件与处理器
📄 Read: references/file-upload-events-and-handlers.md
- ValueChange event for direct file access (Blazor Server only, without AsyncSettings)
- FileSelected event for pre-validation
- Created event for initialization logic
- OnFileListRender for custom file display
- OnUploadStart, Success, OnFailure events (use with AsyncSettings)
- Event handler patterns and best practices
- Important: ValueChange and UploaderAsyncSettings are mutually exclusive
📄 阅读: references/file-upload-events-and-handlers.md
- 直接访问文件的ValueChange事件(仅Blazor Server,不使用AsyncSettings)
- 预验证的FileSelected事件
- 初始化逻辑的Created事件
- 自定义文件显示的OnFileListRender
- 上传开始、成功、失败事件(配合AsyncSettings使用)
- 事件处理器模式与最佳实践
- 重要提示: ValueChange与UploaderAsyncSettings互斥
File Validation
文件验证
📄 Read: references/file-upload-validation.md
- File type validation strategies
- File size constraints (MinFileSize, MaxFileSize)
- Custom validation functions
- Preventing invalid file uploads
- Error messages and user feedback
- Validation within EditForm
📄 阅读: references/file-upload-validation.md
- 文件类型验证策略
- 文件大小限制(MinFileSize、MaxFileSize)
- 自定义验证函数
- 阻止无效文件上传
- 错误提示与用户反馈
- EditForm中的验证
Advanced Features
高级特性
📄 Read: references/file-upload-advanced-features.md
- Chunked upload for large files
- Pause and resume functionality
- Async/await patterns in event handlers
- MemoryStream processing without disk I/O
- Batch upload operations
- Retry and recovery mechanisms
📄 阅读: references/file-upload-advanced-features.md
- 大文件分块上传
- 暂停与恢复功能
- 事件处理器中的Async/await模式
- 无需磁盘I/O的MemoryStream处理
- 批量上传操作
- 重试与恢复机制
Customization & Styling
自定义与样式
📄 Read: references/file-upload-customization.md
- Custom file list templates
- CSS class customization
- Theme Studio integration
- Custom button styling
- Dark mode support
- Responsive design patterns
📄 阅读: references/file-upload-customization.md
- 自定义文件列表模板
- CSS类自定义
- Theme Studio集成
- 自定义按钮样式
- 深色模式支持
- 响应式设计模式
File Source Options
文件来源选项
📄 Read: references/file-upload-file-source-options.md
- Drag-and-drop upload implementation
- Form integration patterns
- Direct file picker interaction
- Browser file dialog usage
- Directory selection and upload
- Multiple input method combinations
- Accessibility best practices
📄 阅读: references/file-upload-file-source-options.md
- 拖拽上传实现
- 表单集成模式
- 直接文件选择器交互
- 浏览器文件对话框使用
- 目录选择与上传
- 多种输入方式组合
- 无障碍最佳实践
Localization & Accessibility
本地化与无障碍
📄 Read: references/file-upload-localization-accessibility.md
- Multi-language UI support
- Locale configuration options
- Custom text labels
- WCAG 2.1 compliance
- Keyboard navigation implementation
- Screen reader support
- ARIA attributes
📄 阅读: references/file-upload-localization-accessibility.md
- 多语言UI支持
- 区域设置配置选项
- 自定义文本标签
- WCAG 2.1合规性
- 键盘导航实现
- 屏幕阅读器支持
- ARIA属性
Platform-Specific Setup
平台特定设置
📄 Read: references/file-upload-platform-specific-setup.md
- Blazor WebAssembly app setup
- Blazor Server app setup
- Blazor Web App (.NET 8+) setup
- MAUI integration
- Different render modes
- Platform-specific considerations
📄 阅读: references/file-upload-platform-specific-setup.md
- Blazor WebAssembly应用设置
- Blazor Server应用设置
- Blazor Web App(.NET 8+)设置
- MAUI集成
- 不同渲染模式
- 平台特定注意事项
Quick Start Example
快速入门示例
razor
@using Syncfusion.Blazor.Inputs
<SfUploader AutoUpload="true" AllowedExtensions=".jpg,.jpeg,.png,.pdf">
<UploaderAsyncSettings
SaveUrl="api/upload/save"
RemoveUrl="api/upload/remove">
</UploaderAsyncSettings>
</SfUploader>razor
@using Syncfusion.Blazor.Inputs
<SfUploader AutoUpload="true" AllowedExtensions=".jpg,.jpeg,.png,.pdf">
<UploaderAsyncSettings
SaveUrl="api/upload/save"
RemoveUrl="api/upload/remove">
</UploaderAsyncSettings>
</SfUploader>Common Patterns
常见模式
Pattern 1: Basic File Upload with Validation (Server Upload)
模式1:带验证的基础文件上传(服务器上传)
- Use for instant uploads
AutoUpload="true" - Configure with SaveUrl/RemoveUrl
UploaderAsyncSettings - Set to restrict file types
AllowedExtensions - Listen to event for pre-validation
FileSelected - Use /
Successevents for upload feedbackOnFailure
- 使用实现即时上传
AutoUpload="true" - 配置的SaveUrl/RemoveUrl
UploaderAsyncSettings - 设置限制文件类型
AllowedExtensions - 监听事件进行预验证
FileSelected - 使用/
Success事件提供上传反馈OnFailure
Pattern 2: Direct File Access (Blazor Server Only)
模式2:直接文件访问(仅Blazor Server)
- Use event to access file content directly
ValueChange - Do NOT use with ValueChange
UploaderAsyncSettings - Process files in memory or save to directory
- Best for file preview, Base64 conversion, or direct storage
- 使用事件直接访问文件内容
ValueChange - 请勿将与
ValueChange一起使用UploaderAsyncSettings - 在内存中处理文件或保存到目录
- 适用于文件预览、Base64转换或直接存储
Pattern 3: Multiple File Handling
模式3:多文件处理
- Set to allow batch uploads
AllowMultiple="true" - Use for ordered processing
SequentialUpload - Track progress with upload events
- Display file list with individual progress indicators
- 设置允许批量上传
AllowMultiple="true" - 使用实现有序处理
SequentialUpload - 通过上传事件跟踪进度
- 显示带单独进度指示器的文件列表
Pattern 4: Large File Upload with Chunking
模式4:大文件分块上传
- Configure in
ChunkSizeUploaderAsyncSettings - Enable pause/resume with chunk upload
- Implement retry logic for failed chunks
- Show chunk-level progress to user
- 在中配置
UploaderAsyncSettingsChunkSize - 启用分块上传的暂停/恢复功能
- 为失败分块实现重试逻辑
- 向用户显示分块级进度
Key Props
关键属性
| Property | Default | Use When |
|---|---|---|
| AutoUpload | true | Upload files immediately after selection |
| AllowMultiple | true | User needs to upload multiple files |
| SequentialUpload | false | Files must upload one at a time |
| AllowedExtensions | "" | Only specific file types allowed |
| DirectoryUpload | false | User can select entire folders |
| MaxFileSize | 28.4 MB | Limiting maximum upload file size |
| MinFileSize | 0 | Setting minimum file size requirement |
| ChunkSize | 0 (disabled) | Enable chunked upload for large files |
| ShowFileList | true | Control visibility of uploaded file list |
| ShowProgressBar | true | Display upload progress indicator |
| Enabled | true | Enable or disable the uploader |
| DropArea | null | Specify custom drop zone CSS selector |
| CssClass | "" | Apply custom CSS classes |
| TabIndex | 0 | Set tab navigation order |
| EnablePersistence | false | Maintain state across page reloads |
| EnableRtl | false | Enable right-to-left layout |
| 属性 | 默认值 | 使用场景 |
|---|---|---|
| AutoUpload | true | 选择文件后立即上传 |
| AllowMultiple | true | 用户需要上传多个文件 |
| SequentialUpload | false | 文件必须逐个上传 |
| AllowedExtensions | "" | 仅允许特定文件类型 |
| DirectoryUpload | false | 用户可选择整个文件夹 |
| MaxFileSize | 28.4 MB | 限制最大上传文件大小 |
| MinFileSize | 0 | 设置最小文件大小要求 |
| ChunkSize | 0(禁用) | 为大文件启用分块上传 |
| ShowFileList | true | 控制已上传文件列表的可见性 |
| ShowProgressBar | true | 显示上传进度指示器 |
| Enabled | true | 启用或禁用上传器 |
| DropArea | null | 指定自定义拖拽区域CSS选择器 |
| CssClass | "" | 应用自定义CSS类 |
| TabIndex | 0 | 设置Tab导航顺序 |
| EnablePersistence | false | 跨页面重载保持状态 |
| EnableRtl | false | 启用从右到左布局 |
Common Use Cases
常见用例
- Document Upload: Resume, PDF, certification file uploads
- Image Gallery: User profile pictures, photo collections
- Data Import: CSV/Excel file imports for data processing
- Media Library: Video, audio file uploads and management
- Backup Uploads: Database backups, configuration files
- Report Generation: Monthly reports, analytics data
- Invoice Processing: Financial document uploads
- User Attachments: Email attachments, message files
- 文档上传:简历、PDF、证书文件上传
- 图片库:用户头像、照片集
- 数据导入:CSV/Excel文件导入用于数据处理
- 媒体库:视频、音频文件上传与管理
- 备份上传:数据库备份、配置文件
- 报告生成:月度报告、分析数据
- 发票处理:财务文档上传
- 用户附件:邮件附件、消息文件
Quick Decision Tree
快速决策树
User needs file upload functionality
├─ Single file only? → Set + use basic setup
├─ Multiple files?
│ ├─ All at once? → +
│ └─ One at a time? → +
└─ Large files (>100MB)?
├─ Enable chunking → Set property
└─ Add pause/resume → Listen to and events
AllowMultiple="false"AllowMultiple="true"SequentialUpload="false"AllowMultiple="true"SequentialUpload="true"ChunkSizePausedOnResume用户需要文件上传功能
├─ 仅单文件?→ 设置 + 基础配置
├─ 多文件?
│ ├─ 同时上传?→ +
│ └─ 逐个上传?→ +
└─ 大文件(>100MB)?
├─ 启用分块→ 设置属性
└─ 添加暂停/恢复→ 监听和事件
AllowMultiple="false"AllowMultiple="true"SequentialUpload="false"AllowMultiple="true"SequentialUpload="true"ChunkSizePausedOnResumeTextArea
TextArea
Learn to implement Syncfusion Blazor TextArea component for multi-line text input with configurable resize modes, row/column sizing, character limits, floating labels, and comprehensive validation. Perfect for comments, descriptions, messages, and any scenario requiring extended text entry with real-time feedback and form integration.
学习实现Syncfusion Blazor TextArea组件,用于多行文本输入,支持可配置的调整大小模式、行列尺寸、字符限制、浮动标签和全面验证。适用于评论、描述、消息等需要扩展文本输入并提供实时反馈和表单集成的场景。
Documentation
文档
Getting Started
快速入门
📄 Read: references/textarea-getting-started.md
- Installation and NuGet package setup
- Basic SfTextArea component setup
- Namespace imports and service registration
- CSS theme configuration
- Minimal working example
- Initial component rendering
📄 阅读: references/textarea-getting-started.md
- 安装和NuGet包配置
- 基础SfTextArea组件设置
- 命名空间导入和服务注册
- CSS主题配置
- 最简运行示例
- 初始组件渲染
Configuration Options
配置选项
📄 Read: references/textarea-configuration.md
- RowCount and ColumnCount for sizing
- ResizeMode (Vertical, Horizontal, Both, None)
- MaxLength property for character limits
- Placeholder text configuration
- FloatLabelType (Auto, Always, Never)
- ReadOnly and Disabled states
- Width property and responsive sizing
- HTML attributes customization
📄 阅读: references/textarea-configuration.md
- 用于尺寸设置的RowCount和ColumnCount
- ResizeMode(Vertical、Horizontal、Both、None)
- 字符限制的MaxLength属性
- 占位符文本配置
- FloatLabelType(Auto、Always、Never)
- 只读和禁用状态
- Width属性与响应式尺寸
- HTML属性自定义
Events and Data Binding
事件与数据绑定
📄 Read: references/textarea-events-binding.md
- Value property and two-way binding (@bind-Value)
- ValueChange event for real-time updates
- Focus and Blur events (TextAreaFocusInEventArgs, TextAreaFocusOutEventArgs)
- Input event for keystroke tracking
- Created and Destroyed lifecycle events
- Form validation integration with EditForm
- ValueExpression for validation binding
📄 阅读: references/textarea-events-binding.md
- Value属性与双向绑定(@bind-Value)
- 实时更新的ValueChange事件
- Focus和Blur事件(TextAreaFocusInEventArgs、TextAreaFocusOutEventArgs)
- 按键跟踪的Input事件
- Created和Destroyed生命周期事件
- 与EditForm的表单验证集成
- 用于验证绑定的ValueExpression
Customization and Styling
自定义与样式
📄 Read: references/textarea-customization.md
- CssClass for custom styling
- ShowClearButton for quick text removal
- InputAttributes and HtmlAttributes
- Theme customization with Theme Studio
- Responsive design patterns
- Accessibility features (ARIA, keyboard navigation)
- RTL (Right-to-Left) support with EnableRtl
📄 阅读: references/textarea-customization.md
- 用于自定义样式的CssClass
- 快速清除文本的ShowClearButton
- InputAttributes和HtmlAttributes
- 与Theme Studio的主题自定义
- 响应式设计模式
- 无障碍特性(ARIA、键盘导航)
- 启用从右到左布局的EnableRtl
Quick Start Example
快速入门示例
razor
@using Syncfusion.Blazor.Inputs
<SfTextArea @bind-Value="@description"
Placeholder="Enter description..."
RowCount="5"
ColumnCount="50"
MaxLength="500"
FloatLabelType="FloatLabelType.Auto">
</SfTextArea>
@code {
private string description = "";
}razor
@using Syncfusion.Blazor.Inputs
<SfTextArea @bind-Value="@description"
Placeholder="输入描述..."
RowCount="5"
ColumnCount="50"
MaxLength="500"
FloatLabelType="FloatLabelType.Auto">
</SfTextArea>
@code {
private string description = "";
}Common Patterns
常见模式
Pattern 1: Basic Multi-Line Input
模式1:基础多行输入
- Use to set visible lines (default: 2)
RowCount - Set for user guidance
Placeholder - Enable for two-way binding
@bind-Value - Apply for character constraints
MaxLength
- 使用设置可见行数(默认:2)
RowCount - 设置提供用户引导
Placeholder - 启用实现双向绑定
@bind-Value - 应用限制字符数
MaxLength
Pattern 2: Resizable TextArea with Limits
模式2:带限制的可调整大小TextArea
- Set for user resizing
ResizeMode="Resize.Both" - Configure and
RowCountfor initial sizeColumnCount - Use to prevent excessive input
MaxLength - Listen to for live character counting
ValueChange
- 设置允许用户调整大小
ResizeMode="Resize.Both" - 配置和
RowCount设置初始尺寸ColumnCount - 使用防止过度输入
MaxLength - 监听实现实时字符计数
ValueChange
Pattern 3: Form Integration with Validation
模式3:带验证的表单集成
- Wrap in with model binding
<EditForm> - Use with
@bind-ValueValueExpression - Apply or
[Required]attributes[StringLength] - Display validation messages with
<ValidationMessage> - Style invalid state with CSS
- 包裹在中并绑定模型
<EditForm> - 将与
@bind-Value配合使用ValueExpression - 应用或
[Required]属性[StringLength] - 使用显示验证消息
<ValidationMessage> - 用CSS设置无效状态样式
Pattern 4: Auto-Growing TextArea
模式4:自动扩展TextArea
- Set for vertical expansion
ResizeMode="Resize.Vertical" - Start with minimal (e.g., 3)
RowCount - Allow user to expand as needed
- Combine with for upper bounds
MaxLength
- 设置实现垂直扩展
ResizeMode="Resize.Vertical" - 从最小开始(如3)
RowCount - 允许用户按需扩展
- 结合设置上限
MaxLength
Key Props
关键属性
| Property | Default | Use When |
|---|---|---|
| Value | "" | Binding textarea content |
| RowCount | 2 | Setting visible number of rows |
| ColumnCount | 20 | Setting visible number of columns |
| MaxLength | null | Limiting maximum characters |
| ResizeMode | Resize.Both | Controlling user resize behavior |
| Placeholder | "" | Showing hint text when empty |
| FloatLabelType | FloatLabelType.Never | Enabling floating label animation |
| ShowClearButton | false | Adding quick clear functionality |
| ReadOnly | false | Preventing user edits while showing content |
| Disabled | false | Disabling the component entirely |
| Width | "100%" | Setting component width |
| CssClass | "" | Applying custom CSS classes |
| EnableRtl | false | Enabling right-to-left text direction |
| 属性 | 默认值 | 使用场景 |
|---|---|---|
| Value | "" | 绑定textarea内容 |
| RowCount | 2 | 设置可见行数 |
| ColumnCount | 20 | 设置可见列数 |
| MaxLength | null | 限制最大字符数 |
| ResizeMode | Resize.Both | 控制用户调整大小行为 |
| Placeholder | "" | 为空时显示提示文本 |
| FloatLabelType | FloatLabelType.Never | 启用浮动标签动画 |
| ShowClearButton | false | 添加快速清除功能 |
| ReadOnly | false | 阻止用户编辑但显示内容 |
| Disabled | false | 完全禁用组件 |
| Width | "100%" | 设置组件宽度 |
| CssClass | "" | 应用自定义CSS类 |
| EnableRtl | false | 启用从右到左文本方向 |
Common Use Cases
常见用例
- Comment Sections: User feedback, review comments, discussion threads
- Form Descriptions: Product descriptions, bio sections, about fields
- Message Composition: Email bodies, chat messages, note-taking
- Code/JSON Input: Configuration files, script input, data entry
- Address Fields: Multi-line address entry with street, city, etc.
- Search Queries: Complex search inputs with multiple criteria
- Customer Support: Ticket descriptions, issue reporting, help requests
- Content Management: Article drafts, blog post editing, documentation
- 评论区:用户反馈、评论、讨论线程
- 表单描述:产品描述、个人简介、关于字段
- 消息撰写:邮件正文、聊天消息、笔记
- 代码/JSON输入:配置文件、脚本输入、数据录入
- 地址字段:包含街道、城市等的多行地址输入
- 搜索查询:包含多个条件的复杂搜索输入
- 客户支持:工单描述、问题报告、帮助请求
- 内容管理:文章草稿、博客编辑、文档撰写
Quick Decision Tree
快速决策树
User needs multi-line text input
├─ Fixed size? → Set + specific
├─ User-resizable?
│ ├─ Vertical only? →
│ ├─ Horizontal only? →
│ └─ Both directions? →
├─ Character limit needed? → Set property
└─ Form validation?
├─ Use within
└─ Add for validation binding
ResizeMode="Resize.None"RowCountResizeMode="Resize.Vertical"ResizeMode="Resize.Horizontal"ResizeMode="Resize.Both"MaxLength<EditForm>ValueExpression用户需要多行文本输入
├─ 固定尺寸?→ 设置 + 特定
├─ 用户可调整大小?
│ ├─ 仅垂直?→
│ ├─ 仅水平?→
│ └─ 双向?→
├─ 需要字符限制?→ 设置属性
└─ 需要表单验证?
├─ 在中使用
└─ 添加用于验证绑定
ResizeMode="Resize.None"RowCountResizeMode="Resize.Vertical"ResizeMode="Resize.Horizontal"ResizeMode="Resize.Both"MaxLength<EditForm>ValueExpressionSignature
Signature
Learn to implement Syncfusion Blazor Signature component for capturing digital signatures with configurable stroke width, colors, background images, save/load functionality in multiple formats (PNG, JPEG, SVG), and comprehensive event handling. Perfect for e-signatures, document approval workflows, digital consent forms, and any scenario requiring handwritten signature capture with touch and mouse support.
学习实现Syncfusion Blazor Signature组件,用于捕获数字签名,支持可配置的笔触宽度、颜色、背景图片、多种格式(PNG、JPEG、SVG)的保存/加载功能和全面事件处理。适用于电子签名、文档审批流程、数字同意表单等需要手写签名捕获并支持触摸和鼠标输入的场景。
Documentation
文档
Getting Started
快速入门
📄 Read: references/signature-getting-started.md
- Installation and NuGet package setup
- Basic SfSignature component setup
- Namespace imports and service registration
- CSS theme configuration
- Canvas rendering and initialization
- Touch and mouse input support
- Minimal working example
📄 阅读: references/signature-getting-started.md
- 安装和NuGet包配置
- 基础SfSignature组件设置
- 命名空间导入和服务注册
- CSS主题配置
- Canvas渲染与初始化
- 触摸和鼠标输入支持
- 最简运行示例
Drawing Configuration
绘制配置
📄 Read: references/signature-drawing-configuration.md
- MinStrokeWidth and MaxStrokeWidth for pen thickness
- StrokeColor for ink color customization
- BackgroundColor for canvas background
- BackgroundImage for letterhead/watermark
- Velocity property for stroke smoothness
- Drawing behavior and responsiveness
- Pressure sensitivity simulation
📄 阅读: references/signature-drawing-configuration.md
- 笔触粗细的MinStrokeWidth和MaxStrokeWidth
- 墨迹颜色自定义的StrokeColor
- Canvas背景的BackgroundColor
- 信头/水印的BackgroundImage
- 笔触平滑度的Velocity属性
- 绘制行为与响应性
- 压力敏感度模拟
Save and Load Signatures
签名保存与加载
📄 Read: references/signature-save-load.md
- Save() method with format options (PNG, JPEG, SVG)
- SaveWithBackground property configuration
- GetSignature() for Base64 string retrieval
- Load() method for existing signatures
- Clear() method for signature removal
- File format selection and quality settings
- Server integration patterns
- Database storage strategies
📄 阅读: references/signature-save-load.md
- 带格式选项的Save()方法(PNG、JPEG、SVG)
- SaveWithBackground属性配置
- 获取Base64字符串的GetSignature()
- 加载现有签名的Load()方法
- 清除签名的Clear()方法
- 文件格式选择与质量设置
- 服务器集成模式
- 数据库存储策略
Event Handling
事件处理
📄 Read: references/signature-events.md
- Changed event for stroke tracking
- OnSave event for save operations
- Created event for initialization
- Event argument structure
- Real-time signature validation
- Detecting empty vs filled signatures
- Event-driven workflows
📄 阅读: references/signature-events.md
- 笔触跟踪的Changed事件
- 保存操作的OnSave事件
- 初始化的Created事件
- 事件参数结构
- 实时签名验证
- 检测空签名与已填充签名
- 事件驱动工作流
Customization and Styling
自定义与样式
📄 Read: references/signature-customization.md
- Disabled and IsReadOnly states
- HtmlAttributes for custom styling
- Canvas size customization
- Theme integration
- Mobile and touch device optimization
- Accessibility considerations
- Responsive design patterns
📄 阅读: references/signature-customization.md
- 禁用和只读状态
- 自定义样式的HtmlAttributes
- Canvas尺寸自定义
- 主题集成
- 移动和触摸设备优化
- 无障碍考虑
- 响应式设计模式
Quick Start Example
快速入门示例
razor
@using Syncfusion.Blazor.Inputs
<div class="signature-container">
<label>Sign below:</label>
<SfSignature @ref="signatureRef"
StrokeColor="#000000"
BackgroundColor="#FFFFFF"
MaxStrokeWidth="2.0"
MinStrokeWidth="0.5">
</SfSignature>
<div class="signature-actions">
<button @onclick="SaveSignature">Save</button>
<button @onclick="ClearSignature">Clear</button>
</div>
</div>
@code {
private SfSignature signatureRef;
private async Task SaveSignature()
{
await signatureRef.SaveAsync(SignatureFileType.Png, "signature.png");
}
private async Task ClearSignature()
{
await signatureRef.ClearAsync();
}
}razor
@using Syncfusion.Blazor.Inputs
<div class="signature-container">
<label>在此签名:</label>
<SfSignature @ref="signatureRef"
StrokeColor="#000000"
BackgroundColor="#FFFFFF"
MaxStrokeWidth="2.0"
MinStrokeWidth="0.5">
</SfSignature>
<div class="signature-actions">
<button @onclick="SaveSignature">保存</button>
<button @onclick="ClearSignature">清除</button>
</div>
</div>
@code {
private SfSignature signatureRef;
private async Task SaveSignature()
{
await signatureRef.SaveAsync(SignatureFileType.Png, "signature.png");
}
private async Task ClearSignature()
{
await signatureRef.ClearAsync();
}
}Common Patterns
常见模式
Pattern 1: Basic Signature Capture
模式1:基础签名捕获
- Use default stroke settings for natural handwriting feel
- Set for clear canvas
BackgroundColor="#FFFFFF" - Provide Clear button for user corrections
- Save as PNG for universal compatibility
- Validate signature is not empty before submission
- 使用默认笔触设置获得自然手写体验
- 设置实现清晰画布
BackgroundColor="#FFFFFF" - 提供清除按钮供用户修正
- 保存为PNG以获得通用兼容性
- 提交前验证签名非空
Pattern 2: Document Signing with Letterhead
模式2:带信头的文档签名
- Use for company letterhead or form template
BackgroundImage - Set to include background in saved file
SaveWithBackground="true" - Configure to contrast with background
StrokeColor - Save as PNG or JPEG with background embedded
- Ideal for contracts, agreements, official documents
- 使用添加公司信头或表单模板
BackgroundImage - 启用在保存文件中包含背景
SaveWithBackground="true" - 配置与背景形成对比
StrokeColor - 保存为带嵌入背景的PNG或JPEG
- 适用于合同、协议、官方文档
Pattern 3: Mobile-Optimized Signature
模式3:移动端优化签名
- Increase stroke width for better touch visibility
- Use larger canvas size for thumb-friendly drawing
- Set only when signature mode active
IsReadOnly="false" - Auto-save on signature completion
- Provide clear visual feedback for touch interactions
- 增加笔触宽度提升触摸可见性
- 使用更大的Canvas尺寸方便拇指绘制
- 仅在签名模式激活时设置
IsReadOnly="false" - 签名完成后自动保存
- 为触摸交互提供清晰视觉反馈
Pattern 4: Multi-Signature Forms
模式4:多签名表单
- Use multiple SfSignature components for different signatories
- Track completion state per signature field
- Save each signature with unique identifier
- Combine signatures in final document generation
- Validate all required signatures before form submission
- 使用多个SfSignature组件支持不同签署人
- 跟踪每个签名字段的完成状态
- 用唯一标识符保存每个签名
- 在最终文档生成中合并签名
- 提交前验证所有必填签名
Key Props
关键属性
| Property | Default | Use When |
|---|---|---|
| MinStrokeWidth | 0.5 | Setting minimum pen thickness |
| MaxStrokeWidth | 2.0 | Setting maximum pen thickness |
| StrokeColor | "#000000" | Changing ink color |
| BackgroundColor | "#FFFFFF" | Setting canvas background color |
| BackgroundImage | null | Adding letterhead or watermark image |
| Velocity | 0.7 | Controlling stroke smoothness (0-1) |
| SaveWithBackground | true | Including background in saved signature |
| Disabled | false | Disabling signature capture entirely |
| IsReadOnly | false | Preventing signature changes while showing existing |
| EnablePersistence | false | Maintaining signature across page reloads |
| HtmlAttributes | null | Adding custom HTML attributes to wrapper |
| 属性 | 默认值 | 使用场景 |
|---|---|---|
| MinStrokeWidth | 0.5 | 设置最小笔触粗细 |
| MaxStrokeWidth | 2.0 | 设置最大笔触粗细 |
| StrokeColor | "#000000" | 更改墨迹颜色 |
| BackgroundColor | "#FFFFFF" | 设置Canvas背景色 |
| BackgroundImage | null | 添加信头或水印图片 |
| Velocity | 0.7 | 控制笔触平滑度(0-1) |
| SaveWithBackground | true | 在保存的签名中包含背景 |
| Disabled | false | 完全禁用签名捕获 |
| IsReadOnly | false | 阻止签名更改但显示现有签名 |
| EnablePersistence | false | 跨页面重载保持签名 |
| HtmlAttributes | null | 为包装器添加自定义HTML属性 |
Common Use Cases
常见用例
- E-Signature Capture: Digital document signing, contract approval, consent forms
- Financial Services: Loan applications, account opening, transaction authorization
- Healthcare: Patient consent forms, HIPAA agreements, medical records
- Legal Documents: Contracts, NDAs, legal agreements, court documents
- HR Processes: Employment contracts, onboarding documents, policy acknowledgments
- Delivery Confirmation: Package delivery signatures, service completion
- Check-In Systems: Visitor logs, attendance tracking, registration forms
- Educational: Test proctoring, form submissions, parent consent
- 电子签名捕获:数字文档签署、合同审批、同意表单
- 金融服务:贷款申请、账户开立、交易授权
- 医疗保健:患者同意表单、HIPAA协议、医疗记录
- 法律文档:合同、保密协议、法律协议、法院文档
- HR流程:雇佣合同、入职文档、政策确认
- 交付确认:包裹交付签名、服务完成确认
- 签到系统:访客日志、考勤跟踪、注册表单
- 教育领域:考试监考、表单提交、家长同意
Quick Decision Tree
快速决策树
User needs signature capture
├─ Basic signature?
│ └─ Use default settings + Save as PNG
├─ Document with letterhead?
│ ├─ Set property
│ └─ Enable
├─ Mobile/touch primary?
│ ├─ Increase to 3.0+
│ └─ Use larger canvas dimensions
├─ Multiple signers?
│ ├─ Use multiple SfSignature components
│ ├─ Track each signature state separately
│ └─ Save with unique identifiers
└─ Need specific format?
├─ PNG → Universal support, transparency
├─ JPEG → Smaller file size, no transparency
└─ SVG → Vector format, scalable
BackgroundImageSaveWithBackground="true"MaxStrokeWidth用户需要签名捕获
├─ 基础签名?
│ └─ 使用默认设置 + 保存为PNG
├─ 带信头的文档?
│ ├─ 设置属性
│ └─ 启用
├─ 以移动/触摸为主?
│ ├─ 将增加到3.0+
│ └─ 使用更大的Canvas尺寸
├─ 多个签署人?
│ ├─ 使用多个SfSignature组件
│ ├─ 分别跟踪每个签名状态
│ └─ 用唯一标识符保存
└─ 需要特定格式?
├─ PNG → 通用支持、透明
├─ JPEG → 文件更小、无透明
└─ SVG → 矢量格式、可缩放
BackgroundImageSaveWithBackground="true"MaxStrokeWidthRangeSlider
RangeSlider
Learn to implement Syncfusion Blazor Range Slider component with dual handles for range selection, ticks, tooltips, color ranges, movement limits, and always get immediate two-value selection for price filters, date ranges, temperature zones, or any scenario requiring range input with visual feedback and validation in Blazor applications.
学习实现Syncfusion Blazor Range Slider组件,支持双手柄范围选择、刻度、工具提示、颜色范围、移动限制,在Blazor应用中为价格筛选、日期范围、温度区间等场景提供即时双值选择和视觉反馈与验证。
Documentation
文档
Getting Started
快速入门
📄 Read: references/rangeslider-getting-started.md
- Installation and NuGet package setup
- Basic SfSlider with Type="SliderType.Range"
- Value binding with arrays for dual handles
- CSS imports and theme configuration
- Namespace imports and service registration
- Minimal working example with range selection
📄 阅读: references/rangeslider-getting-started.md
- 安装和NuGet包配置
- 设置Type="SliderType.Range"的基础SfSlider
- 用数组绑定双手柄的值
- CSS导入和主题配置
- 命名空间导入和服务注册
- 带范围选择的最简运行示例
Range Configuration
范围配置
📄 Read: references/rangeslider-range-configuration.md
- Min, Max, and Step properties for range bounds
- Type property (SliderType.Range vs Default)
- Two-way value binding with arrays (@bind-Value)
- Custom non-numeric values with CustomValues
- IsImmediateValue for real-time updates
- Value array structure and data types
📄 阅读: references/rangeslider-range-configuration.md
- 范围边界的Min、Max和Step属性
- Type属性(SliderType.Range vs Default)
- 用数组实现双向值绑定(@bind-Value)
- 自定义非数值的CustomValues
- 实时更新的IsImmediateValue
- 值数组结构与数据类型
Ticks and Tooltip
刻度与工具提示
📄 Read: references/rangeslider-ticks-and-tooltip.md
- SliderTicks component configuration
- LargeStep and SmallStep for interval markers
- Tick placement options (Before, After, Both)
- ShowSmallTicks property for granular display
- Format property for tick label customization
- SliderTooltip component setup
- Tooltip visibility modes (Focus, Hover, Always, Auto)
- Tooltip placement and format customization
- Custom tooltip templates
📄 阅读: references/rangeslider-ticks-and-tooltip.md
- SliderTicks组件配置
- 间隔标记的LargeStep和SmallStep
- 刻度位置选项(Before、After、Both)
- 精细显示的ShowSmallTicks属性
- 刻度标签自定义的Format属性
- SliderTooltip组件设置
- 工具提示可见性模式(Focus、Hover、Always、Auto)
- 工具提示位置与格式自定义
- 自定义工具提示模板
Color Ranges and Visual Indication
颜色范围与视觉指示
📄 Read: references/rangeslider-color-ranges-visual.md
- SliderColorRanges for visual feedback
- ColorRange components with Start, End, Color
- Multiple color segments for different value zones
- Use cases (temperature zones, price tiers, ratings)
- Color customization and styling
- Accessibility considerations for color choices
📄 阅读: references/rangeslider-color-ranges-visual.md
- 提供视觉反馈的SliderColorRanges
- 带Start、End、Color的ColorRange组件
- 不同值区间的多颜色分段
- 用例(温度区间、价格层级、评分)
- 颜色自定义与样式
- 颜色选择的无障碍考虑
Limits and Constraints
限制与约束
📄 Read: references/rangeslider-limits-and-constraints.md
- SliderLimits configuration for movement restrictions
- MinStart, MinEnd, MaxStart, MaxEnd properties
- Enabled property for limit activation
- StartHandleFixed and EndHandleFixed for locked handles
- Restricting handle movement within bounds
- Use cases (booking date ranges, budget constraints)
- Validation patterns with limits
📄 阅读: references/rangeslider-limits-and-constraints.md
- 限制移动的SliderLimits配置
- MinStart、MinEnd、MaxStart、MaxEnd属性
- 激活限制的Enabled属性
- 锁定手柄的StartHandleFixed和EndHandleFixed
- 限制手柄在边界内移动
- 用例(预订日期范围、预算约束)
- 带限制的验证模式
Orientation and Customization
方向与自定义
📄 Read: references/rangeslider-orientation-and-customization.md
- Orientation property (Horizontal vs Vertical)
- ShowButtons for increment/decrement controls
- Width property for responsive sizing
- EnableAnimation for smooth transitions
- CssClass for custom styling
- EnableRtl for right-to-left language support
- ReadOnly and Enabled states
- Theme customization with Theme Studio
📄 阅读: references/rangeslider-orientation-and-customization.md
- Orientation属性(Horizontal vs Vertical)
- 增减控件的ShowButtons
- 响应式尺寸的Width属性
- 平滑过渡的EnableAnimation
- 自定义样式的CssClass
- 从右到左语言支持的EnableRtl
- 只读和启用状态
- 与Theme Studio的主题自定义
Events and Data Binding
事件与数据绑定
📄 Read: references/rangeslider-events-and-binding.md
- SliderEvents component configuration
- ValueChange event callback for range updates
- OnChange vs Changed event timing
- Created event for initialization logic
- Rendered event for post-render operations
- OnTooltipChange for dynamic tooltip content
- OnTicksRender for custom tick label rendering
- Form integration with EditForm
- Validation with EditContext and data annotations
📄 阅读: references/rangeslider-events-and-binding.md
- SliderEvents组件配置
- 范围更新的ValueChange事件回调
- OnChange与Changed事件时序
- 初始化逻辑的Created事件
- 渲染后操作的Rendered事件
- 动态工具提示内容的OnTooltipChange
- 自定义刻度标签渲染的OnTicksRender
- 与EditForm的表单集成
- 用EditContext和数据注解验证
Quick Start Example
快速入门示例
razor
@using Syncfusion.Blazor.Inputs
<div class="range-slider-container">
<label>Select Price Range: $@priceRange[0] - $@priceRange[1]</label>
<SfSlider @bind-Value="@priceRange"
Type="SliderType.Range"
Min="0"
Max="1000"
Step="10">
<SliderTicks Placement="Placement.After" LargeStep="200" SmallStep="50" ShowSmallTicks="true"></SliderTicks>
<SliderTooltip IsVisible="true" ShowOn="TooltipShowOn.Always" Format="C0"></SliderTooltip>
</SfSlider>
</div>
@code {
private int[] priceRange = new int[] { 200, 800 };
}razor
@using Syncfusion.Blazor.Inputs
<div class="range-slider-container">
<label>选择价格范围:$@priceRange[0] - $@priceRange[1]</label>
<SfSlider @bind-Value="@priceRange"
Type="SliderType.Range"
Min="0"
Max="1000"
Step="10">
<SliderTicks Placement="Placement.After" LargeStep="200" SmallStep="50" ShowSmallTicks="true"></SliderTicks>
<SliderTooltip IsVisible="true" ShowOn="TooltipShowOn.Always" Format="C0"></SliderTooltip>
</SfSlider>
</div>
@code {
private int[] priceRange = new int[] { 200, 800 };
}Common Patterns
常见模式
Pattern 1: Basic Range Selection
模式1:基础范围选择
- Set for dual handles
Type="SliderType.Range" - Bind value to int[] or double[] array with two elements
- Configure ,
Min, andMaxpropertiesStep - Enable tooltip with for user feedback
IsVisible="true" - Use event to capture range updates
ValueChange
- 设置启用双手柄
Type="SliderType.Range" - 将值绑定到包含两个元素的int[]或double[]数组
- 配置、
Min和Max属性Step - 启用的工具提示提供用户反馈
IsVisible="true" - 使用事件捕获范围更新
ValueChange
Pattern 2: Range with Visual Color Zones
模式2:带视觉颜色区间的范围
- Add component
SliderColorRanges - Define multiple segments (e.g., cold/warm/hot)
ColorRange - Set colors that provide clear visual distinction
- Use for temperature, ratings, or risk indicators
- Combine with ticks for precise value identification
- 添加组件
SliderColorRanges - 定义多个分段(如冷/暖/热)
ColorRange - 设置提供清晰视觉区分的颜色
- 用于温度、评分或风险指标
- 结合刻度实现精确值识别
Pattern 3: Constrained Range Selection
模式3:受限范围选择
- Use to restrict handle movement
SliderLimits - Set /
MinStartfor first handle boundsMaxStart - Set /
MinEndfor second handle boundsMaxEnd - Enable or
StartHandleFixedif one handle should be lockedEndHandleFixed - Ideal for booking systems, budget planning, scheduling
- 使用限制手柄移动
SliderLimits - 为第一个手柄设置/
MinStart边界MaxStart - 为第二个手柄设置/
MinEnd边界MaxEnd - 若需锁定一个手柄,启用或
StartHandleFixedEndHandleFixed - 适用于预订系统、预算规划、日程安排
Pattern 4: Custom Value Range Selection
模式4:自定义值范围选择
- Use array for non-numeric ranges
CustomValues - Example: string[] { "XS", "S", "M", "L", "XL", "XXL" }
- Value array uses indices, not actual values
- Display custom labels via tick formatting
- Perfect for size selection, priority levels, skill ratings
- 使用数组实现非数值范围
CustomValues - 示例:string[] { "XS", "S", "M", "L", "XL", "XXL" }
- 值数组使用索引而非实际值
- 通过刻度格式化显示自定义标签
- 适用于尺寸选择、优先级、技能评分
Key Props
关键属性
| Property | Default | Use When |
|---|---|---|
| Type | SliderType.Default | Set to SliderType.Range for dual handles |
| Value | new int[]{} | Binding range values (must be 2-element array) |
| Min | 0 | Setting minimum selectable value |
| Max | 100 | Setting maximum selectable value |
| Step | 1 | Defining increment/decrement value |
| CustomValues | null | Using non-numeric values (sizes, labels) |
| IsImmediateValue | false | Getting real-time updates during drag |
| ShowButtons | false | Adding increment/decrement buttons |
| Orientation | SliderOrientation.Horizontal | Changing to vertical layout |
| Width | null | Setting component width |
| EnableAnimation | true | Controlling handle animation |
| ReadOnly | false | Preventing user interaction while showing value |
| Enabled | true | Enabling/disabling the entire component |
| 属性 | 默认值 | 使用场景 |
|---|---|---|
| Type | SliderType.Default | 设置为SliderType.Range启用双手柄 |
| Value | new int[]{} | 绑定范围值(必须是2元素数组) |
| Min | 0 | 设置最小可选值 |
| Max | 100 | 设置最大可选值 |
| Step | 1 | 定义增减值 |
| CustomValues | null | 使用非数值(尺寸、标签) |
| IsImmediateValue | false | 拖拽期间实时更新 |
| ShowButtons | false | 添加增减按钮 |
| Orientation | SliderOrientation.Horizontal | 更改为垂直布局 |
| Width | null | 设置组件宽度 |
| EnableAnimation | true | 控制手柄动画 |
| ReadOnly | false | 阻止用户交互但显示值 |
| Enabled | true | 启用/禁用整个组件 |
Common Use Cases
常见用例
- E-Commerce Price Filters: Min/max price selection, budget range filtering
- Date Range Pickers: Check-in/check-out dates, event duration, scheduling
- Temperature Control: HVAC systems, oven settings, climate zones
- Age Range Selection: Demographics, target audience, age restrictions
- Time Range Selection: Working hours, availability slots, time windows
- Score/Rating Ranges: Grade filtering, performance metrics, review scores
- Financial Planning: Budget allocation, investment ranges, spending limits
- Resource Allocation: CPU/memory limits, bandwidth throttling, capacity planning
- 电商价格筛选:最小/最大价格选择、预算范围筛选
- 日期范围选择器:入住/退房日期、活动时长、日程安排
- 温度控制:HVAC系统、烤箱设置、气候区间
- 年龄范围选择:人口统计、目标受众、年龄限制
- 时间范围选择:工作时间、可用时段、时间窗口
- 分数/评分范围:成绩筛选、绩效指标、评论分数
- 财务规划:预算分配、投资范围、支出限制
- 资源分配:CPU/内存限制、带宽节流、容量规划
Quick Decision Tree
快速决策树
User needs range selection (two values)
├─ Numeric range?
│ ├─ Set
│ ├─ Use int[] or double[] for Value
│ └─ Configure Min, Max, Step
├─ Non-numeric values (sizes, labels)?
│ ├─ Set array
│ ├─ Value array contains indices
│ └─ Use tick formatting for labels
├─ Need visual zones?
│ ├─ Add component
│ └─ Define multiple segments
├─ Restrict movement?
│ ├─ Use component
│ ├─ Set MinStart/MaxStart/MinEnd/MaxEnd
│ └─ Enable StartHandleFixed or EndHandleFixed if needed
├─ Vertical layout needed?
│ └─ Set
└─ Real-time updates during drag?
└─ Set
Type="SliderType.Range"CustomValuesSliderColorRangesColorRangeSliderLimitsOrientation="SliderOrientation.Vertical"IsImmediateValue="true"用户需要范围选择(双值)
├─ 数值范围?
│ ├─ 设置
│ ├─ 使用int[]或double[]作为Value
│ └─ 配置Min、Max、Step
├─ 非数值(尺寸、标签)?
│ ├─ 设置数组
│ ├─ 值数组包含索引
│ └─ 使用刻度格式化显示标签
├─ 需要视觉区间?
│ ├─ 添加组件
│ └─ 定义多个分段
├─ 限制移动?
│ ├─ 使用组件
│ ├─ 设置MinStart/MaxStart/MinEnd/MaxEnd
│ └─ 必要时启用StartHandleFixed或EndHandleFixed
├─ 需要垂直布局?
│ └─ 设置
└─ 拖拽期间实时更新?
└─ 设置
Type="SliderType.Range"CustomValuesSliderColorRangesColorRangeSliderLimitsOrientation="SliderOrientation.Vertical"IsImmediateValue="true"OtpInput
OtpInput
Learn to implement Syncfusion Blazor OtpInput (One-Time Password) component for secure verification code entry with configurable length, input types (number, text, password), styling modes (outlined, underlined, filled), automatic focus management, and comprehensive event handling. Perfect for 2FA authentication, email verification, SMS codes, PIN entry, and any scenario requiring secure multi-digit code input with keyboard navigation and accessibility support.
学习实现Syncfusion Blazor OtpInput(一次性密码)组件,用于安全验证码输入,支持可配置长度、输入类型(数字、文本、密码)、样式模式(轮廓、下划线、填充)、自动焦点管理和全面事件处理。适用于双因素认证、邮箱验证、短信验证码、PIN码输入等需要安全多位数输入并支持键盘导航和无障碍的场景。
Documentation
文档
Getting Started
快速入门
📄 Read: references/otpinput-getting-started.md
- Installation and NuGet package setup
- Basic SfOtpInput component setup
- Namespace imports and service registration
- CSS theme configuration
- Length property for OTP digit count
- Value binding and retrieval
- Minimal working example
📄 阅读: references/otpinput-getting-started.md
- 安装和NuGet包配置
- 基础SfOtpInput组件设置
- 命名空间导入和服务注册
- CSS主题配置
- OTP位数的Length属性
- 值绑定与获取
- 最简运行示例
Configuration Options
配置选项
📄 Read: references/otpinput-configuration.md
- Length property for digit count (default: 4)
- Type property (Number, Text, Password)
- Placeholder configuration for empty inputs
- Separator for visual grouping
- AutoFocus for immediate input
- Disabled state management
- ID and HtmlAttributes customization
📄 阅读: references/otpinput-configuration.md
- 位数的Length属性(默认:4)
- Type属性(Number、Text、Password)
- 空输入的占位符配置
- 视觉分组的分隔符
- 即时输入的AutoFocus
- 禁用状态管理
- ID和HtmlAttributes自定义
Styling Modes
样式模式
📄 Read: references/otpinput-styling-modes.md
- StylingMode options (Outlined, Underlined, Filled)
- TextTransform (None, Lowercase, Uppercase)
- CssClass for custom styling
- Theme customization with Theme Studio
- Responsive design patterns
- Visual states and focus indicators
📄 阅读: references/otpinput-styling-modes.md
- StylingMode选项(Outlined、Underlined、Filled)
- TextTransform(None、Lowercase、Uppercase)
- 自定义样式的CssClass
- 与Theme Studio的主题自定义
- 响应式设计模式
- 视觉状态与焦点指示器
Events and Data Binding
事件与数据绑定
📄 Read: references/otpinput-events-binding.md
- Value property and two-way binding (@bind-Value)
- ValueChanged event callback (use Value property only, NOT @bind-Value)
- OnInput event with OtpInputEventArgs
- OnFocus and OnBlur events
- Created lifecycle event
- Form validation integration
- Real-time verification patterns
- Auto-submit on completion
📄 阅读: references/otpinput-events-binding.md
- Value属性与双向绑定(@bind-Value)
- ValueChanged事件回调(仅使用Value属性,请勿使用@bind-Value)
- 带OtpInputEventArgs的OnInput事件
- OnFocus和OnBlur事件
- Created生命周期事件
- 表单验证集成
- 实时验证模式
- 完成后自动提交
Accessibility
无障碍
📄 Read: references/otpinput-accessibility.md
- AriaLabels array for individual input fields
- Keyboard navigation (arrows, backspace, delete)
- Screen reader support
- WCAG 2.1 compliance
- Focus management best practices
- Password type accessibility considerations
- Mobile device optimization
📄 阅读: references/otpinput-accessibility.md
- 单个输入字段的AriaLabels数组
- 键盘导航(箭头、退格、删除)
- 屏幕阅读器支持
- WCAG 2.1合规性
- 焦点管理最佳实践
- 密码类型的无障碍考虑
- 移动设备优化
Quick Start Example
快速入门示例
razor
@using Syncfusion.Blazor.Inputs
<div class="otp-container">
<label>Enter verification code:</label>
<SfOtpInput @bind-Value="@otpValue"
Length="6"
Type="OtpInputType.Number"
StylingMode="OtpInputStyle.Outlined">
</SfOtpInput>
@if (!string.IsNullOrEmpty(message))
{
<div class="message">@message</div>
}
</div>
@code {
private string otpValue = "";
private string message = "";
protected override void OnParametersSet()
{
if (otpValue.Length == 6)
{
message = "Verifying code...";
// Call verification API
}
}
}razor
@using Syncfusion.Blazor.Inputs
<div class="otp-container">
<label>输入验证码:</label>
<SfOtpInput @bind-Value="@otpValue"
Length="6"
Type="OtpInputType.Number"
StylingMode="OtpInputStyle.Outlined">
</SfOtpInput>
@if (!string.IsNullOrEmpty(message))
{
<div class="message">@message</div>
}
</div>
@code {
private string otpValue = "";
private string message = "";
protected override void OnParametersSet()
{
if (otpValue.Length == 6)
{
message = "正在验证验证码...";
// 调用验证API
}
}
}Common Patterns
常见模式
Pattern 1: Basic OTP Verification (6-digit numeric)
模式1:基础OTP验证(6位数字)
- Set for standard OTP length
Length="6" - Use for numeric-only input
Type="OtpInputType.Number" - Enable for immediate input
AutoFocus="true" - Use for two-way binding (simplest approach)
@bind-Value - Validate and verify OTP on server
- 设置为标准OTP长度
Length="6" - 使用仅允许数字输入
Type="OtpInputType.Number" - 启用实现即时输入
AutoFocus="true" - 使用实现双向绑定(最简方式)
@bind-Value - 在服务器端验证OTP
Pattern 2: Email/SMS Verification Code
模式2:邮箱/SMS验证码
- Configure or
Length="4"based on serviceLength="6" - Use for numeric codes
Type="OtpInputType.Number" - Set for clean look
StylingMode="OtpInputStyle.Underlined" - Auto-focus first input on page load
- Show countdown timer for code expiration
- Provide "Resend code" functionality
- 根据服务配置或
Length="4"Length="6" - 使用处理数字验证码
Type="OtpInputType.Number" - 设置获得简洁外观
StylingMode="OtpInputStyle.Underlined" - 页面加载时自动聚焦第一个输入框
- 显示验证码过期倒计时
- 提供“重新发送验证码”功能
Pattern 3: Secure PIN Entry
模式3:安全PIN码输入
- Use to mask input
Type="OtpInputType.Password" - Set or
Length="4"for PIN lengthLength="6" - Apply for modern look
StylingMode="OtpInputStyle.Filled" - Implement rate limiting for security
- Clear input on failed attempts
- Show visual feedback for validation
- 使用屏蔽输入
Type="OtpInputType.Password" - 设置或
Length="4"作为PIN码长度Length="6" - 应用获得现代外观
StylingMode="OtpInputStyle.Filled" - 实现速率限制提升安全性
- 验证失败时清除输入
- 提供验证视觉反馈
Pattern 4: Alphanumeric Verification (with separators)
模式4:字母数字验证码(带分隔符)
- Set for letters and numbers
Type="OtpInputType.Text" - Use for readability
TextTransform="TextTransform.Uppercase" - Configure to visually group digits
Separator="-" - Example: ABC-123-XYZ pattern
- Set (including separator positions)
Length="9" - Useful for activation codes, license keys
- 设置允许字母和数字
Type="OtpInputType.Text" - 使用提升可读性
TextTransform="TextTransform.Uppercase" - 配置实现视觉分组
Separator="-" - 示例:ABC-123-XYZ模式
- 设置(包含分隔符位置)
Length="9" - 适用于激活码、许可证密钥
Key Props
关键属性
| Property | Default | Use When |
|---|---|---|
| Value | "" | Binding OTP value (two-way with @bind-Value) |
| Length | 4 | Setting number of OTP input fields |
| Type | OtpInputType.Number | Defining input type (Number, Text, Password) |
| StylingMode | OtpInputStyle.Outlined | Choosing visual style (Outlined, Underlined, Filled) |
| Placeholder | "" | Showing hint text in empty fields |
| Separator | "" | Adding visual separator between groups |
| TextTransform | TextTransform.None | Transforming text (None, Lowercase, Uppercase) |
| AutoFocus | false | Auto-focusing first input on load |
| Disabled | false | Disabling all input fields |
| CssClass | "" | Applying custom CSS classes |
| AriaLabels | null | Setting custom ARIA labels for each input |
| HtmlAttributes | null | Adding custom HTML attributes |
| 属性 | 默认值 | 使用场景 |
|---|---|---|
| Value | "" | 绑定OTP值(用@bind-Value实现双向绑定) |
| Length | 4 | 设置OTP输入字段数量 |
| Type | OtpInputType.Number | 定义输入类型(Number、Text、Password) |
| StylingMode | OtpInputStyle.Outlined | 选择视觉样式(Outlined、Underlined、Filled) |
| Placeholder | "" | 为空字段显示提示文本 |
| Separator | "" | 在分组间添加视觉分隔符 |
| TextTransform | TextTransform.None | 转换文本(None、Lowercase、Uppercase) |
| AutoFocus | false | 加载时自动聚焦第一个输入框 |
| Disabled | false | 禁用所有输入字段 |
| CssClass | "" | 应用自定义CSS类 |
| AriaLabels | null | 为每个输入框设置自定义ARIA标签 |
| HtmlAttributes | null | 添加自定义HTML属性 |
Common Use Cases
常见用例
- Two-Factor Authentication (2FA): Login security, account verification, multi-factor authentication
- Email Verification: Account activation, email confirmation, newsletter signup
- SMS Verification: Phone number verification, mobile app login, transaction confirmation
- Password Reset: Secure password recovery, account access restoration
- Transaction Verification: Banking transactions, payment confirmation, fund transfers
- Access Control: Building entry codes, secure area access, temporary access codes
- Device Pairing: Bluetooth pairing codes, smart device setup, IoT device linking
- Activation Codes: Software licenses, product activation, subscription validation
- 双因素认证(2FA):登录安全、账户验证、多因素认证
- 邮箱验证:账户激活、邮箱确认、新闻订阅
- SMS验证:手机号验证、移动应用登录、交易确认
- 密码重置:安全密码恢复、账户访问恢复
- 交易验证:银行交易、支付确认、资金转账
- 访问控制:楼宇门禁码、安全区域访问、临时访问码
- 设备配对:蓝牙配对码、智能设备设置、IoT设备连接
- 激活码:软件许可证、产品激活、订阅验证
Quick Decision Tree
快速决策树
User needs OTP/verification code input
├─ Numeric only?
│ ├─ Set
│ └─ Use or
├─ Need to hide input (PIN)?
│ ├─ Set
│ └─ Apply security best practices
├─ Alphanumeric codes?
│ ├─ Set
│ ├─ Use
│ └─ Consider for readability
├─ Auto-submit when complete?
│ ├─ Listen to event
│ ├─ Check if
│ └─ Call verification API automatically
├─ Custom styling needed?
│ ├─ Outlined → (default)
│ ├─ Underlined →
│ └─ Filled →
└─ Accessibility important?
├─ Set array for screen readers
└─ Enable for keyboard users
Type="OtpInputType.Number"Length="4"Length="6"Type="OtpInputType.Password"Type="OtpInputType.Text"TextTransform="TextTransform.Uppercase"SeparatorValueChangedvalue.Length == LengthStylingMode="OtpInputStyle.Outlined"StylingMode="OtpInputStyle.Underlined"StylingMode="OtpInputStyle.Filled"AriaLabelsAutoFocus用户需要OTP/验证码输入
├─ 仅数字?
│ ├─ 设置
│ └─ 使用或
├─ 需要隐藏输入(PIN码)?
│ ├─ 设置
│ └─ 应用安全最佳实践
├─ 字母数字验证码?
│ ├─ 设置
│ ├─ 使用
│ └─ 考虑使用提升可读性
├─ 完成后自动提交?
│ ├─ 监听事件
│ ├─ 检查
│ └─ 自动调用验证API
├─ 需要自定义样式?
│ ├─ 轮廓→ (默认)
│ ├─ 下划线→
│ └─ 填充→
└─ 无障碍重要?
├─ 设置数组供屏幕阅读器使用
└─ 启用方便键盘用户
Type="OtpInputType.Number"Length="4"Length="6"Type="OtpInputType.Password"Type="OtpInputType.Text"TextTransform="TextTransform.Uppercase"SeparatorValueChangedvalue.Length == LengthStylingMode="OtpInputStyle.Outlined"StylingMode="OtpInputStyle.Underlined"StylingMode="OtpInputStyle.Filled"AriaLabelsAutoFocusRating
Rating
Learn to implement Syncfusion Blazor Rating component for intuitive rating and feedback collection with configurable precision modes (full, half, quarter, exact), custom icons and templates, label and tooltip support, comprehensive event handling, and accessibility features. Perfect for product reviews, skill assessments, satisfaction surveys, quality ratings, and any scenario requiring user feedback through star ratings or custom iconography with keyboard navigation and form integration.
学习实现Syncfusion Blazor Rating组件,用于直观的评分和反馈收集,支持可配置的精度模式(完整、半值、四分之一、精确)、自定义图标和模板、标签和工具提示支持、全面事件处理和无障碍特性。适用于产品评论、技能评估、满意度调查、质量评分等需要通过星级评分或自定义图标收集用户反馈并支持键盘导航和表单集成的场景。
Documentation
文档
Getting Started
快速入门
📄 Read: references/rating-getting-started.md
- Installation and NuGet package setup
- Basic SfRating component setup
- Namespace imports and service registration
- CSS theme configuration
- ItemsCount property for rating scale
- Value binding and retrieval
- Minimal working example
- Basic 5-star rating implementation
📄 阅读: references/rating-getting-started.md
- 安装和NuGet包配置
- 基础SfRating组件设置
- 命名空间导入和服务注册
- CSS主题配置
- 评分刻度的ItemsCount属性
- 值绑定与获取
- 最简运行示例
- 基础五星评分实现
Precision and Values
精度与值
📄 Read: references/rating-precision-and-values.md
- Precision property (Full, Half, Quarter, Exact)
- Full precision for whole numbers only
- Half precision for 0.5 increments
- Quarter precision for 0.25 increments
- Exact precision for decimal values
- Min property for minimum rating value
- AllowReset for clearing ratings
- EnableSingleSelection for single-item mode
- Value calculations and display
📄 阅读: references/rating-precision-and-values.md
- Precision属性(Full、Half、Quarter、Exact)
- Full精度仅允许整数
- Half精度允许0.5增量
- Quarter精度允许0.25增量
- Exact精度允许十进制值
- 最小评分值的Min属性
- 清除评分的AllowReset
- 单项选择模式的EnableSingleSelection
- 值计算与显示
Labels and Tooltips
标签与工具提示
📄 Read: references/rating-labels-and-tooltips.md
- ShowLabel property for label display
- LabelPosition (Top, Bottom, Left, Right)
- LabelTemplate for custom label formatting
- ShowTooltip property for hover tooltips
- TooltipTemplate for custom tooltip content
- Dynamic label updates based on value
- Contextual feedback patterns
📄 阅读: references/rating-labels-and-tooltips.md
- 显示标签的ShowLabel属性
- LabelPosition(Top、Bottom、Left、Right)
- 自定义标签格式化的LabelTemplate
- 悬停工具提示的ShowTooltip属性
- 自定义工具提示内容的TooltipTemplate
- 基于值的动态标签更新
- 上下文反馈模式
Templates and Customization
模板与自定义
📄 Read: references/rating-templates-customization.md
- EmptyTemplate for unselected items
- FullTemplate for selected items
- RatingItemContext for template data
- Custom icon implementation (hearts, thumbs, emojis)
- SVG and icon font integration
- CssClass for custom styling
- EnableAnimation property
- Theme customization and responsive design
📄 阅读: references/rating-templates-customization.md
- 未选中项的EmptyTemplate
- 已选中项的FullTemplate
- 模板数据的RatingItemContext
- 自定义图标实现(心形、拇指、表情)
- SVG和图标字体集成
- 自定义样式的CssClass
- EnableAnimation属性
- 主题自定义与响应式设计
Events and States
事件与状态
📄 Read: references/rating-events-and-states.md
- ValueChanged event for rating updates
- OnItemHover event with RatingHoverEventArgs
- Created lifecycle event
- Form validation integration
- ReadOnly state for display-only ratings
- Disabled state management
- Visible property control
- Keyboard navigation support
- Accessibility features and ARIA attributes
📄 阅读: references/rating-events-and-states.md
- 评分更新的ValueChanged事件
- 带RatingHoverEventArgs的OnItemHover事件
- Created生命周期事件
- 表单验证集成
- 仅显示评分的ReadOnly状态
- 禁用状态管理
- 组件可见性的Visible属性
- 键盘导航支持
- 无障碍特性与ARIA属性
Quick Start Example
快速入门示例
razor
@using Syncfusion.Blazor.Inputs
<div class="rating-container">
<label>Rate your experience:</label>
<SfRating @bind-Value="@userRating"
ItemsCount="5"
Precision="PrecisionType.Full"
ShowLabel="true">
</SfRating>
@if (userRating > 0)
{
<p>You rated: @userRating / 5 stars</p>
}
</div>
@code {
private double userRating = 0;
}razor
@using Syncfusion.Blazor.Inputs
<div class="rating-container">
<label>评价您的体验:</label>
<SfRating @bind-Value="@userRating"
ItemsCount="5"
Precision="PrecisionType.Full"
ShowLabel="true">
</SfRating>
@if (userRating > 0)
{
<p>您的评分:@userRating / 5星</p>
}
</div>
@code {
private double userRating = 0;
}Common Patterns
常见模式
Pattern 1: Basic 5-Star Product Rating
模式1:基础五星产品评分
- Use default for standard rating
ItemsCount="5" - Set for whole stars only
Precision="PrecisionType.Full" - Enable for two-way data binding
@bind-Value - Show to display rating value
ShowLabel="true" - Position label with
LabelPosition="LabelPosition.Right" - Use event for auto-submit
ValueChanged
- 使用默认作为标准评分
ItemsCount="5" - 设置仅允许整星
Precision="PrecisionType.Full" - 启用实现双向数据绑定
@bind-Value - 启用显示评分值
ShowLabel="true" - 用设置标签位置
LabelPosition="LabelPosition.Right" - 使用事件实现自动提交
ValueChanged
Pattern 2: Half-Star Rating with Hover Feedback
模式2:半星评分与悬停反馈
- Set for 0.5 increments
Precision="PrecisionType.Half" - Enable for hover feedback
ShowTooltip="true" - Use event for preview
OnItemHover - Display average ratings with
ReadOnly="true" - Show rating count in custom label template
- Implement real-time feedback messages
- 设置允许0.5增量
Precision="PrecisionType.Half" - 启用提供悬停反馈
ShowTooltip="true" - 使用事件实现预览
OnItemHover - 用显示平均评分
ReadOnly="true" - 在自定义标签模板中显示评分数量
- 实现实时反馈消息
Pattern 3: Custom Icon Templates (Hearts, Thumbs, Emojis)
模式3:自定义图标模板(心形、拇指、表情)
- Define for unselected state
EmptyTemplate - Define for selected state
FullTemplate - Use for item-specific rendering
RatingItemContext - Implement custom icons (♥, 👍, 😊, etc.)
- Apply for custom colors and sizing
CssClass - Enable for smooth transitions
EnableAnimation="true"
- 定义未选中状态的
EmptyTemplate - 定义已选中状态的
FullTemplate - 使用实现项特定渲染
RatingItemContext - 实现自定义图标(♥、👍、😊等)
- 应用自定义颜色和尺寸
CssClass - 启用实现平滑过渡
EnableAnimation="true"
Pattern 4: Multi-Category Rating Form
模式4:多类别评分表单
- Create multiple components
SfRating - Different per category if needed
ItemsCount - Combine with for validation
EditForm - Calculate overall rating average
- Track completion with event handlers
- Enable submit only when all ratings complete
- 创建多个组件
SfRating - 按需为不同类别设置不同
ItemsCount - 与结合实现验证
EditForm - 计算整体平均评分
- 通过事件处理器跟踪完成状态
- 所有评分完成后才启用提交
Key Props
关键属性
| Property | Default | Use When |
|---|---|---|
| Value | 0 | Binding rating value (two-way with @bind-Value) |
| ItemsCount | 5 | Setting number of rating items (stars) |
| Precision | PrecisionType.Full | Defining rating granularity (Full, Half, Quarter, Exact) |
| ShowLabel | false | Displaying rating value as text |
| LabelPosition | LabelPosition.Right | Positioning label (Top, Bottom, Left, Right) |
| ShowTooltip | false | Enabling hover tooltips |
| AllowReset | true | Allowing users to clear their rating |
| EnableSingleSelection | false | Single item selection mode (thumbs up/down) |
| Min | null | Setting minimum rating value |
| ReadOnly | false | Display-only mode for showing ratings |
| Disabled | false | Disabling all interactions |
| EnableAnimation | true | Enabling smooth transitions |
| Visible | true | Controlling component visibility |
| EmptyTemplate | null | Custom template for unselected items |
| FullTemplate | null | Custom template for selected items |
| LabelTemplate | null | Custom label content |
| TooltipTemplate | null | Custom tooltip content |
| CssClass | "" | Applying custom CSS classes |
| 属性 | 默认值 | 使用场景 |
|---|---|---|
| Value | 0 | 绑定评分值(用@bind-Value实现双向绑定) |
| ItemsCount | 5 | 设置评分项数量(星星) |
| Precision | PrecisionType.Full | 定义评分粒度(Full、Half、Quarter、Exact) |
| ShowLabel | false | 显示评分值文本 |
| LabelPosition | LabelPosition.Right | 设置标签位置(Top、Bottom、Left、Right) |
| ShowTooltip | false | 启用悬停工具提示 |
| AllowReset | true | 允许用户清除评分 |
| EnableSingleSelection | false | 单项选择模式(拇指向上/向下) |
| Min | null | 设置最小评分值 |
| ReadOnly | false | 仅显示评分的模式 |
| Disabled | false | 禁用所有交互 |
| EnableAnimation | true | 启用平滑过渡 |
| Visible | true | 控制组件可见性 |
| EmptyTemplate | null | 未选中项的自定义模板 |
| FullTemplate | null | 已选中项的自定义模板 |
| LabelTemplate | null | 自定义标签内容 |
| TooltipTemplate | null | 自定义工具提示内容 |
| CssClass | "" | 应用自定义CSS类 |
Common Use Cases
常见用例
- Product Reviews: E-commerce ratings, marketplace feedback, customer reviews, product quality assessment
- Service Quality: Restaurant ratings, hotel reviews, delivery service feedback, support satisfaction
- Skill Assessments: Employee evaluations, competency ratings, training feedback, proficiency levels
- Content Rating: Article feedback, video ratings, course reviews, documentation usefulness
- User Experience: App store ratings, feature satisfaction, usability scores, NPS surveys
- Performance Reviews: Team member evaluations, project ratings, goal achievements, KPI tracking
- Survey Responses: Satisfaction surveys, opinion polls, feedback forms, questionnaires
- Quality Control: Inspection ratings, compliance scoring, audit results, quality metrics
- Entertainment: Movie ratings, music reviews, book ratings, game scores
- Sentiment Analysis: Customer sentiment, brand perception, mood tracking, emotional feedback
- 产品评论:电商评分、市场反馈、客户评论、产品质量评估
- 服务质量:餐厅评分、酒店评论、配送服务反馈、支持满意度
- 技能评估:员工评估、能力评分、培训反馈、熟练程度
- 内容评分:文章反馈、视频评分、课程评论、文档实用性
- 用户体验:应用商店评分、功能满意度、可用性得分、NPS调查
- 绩效评估:团队成员评估、项目评分、目标达成、KPI跟踪
- 调查响应:满意度调查、民意测验、反馈表单、问卷
- 质量控制:检查评分、合规评分、审计结果、质量指标
- 娱乐领域:电影评分、音乐评论、书籍评分、游戏得分
- 情感分析:客户情感、品牌认知、情绪跟踪、情感反馈
Quick Decision Tree
快速决策树
User needs rating/feedback functionality
├─ Display existing rating (read-only)?
│ ├─ Set
│ ├─ Use for average ratings
│ └─ Show with review count
├─ Collect new rating from user?
│ ├─ Whole stars only? →
│ ├─ Half stars? →
│ ├─ Quarter stars? →
│ └─ Any decimal? →
├─ Custom rating scale?
│ ├─ 3-point scale →
│ ├─ 7-point scale →
│ └─ 10-point scale →
├─ Need custom icons instead of stars?
│ ├─ Hearts → Define and with ♥
│ ├─ Thumbs → Use 👍/👎 icons
│ ├─ Emojis → Use 😞😐🙂😊🤩 progression
│ └─ Custom SVG → Render SVG in templates
├─ Thumbs up/down only?
│ ├─ Set
│ ├─ Use or
│ └─ Custom templates with thumb icons
├─ Form integration needed?
│ ├─ Use within
│ ├─ Add validation attributes
│ └─ Listen to for validation
├─ Show rating feedback?
│ ├─ Enable for numeric display
│ ├─ Use for custom messages
│ ├─ Enable for hover feedback
│ └─ Use for contextual messages
└─ Accessibility requirements?
├─ Ensure keyboard navigation works (arrow keys)
├─ Test screen reader compatibility
└─ Provide clear ARIA labels
ReadOnly="true"Precision="PrecisionType.Exact"ShowLabel="true"Precision="PrecisionType.Full"Precision="PrecisionType.Half"Precision="PrecisionType.Quarter"Precision="PrecisionType.Exact"ItemsCount="3"ItemsCount="7"ItemsCount="10"EmptyTemplateFullTemplateEnableSingleSelection="true"ItemsCount="1"ItemsCount="2"<EditForm>ValueChangedShowLabel="true"LabelTemplateShowTooltip="true"TooltipTemplate用户需要评分/反馈功能
├─ 显示现有评分(只读)?
│ ├─ 设置
│ ├─ 使用显示平均评分
│ └─ 启用并显示评论数量
├─ 收集用户新评分?
│ ├─ 仅整星?→
│ ├─ 半星?→
│ ├─ 四分之一星?→
│ └─ 任意十进制?→
├─ 自定义评分刻度?
│ ├─ 3分制→
│ ├─ 7分制→
│ └─ 10分制→
├─ 需要自定义图标而非星星?
│ ├─ 心形→ 用♥定义和
│ ├─ 拇指→ 使用👍/👎图标
│ ├─ 表情→ 使用😞😐🙂😊🤩渐变
│ └─ 自定义SVG→ 在模板中渲染SVG
├─ 仅拇指向上/向下?
│ ├─ 设置
│ ├─ 使用或
│ └─ 用拇指图标自定义模板
├─ 需要表单集成?
│ ├─ 在中使用
│ ├─ 添加验证属性
│ └─ 监听实现验证
├─ 显示评分反馈?
│ ├─ 启用显示数值
│ ├─ 使用显示自定义消息
│ ├─ 启用提供悬停反馈
│ └─ 使用显示上下文消息
└─ 无障碍要求?
├─ 确保键盘导航可用(箭头键)
├─ 测试屏幕阅读器兼容性
└─ 提供清晰的ARIA标签
ReadOnly="true"Precision="PrecisionType.Exact"ShowLabel="true"Precision="PrecisionType.Full"Precision="PrecisionType.Half"Precision="PrecisionType.Quarter"Precision="PrecisionType.Exact"ItemsCount="3"ItemsCount="7"ItemsCount="10"EmptyTemplateFullTemplateEnableSingleSelection="true"ItemsCount="1"ItemsCount="2"<EditForm>ValueChangedShowLabel="true"LabelTemplateShowTooltip="true"TooltipTemplateInputMask
InputMask
Learn to implement Syncfusion Blazor InputMask (MaskedTextBox) component for formatted text input with predefined patterns, custom mask rules, prompt characters, and always get immediate masked input for phone numbers, SSN, credit cards, dates, ZIP codes, license plates, or any scenario requiring structured text entry with format validation, literal preservation, and comprehensive event handling in Blazor applications.
学习实现Syncfusion Blazor InputMask(掩码文本框)组件,用于格式化文本输入,支持预定义模式、自定义掩码规则、提示字符,在Blazor应用中为电话号码、社保号、信用卡、日期、邮政编码、车牌等场景提供即时掩码输入,包含格式验证、字面量保留和全面事件处理。
Documentation
文档
Getting Started
快速入门
📄 Read: references/inputmask-getting-started.md
- Installation and NuGet package setup
- Basic SfMaskedTextBox component setup
- Namespace imports and service registration
- CSS theme configuration
- Simple mask examples (phone, date, SSN)
- Value binding basics
- Minimal working example
📄 阅读: references/inputmask-getting-started.md
- 安装和NuGet包配置
- 基础SfMaskedTextBox组件设置
- 命名空间导入和服务注册
- CSS主题配置
- 简单掩码示例(电话、日期、社保号)
- 值绑定基础
- 最简运行示例
Mask Patterns and Configuration
掩码模式与配置
📄 Read: references/inputmask-mask-patterns.md
- Standard mask characters (0, 9, L, ?, A, &, C, #)
- Predefined patterns (phone, SSN, ZIP, date, time)
- Mask property configuration
- Literal characters in masks
- Optional vs required positions
- Complex pattern examples
- International format patterns
- Pattern validation rules
📄 阅读: references/inputmask-mask-patterns.md
- 标准掩码字符(0、9、L、?、A、&、C、#)
- 预定义模式(电话、社保号、邮政编码、日期、时间)
- Mask属性配置
- 掩码中的字面量字符
- 可选与必填位置
- 复杂模式示例
- 国际格式模式
- 模式验证规则
Custom Characters and Formatting
自定义字符与格式化
📄 Read: references/inputmask-custom-characters.md
- CustomCharacters dictionary usage
- Creating custom mask rules
- Regex-based character validation
- Advanced pattern customization
- Use cases (license plates, product codes, etc.)
- Combining custom with standard masks
- Best practices for custom rules
📄 阅读: references/inputmask-custom-characters.md
- CustomCharacters字典使用
- 创建自定义掩码规则
- 基于正则的字符验证
- 高级模式自定义
- 用例(车牌、产品代码等)
- 标准与自定义掩码结合
- 自定义规则最佳实践
Prompt Character Configuration
提示字符配置
📄 Read: references/inputmask-prompt-configuration.md
- PromptChar property (default: _)
- PromptPlaceholder for display
- EnableLiterals for value inclusion
- Placeholder vs PromptChar difference
- Visual feedback configuration
- User experience considerations
- Examples with different configurations
📄 阅读: references/inputmask-prompt-configuration.md
- PromptChar属性(默认:_)
- 显示用的PromptPlaceholder
- 值包含字面量的EnableLiterals
- Placeholder与PromptChar的区别
- 视觉反馈配置
- 用户体验考虑
- 不同配置示例
Events and Data Binding
事件与数据绑定
📄 Read: references/inputmask-events-binding.md
- Value property and @bind-Value
- ValueChange event (MaskChangeEventArgs)
- ValueChanged event callback
- Focus and Blur events (MaskFocusEventArgs, MaskBlurEventArgs)
- OnChange vs OnInput vs ValueChange timing
- EditForm integration with EditContext
- ValueExpression for validation
- Real-time validation patterns
- Event handler best practices
📄 阅读: references/inputmask-events-binding.md
- Value属性与@bind-Value
- ValueChange事件(MaskChangeEventArgs)
- ValueChanged事件回调
- Focus和Blur事件(MaskFocusEventArgs、MaskBlurEventArgs)
- OnChange、OnInput与ValueChange的时序
- 与EditContext的EditForm集成
- 验证用的ValueExpression
- 实时验证模式
- 事件处理器最佳实践
Styling and Accessibility
样式与无障碍
📄 Read: references/inputmask-styling-accessibility.md
- FloatLabelType configuration
- ShowClearButton functionality
- CssClass for custom styling
- Width and responsive sizing
- Enabled vs Readonly states
- Theme customization with Theme Studio
- WCAG 2.1 compliance
- Keyboard navigation
- ARIA attributes
- Screen reader support
- RTL (EnableRtl) support
- HtmlAttributes and InputAttributes
- Accessibility best practices
📄 阅读: references/inputmask-styling-accessibility.md
- FloatLabelType配置
- ShowClearButton功能
- 自定义样式的CssClass
- 宽度与响应式尺寸
- 启用与只读状态
- 与Theme Studio的主题自定义
- WCAG 2.1合规性
- 键盘导航
- ARIA属性
- 屏幕阅读器支持
- 从右到左布局的EnableRtl
- HtmlAttributes和InputAttributes
- 无障碍最佳实践
Quick Start Example
快速入门示例
razor
@using Syncfusion.Blazor.Inputs
<div class="input-mask-container">
<label>Phone Number:</label>
<SfMaskedTextBox @bind-Value="@phoneNumber"
Mask="(000) 000-0000"
Placeholder="Enter phone number"
FloatLabelType="FloatLabelType.Auto">
</SfMaskedTextBox>
<label>Social Security Number:</label>
<SfMaskedTextBox @bind-Value="@ssn"
Mask="000-00-0000"
PromptChar="#"
Placeholder="Enter SSN">
</SfMaskedTextBox>
</div>
@code {
private string phoneNumber = "";
private string ssn = "";
}razor
@using Syncfusion.Blazor.Inputs
<div class="input-mask-container">
<label>电话号码:</label>
<SfMaskedTextBox @bind-Value="@phoneNumber"
Mask="(000) 000-0000"
Placeholder="输入电话号码"
FloatLabelType="FloatLabelType.Auto">
</SfMaskedTextBox>
<label>社会保障号:</label>
<SfMaskedTextBox @bind-Value="@ssn"
Mask="000-00-0000"
PromptChar="#"
Placeholder="输入社保号">
</SfMaskedTextBox>
</div>
@code {
private string phoneNumber = "";
private string ssn = "";
}Common Patterns
常见模式
Pattern 1: Phone Number Input (US Format)
模式1:电话号码输入(美国格式)
- Use mask for US phone numbers
"(000) 000-0000" - Set for clear visual feedback
PromptChar="_" - Enable for two-way binding
@bind-Value - Use for modern UX
FloatLabelType.Auto - Configure for user guidance
Placeholder - Set to exclude parentheses/dashes from value
EnableLiterals="false"
- 使用掩码处理美国电话号码
"(000) 000-0000" - 设置提供清晰视觉反馈
PromptChar="_" - 启用实现双向绑定
@bind-Value - 使用获得现代UX
FloatLabelType.Auto - 配置提供用户引导
Placeholder - 设置从值中排除括号/短横线
EnableLiterals="false"
Pattern 2: Social Security Number (SSN)
模式2:社会保障号(SSN)
- Use mask for SSN format
"000-00-0000" - Set or
PromptChar="#"for privacyPromptChar="*" - Apply for input,
Readonly="false"for displayReadonly="true" - Use for quick reset
ShowClearButton="true" - Implement validation with event
ValueChange - Consider masking display value for security
- 使用掩码处理SSN格式
"000-00-0000" - 设置或
PromptChar="#"保护隐私PromptChar="*" - 输入时设置,显示时设置
Readonly="false"Readonly="true" - 启用实现快速重置
ShowClearButton="true" - 通过事件实现验证
ValueChange - 考虑在显示时掩码部分内容提升安全性
Pattern 3: Credit Card Number with Separators
模式3:带分隔符的信用卡号
- Use mask for 16-digit cards
"0000 0000 0000 0000" - Set to get digits only
EnableLiterals="false" - Listen to to detect card type (Visa, MC, Amex)
ValueChange - Show card brand icon based on first digits
- Apply real-time Luhn algorithm validation
- Use for clear empty positions
PromptChar="X"
- 使用掩码处理16位卡号
"0000 0000 0000 0000" - 设置仅获取数字
EnableLiterals="false" - 监听检测卡类型(Visa、MC、Amex)
ValueChange - 根据前几位显示卡品牌图标
- 应用实时Luhn算法验证
- 使用清晰显示空位置
PromptChar="X"
Pattern 4: Date Input with Custom Format
模式4:自定义格式日期输入
- Use mask for MM/DD/YYYY format
"00/00/0000" - Or for DD-MM-YYYY format
"00-00-0000" - Set for format guidance
Placeholder="MM/DD/YYYY" - Implement custom validation for valid dates
- Use to validate day/month ranges
ValueChange - Consider using DatePicker component for complex date selection
- 使用掩码处理MM/DD/YYYY格式
"00/00/0000" - 或使用处理DD-MM-YYYY格式
"00-00-0000" - 设置提供格式引导
Placeholder="MM/DD/YYYY" - 实现自定义验证确保日期有效
- 使用验证日/月范围
ValueChange - 复杂日期选择考虑使用DatePicker组件
Pattern 5: Custom Product Code Format
模式5:自定义产品代码格式
- Define dictionary for special rules
CustomCharacters - Example:
@(new Dictionary<string, string> { { "P", "[A-Z]" }, { "N", "[0-9]" } }) - Use mask like for ABC-123-456 format
"PPP-NNN-NNN" - Combine standard and custom characters
- Apply for uppercase conversion
TextTransform - Validate against business rules in events
- 定义字典设置特殊规则
CustomCharacters - 示例:
@(new Dictionary<string, string> { { "P", "[A-Z]" }, { "N", "[0-9]" } }) - 使用类似的掩码实现ABC-123-456格式
"PPP-NNN-NNN" - 结合标准与自定义字符
- 应用转换为大写
TextTransform - 在事件中验证业务规则
Pattern 6: International Phone with Custom Characters
模式6:带自定义字符的国际电话号码
- Use for country-specific patterns
CustomCharacters - Example: with country code
"+00 (000) 000-0000" - Set to include + and formatting
EnableLiterals="true" - Display country flag based on code
- Implement dynamic mask switching per country
- Support multiple international formats
- 使用支持国家特定模式
CustomCharacters - 示例:带国家代码
"+00 (000) 000-0000" - 设置包含+和格式字符
EnableLiterals="true" - 根据代码显示国家旗帜
- 实现基于地区的动态掩码切换
- 支持多种国际格式
Key Props
关键属性
| Property | Default | Use When |
|---|---|---|
| Mask | "" | Defining input format pattern (required) |
| Value | "" | Binding masked input value |
| PromptChar | '_' | Setting placeholder character for empty positions |
| PromptPlaceholder | null | Overriding prompt character in placeholder mode |
| EnableLiterals | true | Include/exclude literal characters in value |
| CustomCharacters | null | Defining custom mask rules with regex |
| Placeholder | "" | Showing hint text when empty |
| FloatLabelType | FloatLabelType.Never | Enabling floating label animation |
| ShowClearButton | false | Adding quick clear functionality |
| Readonly | false | Preventing edits while showing masked value |
| Enabled | true | Enabling/disabling the component |
| Width | "" | Setting component width |
| CssClass | "" | Applying custom CSS classes |
| EnableRtl | false | Enabling right-to-left text direction |
| HtmlAttributes | null | Adding custom HTML attributes to wrapper |
| InputAttributes | null | Adding custom attributes to input element |
| TabIndex | 0 | Setting tab navigation order |
| 属性 | 默认值 | 使用场景 |
|---|---|---|
| Mask | "" | 定义输入格式模式(必填) |
| Value | "" | 绑定掩码输入值 |
| PromptChar | '_' | 设置空位置的占位符字符 |
| PromptPlaceholder | null | 覆盖占位符模式下的提示字符 |
| EnableLiterals | true | 值中包含/排除字面量字符 |
| CustomCharacters | null | 用正则定义自定义掩码规则 |
| Placeholder | "" | 为空时显示提示文本 |
| FloatLabelType | FloatLabelType.Never | 启用浮动标签动画 |
| ShowClearButton | false | 添加快速清除功能 |
| Readonly | false | 阻止编辑但显示掩码值 |
| Enabled | true | 启用/禁用组件 |
| Width | "" | 设置组件宽度 |
| CssClass | "" | 应用自定义CSS类 |
| EnableRtl | false | 启用从右到左文本方向 |
| HtmlAttributes | null | 为包装器添加自定义HTML属性 |
| InputAttributes | null | 为输入元素添加自定义属性 |
| TabIndex | 0 | 设置Tab导航顺序 |
Common Use Cases
常见用例
- Contact Information: Phone numbers, fax numbers, mobile numbers with country codes
- Personal Identification: SSN, tax ID, national ID, passport numbers, driver's license
- Financial Data: Credit card numbers, bank account numbers, routing numbers, CVV codes
- Dates and Times: Custom date formats, time entry, date ranges with specific patterns
- Postal Codes: ZIP codes (US), postal codes (international), area codes with formatting
- Product Identification: SKU numbers, serial numbers, product codes, barcode entry
- License Numbers: Vehicle plates, software licenses, registration numbers with patterns
- Network Information: IP addresses, MAC addresses, subnet masks with dot notation
- Version Numbers: Software versions (1.2.3), build numbers with custom formats
- Custom Codes: Voucher codes, promo codes, tracking numbers with specific patterns
- 联系信息:电话号码、传真号码、带国家代码的手机号
- 个人身份:社保号、税号、国家ID、护照号、驾照
- 金融数据:信用卡号、银行账户号、路由号、CVV码
- 日期与时间:自定义日期格式、时间输入、带特定模式的日期范围
- 邮政编码:美国ZIP码、国际邮政编码、带格式的区号
- 产品标识:SKU编号、序列号、产品代码、条码输入
- 许可证编号:车牌、软件许可证、带模式的注册号
- 网络信息:IP地址、MAC地址、带点分格式的子网掩码
- 版本号:软件版本(1.2.3)、带自定义格式的构建号
- 自定义代码:优惠券代码、促销码、带特定模式的跟踪号
Quick Decision Tree
快速决策树
User needs formatted text input with pattern
├─ Standard formats?
│ ├─ US Phone →
│ ├─ SSN →
│ ├─ ZIP Code → or
│ ├─ Credit Card →
│ ├─ Date → (MM/DD/YYYY)
│ └─ Time → (HH:MM)
├─ Need digits only in value?
│ ├─ Set
│ └─ Mask literals will be excluded from Value
├─ Include formatting in value?
│ ├─ Set (default)
│ └─ Value will include parentheses, dashes, etc.
├─ Custom pattern (not standard)?
│ ├─ Use dictionary
│ ├─ Define regex for each custom character
│ ├─ Example: { "P", "[A-Z]" } for uppercase letters
│ └─ Combine in mask:
├─ Privacy/security concerns?
│ ├─ Set or
│ ├─ Use for display-only masked data
│ └─ Implement additional masking on display if needed
├─ International format support?
│ ├─ Use for flexible patterns
│ ├─ Implement dynamic mask switching based on locale
│ └─ Consider country/region selection
├─ Form validation needed?
│ ├─ Use within with model binding
│ ├─ Add for validation
│ ├─ Apply data annotations ([Required], [StringLength])
│ ├─ Listen to for real-time validation
│ └─ Implement custom validation logic (Luhn, date ranges)
├─ Enhance user experience?
│ ├─ Set
│ ├─ Enable for quick reset
│ ├─ Use meaningful text
│ └─ Provide visual feedback on validation
└─ Accessibility important?
├─ Ensure keyboard navigation works
├─ Set proper ARIA labels via
├─ Test screen reader compatibility
└─ Provide clear format instructions in label/placeholder
Mask="(000) 000-0000"Mask="000-00-0000"Mask="00000"Mask="00000-0000"Mask="0000 0000 0000 0000"Mask="00/00/0000"Mask="00:00"EnableLiterals="false"EnableLiterals="true"CustomCharacters"PPP-000-NNN"PromptChar="*"PromptChar="#"Readonly="true"CustomCharacters<EditForm>ValueExpressionValueChangeFloatLabelType="FloatLabelType.Auto"ShowClearButton="true"PlaceholderHtmlAttributes用户需要带模式的格式化文本输入
├─ 标准格式?
│ ├─ 美国电话→
│ ├─ 社保号→
│ ├─ 邮政编码→ 或
│ ├─ 信用卡→
│ ├─ 日期→ (MM/DD/YYYY)
│ └─ 时间→ (HH:MM)
├─ 值中仅需数字?
│ ├─ 设置
│ └─ 掩码字面量将从Value中排除
├─ 值中包含格式字符?
│ ├─ 设置(默认)
│ └─ Value将包含括号、短横线等
├─ 自定义模式(非标准)?
│ ├─ 使用字典
│ ├─ 为每个自定义字符定义正则
│ ├─ 示例:{ "P", "[A-Z]" }代表大写字母
│ └─ 在掩码中组合:
├─ 隐私/安全顾虑?
│ ├─ 设置或
│ ├─ 用显示仅掩码数据
│ └─ 必要时在显示时额外掩码内容
├─ 支持国际格式?
│ ├─ 使用实现灵活模式
│ ├─ 基于区域实现动态掩码切换
│ └─ 考虑国家/地区选择
├─ 需要表单验证?
│ ├─ 在中使用并绑定模型
│ ├─ 添加用于验证
│ ├─ 应用数据注解([Required]、[StringLength])
│ ├─ 监听实现实时验证
│ └─ 实现自定义验证逻辑(Luhn、日期范围)
├─ 提升用户体验?
│ ├─ 设置
│ ├─ 启用实现快速重置
│ ├─ 使用有意义的文本
│ └─ 提供验证视觉反馈
└─ 无障碍重要?
├─ 确保键盘导航可用
├─ 通过设置正确的ARIA标签
├─ 测试屏幕阅读器兼容性
└─ 在标签/占位符中提供清晰格式说明
Mask="(000) 000-0000"Mask="000-00-0000"Mask="00000"Mask="00000-0000"Mask="0000 0000 0000 0000"Mask="00/00/0000"Mask="00:00"EnableLiterals="false"EnableLiterals="true"CustomCharacters"PPP-000-NNN"PromptChar="*"PromptChar="#"Readonly="true"CustomCharacters<EditForm>ValueExpressionValueChangeFloatLabelType="FloatLabelType.Auto"ShowClearButton="true"PlaceholderHtmlAttributesColorPicker
ColorPicker
Learn to implement Syncfusion Blazor ColorPicker component for intuitive color selection with picker and palette modes, opacity control, preset color collections, inline or popup display, mode switching, and always get immediate color input for themes, UI customization, design tools, data visualization, branding, or any scenario requiring color selection with hex/rgba values, recent colors tracking, and comprehensive event handling in Blazor applications.
学习实现Syncfusion Blazor ColorPicker组件,用于直观的颜色选择,支持选择器和调色板模式、透明度控制、预设颜色集合、内联或弹出显示、模式切换,在Blazor应用中为主题、UI自定义、设计工具、数据可视化、品牌等场景提供即时颜色输入,包含十六进制/RGBA值、最近颜色跟踪和全面事件处理。
Documentation
文档
Getting Started
快速入门
📄 Read: references/colorpicker-getting-started.md
- Installation and NuGet package setup
- Basic SfColorPicker component setup
- Namespace imports and service registration
- CSS theme configuration
- Value binding with color formats
- Mode overview (Picker vs Palette)
- Minimal working example
📄 阅读: references/colorpicker-getting-started.md
- 安装和NuGet包配置
- 基础SfColorPicker组件设置
- 命名空间导入和服务注册
- CSS主题配置
- 颜色格式的值绑定
- 模式概述(Picker vs Palette)
- 最简运行示例
Modes and Configuration
模式与配置
📄 Read: references/colorpicker-modes-configuration.md
- ColorPickerMode (Picker vs Palette)
- Picker mode for gradient color selection
- Palette mode for predefined color grids
- Inline vs Popup display options
- ModeSwitcher for user mode selection
- Columns configuration for palette layout
- ShowButtons for Apply/Cancel actions
- Mode-specific behaviors and use cases
📄 阅读: references/colorpicker-modes-configuration.md
- ColorPickerMode(Picker vs Palette)
- 渐变颜色选择的Picker模式
- 预定义颜色网格的Palette模式
- 内联与弹出显示选项
- 允许用户切换模式的ModeSwitcher
- 调色板布局的Columns配置
- Apply/Cancel按钮的ShowButtons
- 模式特定行为与用例
Preset Colors and Palettes
预设颜色与调色板
📄 Read: references/colorpicker-presets-colors.md
- PresetColors dictionary configuration
- Custom color palette groups
- Default preset color collections
- ShowRecentColors functionality
- NoColor option for "no selection"
- Organizing preset categories
- Business and design use cases
📄 阅读: references/colorpicker-presets-colors.md
- PresetColors字典配置
- 自定义颜色调色板组
- 默认预设颜色集合
- 最近颜色跟踪的ShowRecentColors
- “无颜色”选项的NoColor
- 预设类别组织
- 业务与设计用例
Opacity and Value Formats
透明度与值格式
📄 Read: references/colorpicker-opacity-values.md
- EnableOpacity for alpha channel control
- Opacity slider configuration
- Value formats (hex, rgba, hsva)
- Reading and setting opacity values
- Transparent color handling
- Use cases (overlays, highlights, transparency)
📄 阅读: references/colorpicker-opacity-values.md
- 启用Alpha通道控制的EnableOpacity
- 透明度滑块配置
- 值格式(hex、rgba、hsva)
- 透明度值的读取与设置
- 透明颜色处理
- 用例(覆盖层、高亮、透明度)
Events and Data Binding
事件与数据绑定
📄 Read: references/colorpicker-events-binding.md
- Value property and two-way binding (@bind-Value)
- ValueChanged event callback
- Selected event with ColorPickerEventArgs
- OnOpen and OnClose events for popup control
- ModeSwitched event handling
- OnTileRender for custom palette tiles
- Form integration with EditForm
- Real-time color preview patterns
📄 阅读: references/colorpicker-events-binding.md
- Value属性与双向绑定(@bind-Value)
- ValueChanged事件回调
- 带ColorPickerEventArgs的Selected事件
- 弹出控制的OnOpen和OnClose事件
- 模式切换的ModeSwitched事件处理
- 自定义调色板瓦片的OnTileRender
- 与EditForm的表单集成
- 实时颜色预览模式
Customization and Accessibility
自定义与无障碍
📄 Read: references/colorpicker-customization-accessibility.md
- ShowButtons configuration
- CssClass for custom styling
- Disabled and EnableRtl states
- HtmlAttributes customization
- Keyboard navigation support
- ARIA attributes for accessibility
- WCAG 2.1 compliance
- Theme customization with Theme Studio
- Responsive design patterns
📄 阅读: references/colorpicker-customization-accessibility.md
- ShowButtons配置
- 自定义样式的CssClass
- 禁用与EnableRtl状态
- HtmlAttributes自定义
- 键盘导航支持
- 无障碍ARIA属性
- WCAG 2.1合规性
- 与Theme Studio的主题自定义
- 响应式设计模式
Quick Start Example
快速入门示例
razor
@using Syncfusion.Blazor.Inputs
<div class="colorpicker-container">
<label>Choose a color:</label>
<SfColorPicker @bind-Value="@selectedColor"
Mode="ColorPickerMode.Palette"
ShowButtons="true">
</SfColorPicker>
<div class="color-preview" style="background-color: @selectedColor;">
Selected: @selectedColor
</div>
</div>
@code {
private string selectedColor = "#008000";
}razor
@using Syncfusion.Blazor.Inputs
<div class="colorpicker-container">
<label>选择颜色:</label>
<SfColorPicker @bind-Value="@selectedColor"
Mode="ColorPickerMode.Palette"
ShowButtons="true">
</SfColorPicker>
<div class="color-preview" style="background-color: @selectedColor;">
已选择:@selectedColor
</div>
</div>
@code {
private string selectedColor = "#008000";
}Common Patterns
常见模式
Pattern 1: Basic Palette Color Picker
模式1:基础调色板颜色选择器
- Use for predefined color grid
Mode="ColorPickerMode.Palette" - Enable for two-way binding
@bind-Value - Set for Apply/Cancel actions
ShowButtons="true" - Use default PresetColors or customize
- Bind to string variable for hex values
- Display preview with selected color
- 使用启用预定义颜色网格
Mode="ColorPickerMode.Palette" - 启用实现双向绑定
@bind-Value - 设置启用Apply/Cancel按钮
ShowButtons="true" - 使用默认PresetColors或自定义
- 绑定到字符串变量存储十六进制值
- 显示选中颜色的预览
Pattern 2: Advanced Gradient Picker with Opacity
模式2:带透明度的高级渐变选择器
- Set for gradient selector
Mode="ColorPickerMode.Picker" - Enable for alpha channel
EnableOpacity="true" - Use to allow mode switching
ModeSwitcher="true" - Display rgba value for transparency
- Ideal for design tools, graphics editors
- Show real-time preview with opacity
- 设置启用渐变选择器
Mode="ColorPickerMode.Picker" - 启用启用Alpha通道
EnableOpacity="true" - 启用允许模式切换
ModeSwitcher="true" - 显示带透明度的rgba值
- 适用于设计工具、图形编辑器
- 显示带透明度的实时预览
Pattern 3: Inline Color Selector (No Popup)
模式3:内联颜色选择器(无弹出)
- Set for always-visible picker
Inline="true" - Use for color customization panels
- No popup trigger, immediate display
- Works with both Picker and Palette modes
- Combine with for instant selection
ShowButtons="false" - Perfect for settings panels, theme builders
- 设置实现始终可见的选择器
Inline="true" - 用于颜色自定义面板
- 无弹出触发,即时显示
- 适用于Picker和Palette模式
- 结合实现即时选择
ShowButtons="false" - 完美用于设置面板、主题构建器
Pattern 4: Custom Preset Palette
模式4:自定义预设调色板
- Define dictionary with custom groups
PresetColors - Organize by categories (brand colors, pastels, etc.)
- Set property for grid layout
Columns - Use for history
ShowRecentColors="true" - Enable for "no selection" option
NoColor="true" - Ideal for brand color systems, design systems
- 定义字典设置自定义组
PresetColors - 按类别组织(品牌色、马卡龙色等)
- 设置属性配置网格布局
Columns - 启用跟踪历史
ShowRecentColors="true" - 启用提供“无选择”选项
NoColor="true" - 适用于品牌颜色系统、设计系统
Key Props
关键属性
| Property | Default | Use When |
|---|---|---|
| Value | "" | Binding selected color (hex, rgba, hsva) |
| Mode | ColorPickerMode.Picker | Choosing Picker (gradient) or Palette (grid) |
| Inline | false | Display picker inline instead of popup |
| ModeSwitcher | false | Allow user to switch between Picker and Palette |
| EnableOpacity | false | Enable alpha channel/transparency control |
| ShowButtons | false | Show Apply and Cancel buttons (popup mode) |
| ShowRecentColors | true | Display recently selected colors |
| PresetColors | null | Custom preset color palette dictionary |
| Columns | 10 | Number of columns in palette mode |
| NoColor | false | Allow "no color" selection option |
| Disabled | false | Disable color selection entirely |
| EnableRtl | false | Enable right-to-left layout |
| CssClass | "" | Apply custom CSS classes |
| HtmlAttributes | null | Add custom HTML attributes |
| 属性 | 默认值 | 使用场景 |
|---|---|---|
| Value | "" | 绑定选中颜色(hex、rgba、hsva) |
| Mode | ColorPickerMode.Picker | 选择Picker(渐变)或Palette(网格) |
| Inline | false | 内联显示选择器而非弹出 |
| ModeSwitcher | false | 允许用户在Picker和Palette间切换 |
| EnableOpacity | false | 启用Alpha通道/透明度控制 |
| ShowButtons | false | 显示Apply和Cancel按钮(弹出模式) |
| ShowRecentColors | true | 显示最近选中的颜色 |
| PresetColors | null | 自定义预设颜色调色板字典 |
| Columns | 10 | 调色板模式下的列数 |
| NoColor | false | 允许“无颜色”选择选项 |
| Disabled | false | 完全禁用颜色选择 |
| EnableRtl | false | 启用从右到左布局 |
| CssClass | "" | 应用自定义CSS类 |
| HtmlAttributes | null | 添加自定义HTML属性 |
Common Use Cases
常见用例
- UI Theme Customization: User-selectable themes, color scheme builders, personalization
- Design Tools: Graphic editors, drawing apps, image annotation, markup tools
- Data Visualization: Chart color selection, graph customization, report styling
- Branding: Logo colors, brand identity, style guide implementation, corporate colors
- Web Design: CSS color selection, background colors, text colors, border colors
- Product Customization: Product color variants, custom merchandise, personalization
- Highlighting Tools: Text highlighters, annotation colors, emphasis markers
- Dashboard Customization: Widget colors, status indicators, category colors
- Form Builders: Custom form styling, input colors, validation colors
- Calendar/Scheduling: Event colors, category coding, priority indicators
- UI主题自定义:用户可选主题、配色方案构建器、个性化设置
- 设计工具:图形编辑器、绘图应用、图像标注、标记工具
- 数据可视化:图表颜色选择、图形自定义、报告样式
- 品牌建设:Logo颜色、品牌标识、风格指南实现、企业颜色
- 网页设计:CSS颜色选择、背景色、文本颜色、边框颜色
- 产品自定义:产品颜色变体、定制商品、个性化设置
- 高亮工具:文本高亮、标注颜色、强调标记
- 仪表板自定义:组件颜色、状态指示器、类别颜色
- 表单构建器:自定义表单样式、输入颜色、验证颜色
- 日历/日程安排:事件颜色、类别编码、优先级指示器
Quick Decision Tree
快速决策树
User needs color selection functionality
├─ Specific predefined colors only?
│ ├─ Use
│ ├─ Set with custom palette
│ └─ Configure for grid layout
├─ Any color from gradient?
│ ├─ Use (default)
│ └─ Users can select from full color spectrum
├─ Allow both modes?
│ ├─ Enable
│ └─ Users can toggle between Picker and Palette
├─ Need transparency/opacity?
│ ├─ Set
│ ├─ Value will include alpha (rgba format)
│ └─ Show opacity slider for user control
├─ Always visible (no popup)?
│ ├─ Set
│ ├─ Use in settings panels, sidebars
│ └─ Consider for instant selection
├─ Popup with confirmation?
│ ├─ Use (default)
│ ├─ Set for Apply/Cancel
│ └─ Listen to event for confirmed selection
├─ Track recent colors?
│ ├─ Enable (default)
│ └─ Recent colors displayed automatically
├─ Allow "no color" selection?
│ ├─ Set
│ └─ User can clear color selection
├─ Custom color palette needed?
│ ├─ Define dictionary
│ ├─ Group colors by category
│ └─ Example: { "Basic": ["#fff", "#000"], "Brand": ["#e74c3c", "#3498db"] }
├─ Form integration required?
│ ├─ Use within
│ ├─ Apply validation attributes
│ └─ Listen to for validation
└─ Accessibility important?
├─ Ensure keyboard navigation works (Tab, Enter, Escape)
├─ Test screen reader compatibility
└─ Provide clear labels via
Mode="ColorPickerMode.Palette"PresetColorsColumnsMode="ColorPickerMode.Picker"ModeSwitcher="true"EnableOpacity="true"Inline="true"ShowButtons="false"Inline="false"ShowButtons="true"SelectedShowRecentColors="true"NoColor="true"PresetColors<EditForm>ValueChangedHtmlAttributes用户需要颜色选择功能
├─ 仅特定预定义颜色?
│ ├─ 使用
│ ├─ 设置自定义调色板
│ └─ 配置设置网格布局
├─ 从渐变中选择任意颜色?
│ ├─ 使用(默认)
│ └─ 用户可从全色谱中选择
├─ 允许两种模式?
│ ├─ 启用
│ └─ 用户可在Picker和Palette间切换
├─ 需要透明度/不透明度?
│ ├─ 设置
│ ├─ 值将包含Alpha通道(rgba格式)
│ └─ 显示透明度滑块供用户控制
├─ 始终可见(无弹出)?
│ ├─ 设置
│ ├─ 用于设置面板、侧边栏
│ └─ 考虑实现即时选择
├─ 带确认的弹出?
│ ├─ 使用(默认)
│ ├─ 设置启用Apply/Cancel
│ └─ 监听事件获取确认后的选择
├─ 跟踪最近颜色?
│ ├─ 启用(默认)
│ └─ 自动显示最近颜色
├─ 允许“无颜色”选择?
│ ├─ 设置
│ └─ 用户可清除颜色选择
├─ 需要自定义颜色调色板?
│ ├─ 定义字典
│ ├─ 按类别分组颜色
│ └─ 示例:{ "基础色": ["#fff", "#000"], "品牌色": ["#e74c3c", "#3498db"] }
├─ 需要表单集成?
│ ├─ 在中使用
│ ├─ 应用验证属性
│ └─ 监听实现验证
└─ 无障碍重要?
├─ 确保键盘导航可用(Tab、Enter、Escape)
├─ 测试屏幕阅读器兼容性
└─ 通过提供清晰标签
Mode="ColorPickerMode.Palette"PresetColorsColumnsMode="ColorPickerMode.Picker"ModeSwitcher="true"EnableOpacity="true"Inline="true"ShowButtons="false"Inline="false"ShowButtons="true"SelectedShowRecentColors="true"NoColor="true"PresetColors<EditForm>ValueChangedHtmlAttributes