syncfusion-blazor-inputs

实现 Syncfusion Blazor FileUpload

本技能介绍 Syncfusion Blazor FileUpload 组件，这是一款适用于 Blazor 应用的强大文件处理解决方案。了解如何实现单文件和多文件上传、配置验证规则、启用拖放交互、通过分块上传处理大文件，以及利用全面的事件实现完整的上传控制和用户反馈。

---

FileUpload

了解如何实现 Syncfusion Blazor File Upload 组件，支持异步/同步上传、验证、事件和自定义；还可通过拖放或表单集成，在 Web 和服务器应用中即时处理文件。

文档

入门

📄 阅读： references/file-upload-getting-started.md

• 安装和 NuGet 包设置
• Visual Studio/Visual Studio Code 设置步骤
• Blazor WebAssembly 与 Server 配置
• 基本的 SfUploader 组件渲染
• CSS 和脚本导入
• 最小可运行示例

核心配置

📄 阅读： references/file-upload-configuration.md

• 用于组件标识的 ID 属性
• 用于限制文件类型的 AllowedExtensions
• AllowMultiple 与单文件上传
• AutoUpload 行为配置
• 按顺序处理的 SequentialUpload
• DirectoryUpload 功能
• Enabled 状态和组件控制

上传方式与行为

📄 阅读： references/file-upload-file-upload-methods.md

• 同步与异步上传
• Save URL 和 Remove URL 配置
• 上传按钮点击处理程序
• 自动或手动触发上传
• 上传进度跟踪机制
• 后端 API 要求

事件与处理程序

📄 阅读： references/file-upload-events-and-handlers.md

• 用于直接访问文件的 ValueChange 事件（仅限 Blazor Server，且不使用 AsyncSettings）
• 用于预验证的 FileSelected 事件
• 用于初始化逻辑的 Created 事件
• 用于自定义文件显示的 OnFileListRender
• OnUploadStart、Success、OnFailure 事件（与 AsyncSettings 一起使用）
• 事件处理程序模式和最佳实践
• 重要： ValueChange 和 UploaderAsyncSettings 不能同时使用

文件验证

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

• 文件类型验证策略
• 文件大小限制（MinFileSize、MaxFileSize）
• 自定义验证函数
• 阻止无效文件上传
• 错误消息和用户反馈
• 在 EditForm 中进行验证

高级功能

📄 阅读： references/file-upload-advanced-features.md

• 大文件分块上传
• 暂停和恢复功能
• 事件处理程序中的 async/await 模式
• 不进行磁盘 I/O 的 MemoryStream 处理
• 批量上传操作
• 重试和恢复机制

自定义与样式

📄 阅读： references/file-upload-customization.md

• 自定义文件列表模板
• CSS 类自定义
• Theme Studio 集成
• 自定义按钮样式
• 深色模式支持
• 响应式设计模式

文件来源选项

📄 阅读： references/file-upload-file-source-options.md

• 拖放上传实现
• 表单集成模式
• 直接与文件选择器交互
• 使用浏览器文件对话框
• 目录选择和上传
• 多种输入方式组合
• 无障碍最佳实践

本地化与无障碍

📄 阅读： references/file-upload-localization-accessibility.md

• 多语言 UI 支持
• 区域设置配置选项
• 自定义文本标签
• 符合 WCAG 2.1 标准
• 键盘导航实现
• 屏幕阅读器支持
• ARIA 属性

平台专属设置

📄 阅读： references/file-upload-platform-specific-setup.md

• Blazor WebAssembly 应用设置
• Blazor Server 应用设置
• Blazor Web App（.NET 8+）设置
• MAUI 集成
• 不同的渲染模式
• 平台专属注意事项

快速入门示例

@using Syncfusion.Blazor.Inputs

<SfUploader AutoUpload="true" AllowedExtensions=".jpg,.jpeg,.png,.pdf">
    <UploaderAsyncSettings 
        SaveUrl="api/upload/save" 
        RemoveUrl="api/upload/remove">
    </UploaderAsyncSettings>
</SfUploader>

常见模式

模式 1：带验证的基本文件上传（服务端上传）

• 使用 AutoUpload="true" 实现即时上传
• 使用 SaveUrl/RemoveUrl 配置 UploaderAsyncSettings
• 设置 AllowedExtensions 以限制文件类型
• 监听 FileSelected 事件进行预验证
• 使用 Success/OnFailure 事件反馈上传结果

模式 2：直接访问文件（仅限 Blazor Server）

• 使用 ValueChange 事件直接访问文件内容
• 不要使用 UploaderAsyncSettings 搭配 ValueChange
• 在内存中处理文件或将文件保存到目录
• 适用于文件预览、Base64 转换或直接存储

模式 3：处理多个文件

• 设置 AllowMultiple="true" 以允许批量上传
• 使用 SequentialUpload 按顺序处理
• 使用上传事件跟踪进度
• 显示文件列表及各文件的进度指示器

模式 4：使用分块上传大文件

• 在 UploaderAsyncSettings 中配置 ChunkSize
• 启用分块上传的暂停和恢复功能
• 为上传失败的分块实现重试逻辑
• 向用户显示分块级别的进度

关键属性

属性	默认值	使用场景
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	启用从右到左布局

常见用例

1. 文档上传：简历、PDF、证书文件上传
2. 图片库：用户头像、照片集
3. 数据导入：导入 CSV/Excel 文件以处理数据
4. 媒体库：视频、音频文件的上传和管理
5. 备份上传：数据库备份、配置文件
6. 报告生成：月度报告、分析数据
7. 发票处理：财务文档上传
8. 用户附件：电子邮件附件、消息文件

快速决策树

用户需要文件上传功能 ├─ 仅单个文件？→ 设置 AllowMultiple="false" + 使用基本设置 ├─ 多个文件？ │ ├─ 一次全部上传？→ AllowMultiple="true" + SequentialUpload="false" │ └─ 逐个上传？→ AllowMultiple="true" + SequentialUpload="true" └─ 大文件（>100MB）？ ├─ 启用分块上传 → 设置 ChunkSize 属性 └─ 添加暂停和恢复功能 → 监听 Paused 和 OnResume 事件

---

TextArea

了解如何实现 Syncfusion Blazor TextArea 组件，用于多行文本输入，并支持可配置的调整大小模式、行列尺寸、字符限制、浮动标签和全面验证。非常适合评论、描述、消息，以及任何需要扩展文本输入、实时反馈和表单集成的场景。

文档

入门指南

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

• 安装和 NuGet 包设置
• SfTextArea 组件的基本设置
• 命名空间导入和服务注册
• CSS 主题配置
• 最简可运行示例
• 初始组件渲染

配置选项

📄 阅读： references/textarea-configuration.md

• 使用 RowCount 和 ColumnCount 设置大小
• ResizeMode（Vertical、Horizontal、Both、None）
• 用于限制字符数的 MaxLength 属性
• 占位文本配置
• FloatLabelType（Auto、Always、Never）
• ReadOnly 和 Disabled 状态
• Width 属性和响应式尺寸
• 自定义 HTML 属性

事件和数据绑定

📄 阅读： references/textarea-events-binding.md

• Value 属性和双向绑定（@bind-Value）
• 用于实时更新的 ValueChange 事件
• Focus 和 Blur 事件（TextAreaFocusInEventArgs、TextAreaFocusOutEventArgs）
• 用于跟踪按键输入的 Input 事件
• Created 和 Destroyed 生命周期事件
• 与 EditForm 集成的表单验证
• 用于验证绑定的 ValueExpression

自定义和样式

📄 阅读： references/textarea-customization.md

• 使用 CssClass 自定义样式
• 使用 ShowClearButton 快速清除文本
• InputAttributes 和 HtmlAttributes
• 使用 Theme Studio 自定义主题
• 响应式设计模式
• 无障碍功能（ARIA、键盘导航）
• 使用 EnableRtl 支持 RTL（从右向左）

快速入门示例

@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 = "";
}

常见模式

模式 1：基本多行输入

• 使用 RowCount 设置可见行数（默认值：2）
• 设置 Placeholder 为用户提供提示
• 启用 @bind-Value 进行双向绑定
• 使用 MaxLength 限制字符数

模式 2：带限制的可调整大小 TextArea

• 设置 ResizeMode="Resize.Both" 以允许用户调整大小
• 配置 RowCount 和 ColumnCount 设置初始大小
• 使用 MaxLength 防止输入过多内容
• 监听 ValueChange 实时统计字符数

模式 3：集成验证的表单

• 使用模型绑定将组件包在 <EditForm> 中
• 将 @bind-Value 与 ValueExpression 配合使用
• 应用 [Required] 或 [StringLength] 属性
• 使用 <ValidationMessage> 显示验证消息
• 使用 CSS 设置无效状态的样式

模式 4：自动增高的 TextArea

• 设置 ResizeMode="Resize.Vertical" 以允许垂直扩展
• 从最小 RowCount 开始（例如，3）
• 允许用户根据需要扩展
• 配合 MaxLength 设置上限

主要属性

属性	默认值	使用场景
Value	""	绑定文本区域内容
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	启用从右向左的文本方向

常见用例

1. 评论区：用户反馈、评审意见、讨论串
2. 表单描述：产品描述、个人简介部分、关于字段
3. 消息撰写：电子邮件正文、聊天消息、记笔记
4. 代码/JSON 输入：配置文件、脚本输入、数据录入
5. 地址字段：输入包含街道、城市等信息的多行地址
6. 搜索查询：包含多个条件的复杂搜索输入
7. 客户支持：工单描述、问题报告、帮助请求
8. 内容管理：文章草稿、博客文章编辑、文档编写

快速决策树

用户需要多行文本输入 ├─ 固定大小？→ 设置 ResizeMode="Resize.None" + 特定 RowCount ├─ 用户可调整大小？ │ ├─ 仅垂直方向？→ ResizeMode="Resize.Vertical" │ ├─ 仅水平方向？→ ResizeMode="Resize.Horizontal" │ └─ 两个方向？→ ResizeMode="Resize.Both" ├─ 需要字符数限制？→ 设置 MaxLength 属性 └─ 表单验证？ ├─ 在 <EditForm> 中使用 └─ 添加 ValueExpression 以绑定验证

---

签名

了解如何实现 Syncfusion Blazor Signature 组件，以捕获数字签名，并配置笔画宽度、颜色、背景图像、保存/加载功能（支持 PNG、JPEG、SVG 多种格式）以及全面的事件处理。非常适用于电子签名、文档审批工作流、数字同意书，以及任何需要通过触控和鼠标捕获手写签名的场景。

文档

入门指南

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

• 安装和 NuGet 包设置
• SfSignature 组件基本设置
• 命名空间导入和服务注册
• CSS 主题配置
• 画布渲染和初始化
• 触控和鼠标输入支持
• 最小可运行示例

绘制配置

📄 阅读： references/signature-drawing-configuration.md

• 用于设置笔画粗细的 MinStrokeWidth 和 MaxStrokeWidth
• 用于自定义墨水颜色的 StrokeColor
• 用于设置画布背景的 BackgroundColor
• 用于添加信纸抬头/水印的 BackgroundImage
• 用于平滑笔画的 Velocity 属性
• 绘制行为和响应能力
• 压力灵敏度模拟

保存和加载签名

📄 阅读： references/signature-save-load.md

• 带格式选项（PNG、JPEG、SVG）的 Save() 方法
• SaveWithBackground 属性配置
• 使用 GetSignature() 获取 Base64 字符串
• 用于加载现有签名的 Load() 方法
• 用于移除签名的 Clear() 方法
• 文件格式选择和质量设置
• 服务端集成模式
• 数据库存储策略

事件处理

📄 阅读： references/signature-events.md

• 用于跟踪笔画的 Changed 事件
• 用于保存操作的 OnSave 事件
• 用于初始化的 Created 事件
• 事件参数结构
• 实时签名验证
• 检测空白和已填写的签名
• 事件驱动工作流

自定义和样式设置

📄 阅读： references/signature-customization.md

• Disabled 和 IsReadOnly 状态
• 用于自定义样式的 HtmlAttributes
• 画布大小自定义
• 主题集成
• 移动设备和触控设备优化
• 无障碍访问注意事项
• 响应式设计模式

快速入门示例

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

常见模式

模式 1：基本签名捕获

• 使用默认笔画设置，营造自然的手写体验
• 设置 BackgroundColor="#FFFFFF" 以获得清晰的画布
• 提供“清除”按钮，供用户修正
• 保存为 PNG，以确保通用兼容性
• 提交前验证签名不为空

模式 2：使用信笺抬头签署文档

• 使用 BackgroundImage 设置公司信笺抬头或表单模板
• 设置 SaveWithBackground="true"，将背景包含在保存的文件中
• 配置 StrokeColor，使其与背景形成对比
• 保存为嵌入背景的 PNG 或 JPEG 文件
• 适用于合同、协议和官方文件

模式 3：针对移动设备优化的签名

• 加宽笔画，让触控签名更清晰
• 使用更大的画布，方便用拇指绘制
• 仅在签名模式激活时设置 IsReadOnly="false"
• 签名完成后自动保存
• 为触控交互提供清晰的视觉反馈

模式 4：多签名表单

• 使用多个 SfSignature 组件供不同签署人签名
• 跟踪每个签名字段的完成状态
• 为每个签名使用唯一标识符保存
• 在生成最终文档时合并签名
• 提交表单前验证所有必需的签名

关键属性

属性	默认值	使用场景
MinStrokeWidth	0.5	设置笔画的最小粗细
MaxStrokeWidth	2.0	设置笔画的最大粗细
StrokeColor	"#000000"	更改墨迹颜色
BackgroundColor	"#FFFFFF"	设置画布背景颜色
BackgroundImage	null	添加信笺抬头或水印图片
Velocity	0.7	控制笔画平滑度（0-1）
SaveWithBackground	true	将背景包含在保存的签名中
Disabled	false	完全禁用签名捕获
IsReadOnly	false	显示现有签名时禁止更改
EnablePersistence	false	在页面重新加载后保留签名
HtmlAttributes	null	为包装器添加自定义 HTML 属性

常见用例

1. 电子签名采集：数字文档签署、合同审批、同意书
2. 金融服务：贷款申请、开户、交易授权
3. 医疗保健：患者同意书、HIPAA 协议、医疗记录
4. 法律文档：合同、保密协议、法律协议、法院文件
5. 人力资源流程：雇佣合同、入职文档、政策确认
6. 交付确认：包裹签收、服务完成确认
7. 签到系统：访客日志、考勤跟踪、登记表
8. 教育：考试监考、表单提交、家长同意书

快速决策树

用户需要采集签名 ├─ 基本签名？ │ └─ 使用默认设置 + 保存为 PNG ├─ 带信笺抬头的文档？ │ ├─ 设置 BackgroundImage 属性 │ └─ 启用 SaveWithBackground="true" ├─ 主要面向移动设备或触控操作？ │ ├─ 将 MaxStrokeWidth 增大到 3.0 或更高 │ └─ 使用更大的画布尺寸 ├─ 多位签署人？ │ ├─ 使用多个 SfSignature 组件 │ ├─ 分别跟踪每个签名的状态 │ └─ 使用唯一标识符保存 └─ 需要特定格式？ ├─ PNG → 通用支持，支持透明背景 ├─ JPEG → 文件更小，不支持透明背景 └─ SVG → 矢量格式，可缩放

---

RangeSlider

了解如何在 Blazor 应用中实现 Syncfusion Blazor Range Slider 组件，通过双滑块选择范围，并使用刻度、工具提示、颜色范围和移动限制；还可即时获取双值选择，用于价格筛选、日期范围、温度区间，或任何需要范围输入并提供视觉反馈和验证的场景。

文档

入门指南

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

• 安装和 NuGet 包设置
• 使用 Type="SliderType.Range" 配置基本的 SfSlider
• 使用数组为双滑块绑定值
• CSS 导入和主题配置
• 命名空间导入和服务注册
• 包含范围选择的最简可运行示例

范围配置

📄 阅读： references/rangeslider-range-configuration.md

• 用于设置范围边界的 Min、Max 和 Step 属性
• Type 属性（SliderType.Range 与 Default）
• 使用数组进行双向值绑定（@bind-Value）
• 使用 CustomValues 设置自定义非数值
• IsImmediateValue 用于实时更新
• 值数组的结构和数据类型

刻度和工具提示

📄 阅读： references/rangeslider-ticks-and-tooltip.md

• SliderTicks 组件配置
• 使用 LargeStep 和 SmallStep 设置间隔标记
• 刻度位置选项（Before、After、Both）
• ShowSmallTicks 属性用于显示细分刻度
• Format 属性用于自定义刻度标签
• SliderTooltip 组件设置
• 工具提示显示模式（Focus、Hover、Always、Auto）
• 工具提示位置和格式自定义
• 自定义工具提示模板

颜色范围和视觉指示

📄 阅读： references/rangeslider-color-ranges-visual.md

• SliderColorRanges 用于提供视觉反馈
• 使用 Start、End、Color 配置 ColorRange 组件
• 为不同的数值区域设置多个颜色段
• 使用场景（温度区域、价格区间、评分）
• 颜色自定义和样式设置
• 颜色选择的无障碍性考量

限制和约束

📄 阅读： references/rangeslider-limits-and-constraints.md

• 使用 SliderLimits 配置移动限制
• MinStart、MinEnd、MaxStart、MaxEnd 属性
• Enabled 属性用于启用限制
• StartHandleFixed 和 EndHandleFixed 用于锁定滑块手柄
• 将手柄移动限制在边界内
• 使用场景（预订日期范围、预算限制）
• 使用限制进行验证的模式

方向和自定义

📄 阅读： references/rangeslider-orientation-and-customization.md

• Orientation 属性（Horizontal 与 Vertical）
• ShowButtons 用于显示增减控件
• Width 属性用于响应式尺寸调整
• EnableAnimation 用于实现平滑过渡
• CssClass 用于自定义样式
• EnableRtl 用于支持从右向左书写的语言
• ReadOnly 和 Enabled 状态
• 使用 Theme Studio 自定义主题

事件和数据绑定

📄 阅读： references/rangeslider-events-and-binding.md

• SliderEvents 组件配置
• 使用 ValueChange 事件回调处理范围更新
• OnChange 与 Changed 事件的触发时机
• Created 事件用于初始化逻辑
• Rendered 事件用于渲染后的操作
• 使用 OnTooltipChange 动态设置工具提示内容
• 使用 OnTicksRender 自定义刻度标签的渲染
• 与 EditForm 集成
• 使用 EditContext 和数据注释进行验证

快速入门示例

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

常见模式

模式 1：基本范围选择

• 设置 Type="SliderType.Range" 以启用双手柄
• 将值绑定到包含两个元素的 int[] 或 double[] 数组
• 配置 Min、Max 和 Step 属性
• 使用 IsVisible="true" 启用工具提示，为用户提供反馈
• 使用 ValueChange 事件捕获范围更新

模式 2：带有视觉颜色区域的范围

• 添加 SliderColorRanges 组件
• 定义多个 ColorRange 段（例如，冷／暖／热）
• 设置能够清晰区分的颜色
• 用于温度、评分或风险指示器
• 结合刻度以便精确识别数值

模式 3：受约束的范围选择

• 使用 SliderLimits 限制手柄移动
• 设置 MinStart／MaxStart 以指定第一个手柄的边界
• 设置 MinEnd／MaxEnd 以指定第二个手柄的边界
• 如果需要锁定某个手柄，则启用 StartHandleFixed 或 EndHandleFixed
• 适用于预订系统、预算规划和日程安排

模式 4：自定义值范围选择

• 使用 CustomValues 数组表示非数值范围
• 示例：string[] { "XS", "S", "M", "L", "XL", "XXL" }
• 值数组使用索引，而非实际值
• 通过刻度格式设置显示自定义标签
• 非常适合尺码选择、优先级级别和技能评分

关键属性

属性	默认值	使用场景
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	启用／禁用整个组件

常见使用场景

1. 电子商务价格筛选：选择最低／最高价格、按预算范围筛选
2. 日期范围选择器：入住／退房日期、活动时长、日程安排
3. 温度控制：HVAC 系统、烤箱设置、气候分区
4. 年龄范围选择：人口统计、目标受众、年龄限制
5. 时间范围选择：工作时间、可用时段、时间窗口
6. 分数／评分范围：按成绩筛选、绩效指标、评论评分
7. 财务规划：预算分配、投资范围、支出限额
8. 资源分配：CPU／内存限制、带宽限制、容量规划

快速决策树

用户需要选择范围（两个值） ├─ 数值范围？ │ ├─ 设置 Type="SliderType.Range" │ ├─ Value 使用 int[] 或 double[] │ └─ 配置 Min、Max、Step ├─ 非数值（尺码、标签）？ │ ├─ 设置 CustomValues 数组 │ ├─ Value 数组包含索引 │ └─ 使用刻度格式设置标签 ├─ 需要可视化分区？ │ ├─ 添加 SliderColorRanges 组件 │ └─ 定义多个 ColorRange 区段 ├─ 限制移动？ │ ├─ 使用 SliderLimits 组件 │ ├─ 设置 MinStart/MaxStart/MinEnd/MaxEnd │ └─ 如有需要，启用 StartHandleFixed 或 EndHandleFixed ├─ 需要垂直布局？ │ └─ 设置 Orientation="SliderOrientation.Vertical" └─ 需要在拖动期间实时更新？ └─ 设置 IsImmediateValue="true"

---

OtpInput

了解如何实现 Syncfusion Blazor OtpInput（一次性密码）组件，以安全输入验证码；该组件支持配置长度、输入类型（数字、文本、密码）、样式模式（轮廓、下划线、填充）、自动焦点管理和全面的事件处理。非常适用于双重身份验证、电子邮件验证、短信验证码、PIN 输入，以及任何需要安全输入多位代码并支持键盘导航和无障碍功能的场景。

文档

入门

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

• 安装和 NuGet 包配置
• 基本的 SfOtpInput 组件设置
• 命名空间导入和服务注册
• CSS 主题配置
• 用于设置 OTP 位数的 Length 属性
• 值绑定和获取
• 最小可运行示例

配置选项

📄 阅读： references/otpinput-configuration.md

• 用于设置位数的 Length 属性（默认值：4）
• Type 属性（Number、Text、Password）
• 空输入框的占位符配置
• 用于视觉分组的分隔符
• 用于立即输入的 AutoFocus
• 禁用状态管理
• ID 和 HtmlAttributes 自定义

样式模式

📄 阅读： references/otpinput-styling-modes.md

• StylingMode 选项（Outlined、Underlined、Filled）
• TextTransform（None、Lowercase、Uppercase）
• 使用 CssClass 自定义样式
• 使用 Theme Studio 自定义主题
• 响应式设计模式
• 视觉状态和焦点指示器

事件和数据绑定

📄 阅读： references/otpinput-events-binding.md

• Value 属性和双向绑定（@bind-Value）
• ValueChanged 事件回调（仅使用 Value 属性，不要使用 @bind-Value）
• 搭配 OtpInputEventArgs 使用 OnInput 事件
• OnFocus 和 OnBlur 事件
• Created 生命周期事件
• 集成表单验证
• 实时验证模式
• 完成后自动提交

无障碍访问

📄 阅读： references/otpinput-accessibility.md

• 使用 AriaLabels 数组设置各个输入框的标签
• 键盘导航（方向键、退格键、删除键）
• 屏幕阅读器支持
• 符合 WCAG 2.1 标准
• 焦点管理最佳实践
• 密码类型的无障碍访问注意事项
• 移动设备优化

快速入门示例

@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
        }
    }
}

常见模式

模式 1：基本 OTP 验证（6 位数字）

• 设置 Length="6"，使用标准 OTP 长度
• 使用 Type="OtpInputType.Number"，仅允许输入数字
• 启用 AutoFocus="true"，立即开始输入
• 使用 @bind-Value 进行双向绑定（最简单的方式）
• 在服务端验证 OTP

模式 2：电子邮件／短信验证码

• 根据服务设置 Length="4" 或 Length="6"
• 使用 Type="OtpInputType.Number" 输入数字验证码
• 设置 StylingMode="OtpInputStyle.Underlined"，实现简洁外观
• 页面加载时自动聚焦第一个输入框
• 显示验证码过期倒计时
• 提供“重新发送验证码”功能

模式 3：安全 PIN 输入

• 使用 Type="OtpInputType.Password" 隐藏输入内容
• 设置 Length="4" 或 Length="6"，指定 PIN 长度
• 应用 StylingMode="OtpInputStyle.Filled"，实现现代外观
• 实施速率限制，增强安全性
• 输入错误时清除内容
• 显示验证结果的视觉反馈

模式 4：字母数字验证码（带分隔符）

• 设置 Type="OtpInputType.Text"，输入字母和数字
• 使用 TextTransform="TextTransform.Uppercase"，提高可读性
• 设置 Separator="-"，以视觉方式分组字符
• 示例：ABC-123-XYZ 格式
• 设置 Length="9"（包括分隔符位置）
• 适用于激活码、许可证密钥

主要属性

属性	默认值	使用场景
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 属性

常见用例

1. 双重身份验证（2FA）：登录安全、账户验证、多因素身份验证
2. 电子邮件验证：账户激活、电子邮件确认、新闻简报注册
3. 短信验证：电话号码验证、移动应用登录、交易确认
4. 密码重置：安全找回密码、恢复账户访问权限
5. 交易验证：银行交易、付款确认、资金转账
6. 访问控制：建筑物入口代码、安全区域访问、临时访问代码
7. 设备配对：蓝牙配对代码、智能设备设置、物联网设备连接
8. 激活码：软件许可证、产品激活、订阅验证

快速决策树

用户需要输入 OTP/验证码 ├─ 仅限数字？ │ ├─ 设置 Type="OtpInputType.Number" │ └─ 使用 Length="4" 或 Length="6" ├─ 需要隐藏输入内容（PIN）？ │ ├─ 设置 Type="OtpInputType.Password" │ └─ 遵循安全最佳实践 ├─ 字母数字代码？ │ ├─ 设置 Type="OtpInputType.Text" │ ├─ 使用 TextTransform="TextTransform.Uppercase" │ └─ 考虑使用 Separator 提高可读性 ├─ 完成后自动提交？ │ ├─ 监听 ValueChanged 事件 │ ├─ 检查 value.Length == Length │ └─ 自动调用验证 API ├─ 需要自定义样式？ │ ├─ 轮廓样式 → StylingMode="OtpInputStyle.Outlined"（默认） │ ├─ 下划线样式 → StylingMode="OtpInputStyle.Underlined" │ └─ 填充样式 → StylingMode="OtpInputStyle.Filled" └─ 无障碍功能很重要？ ├─ 设置 AriaLabels 数组，供屏幕阅读器使用 └─ 启用 AutoFocus，方便键盘用户操作

---

评分

了解如何实现 Syncfusion Blazor Rating 组件，以直观地收集评分和反馈。该组件支持可配置的精度模式（整星、半星、四分之一星、精确值）、自定义图标和模板、标签和工具提示，以及全面的事件处理和无障碍功能。适用于商品评价、技能评估、满意度调查、质量评分，以及任何需要通过星级或自定义图标收集用户反馈并支持键盘导航和表单集成的场景。

文档

快速入门

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

• 安装和 NuGet 包设置
• SfRating 组件基本设置
• 命名空间导入和服务注册
• CSS 主题配置
• 用于设置评分范围的 ItemsCount 属性
• 值绑定和获取
• 最简可运行示例
• 基本的 5 星评分实现

精度和值

📄 阅读： references/rating-precision-and-values.md

• Precision 属性（Full、Half、Quarter、Exact）
• Full 精度：仅支持整数
• Half 精度：以 0.5 为增量
• Quarter 精度：以 0.25 为增量
• Exact 精度：支持小数值
• 用于设置最低评分值的 Min 属性
• 用于清除评分的 AllowReset
• 用于单项模式的 EnableSingleSelection
• 值的计算和显示

标签和工具提示

📄 阅读： references/rating-labels-and-tooltips.md

• 用于显示标签的 ShowLabel 属性
• LabelPosition（Top、Bottom、Left、Right）
• 用于自定义标签格式的 LabelTemplate
• 用于显示悬停工具提示的 ShowTooltip 属性
• 用于自定义工具提示内容的 TooltipTemplate
• 根据值动态更新标签
• 上下文反馈模式

模板和自定义

📄 阅读： references/rating-templates-customization.md

• 用于未选中项的 EmptyTemplate
• 用于已选中项的 FullTemplate
• 用于模板数据的 RatingItemContext
• 自定义图标实现（爱心、点赞、表情符号）
• SVG 和图标字体集成
• 用于自定义样式的 CssClass
• EnableAnimation 属性
• 主题自定义和响应式设计

事件和状态

📄 阅读： references/rating-events-and-states.md

• 用于评分更新的 ValueChanged 事件
• 携带 RatingHoverEventArgs 的 OnItemHover 事件
• Created 生命周期事件
• 表单验证集成
• 用于仅显示评分的 ReadOnly 状态
• Disabled 状态管理
• Visible 属性控制
• 键盘导航支持
• 无障碍功能和 ARIA 属性

快速入门示例

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

常见模式

模式 1：基本的 5 星商品评分

• 使用默认的 ItemsCount="5" 进行标准评分
• 设置 Precision="PrecisionType.Full"，仅使用整星
• 启用 @bind-Value 进行双向数据绑定
• 设置 ShowLabel="true" 显示评分值
• 使用 LabelPosition="LabelPosition.Right" 设置标签位置
• 使用 ValueChanged 事件自动提交

模式 2：带悬停反馈的半星评分

• 设置 Precision="PrecisionType.Half"，以 0.5 为增量
• 启用 ShowTooltip="true" 提供悬停反馈
• 使用 OnItemHover 事件进行预览
• 设置 ReadOnly="true" 显示平均评分
• 在自定义标签模板中显示评分数量
• 实时显示反馈消息

模式 3：自定义图标模板（爱心、点赞、表情符号）

• 为未选中状态定义 EmptyTemplate
• 为选中状态定义 FullTemplate
• 使用 RatingItemContext 针对具体项目进行渲染
• 实现自定义图标（♥、👍、😊 等）
• 使用 CssClass 设置自定义颜色和大小
• 启用 EnableAnimation="true" 实现平滑过渡

模式 4：多类别评分表单

• 创建多个 SfRating 组件
• 根据需要为不同类别设置不同的 ItemsCount
• 与 EditForm 结合使用以进行验证
• 计算总体平均评分
• 使用事件处理程序跟踪完成情况
• 仅在所有评分均已完成时启用提交

关键属性

属性	默认值	使用场景
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 类

常见用例

1. 产品评论：电商评分、市场反馈、客户评论、产品质量评估
2. 服务质量：餐厅评分、酒店评论、配送服务反馈、支持满意度
3. 技能评估：员工评估、能力评分、培训反馈、熟练程度
4. 内容评分：文章反馈、视频评分、课程评论、文档实用性
5. 用户体验：应用商店评分、功能满意度、易用性评分、NPS 调查
6. 绩效评估：团队成员评估、项目评分、目标达成情况、KPI 跟踪
7. 调查回复：满意度调查、民意调查、反馈表、问卷
8. 质量控制：检查评分、合规评分、审计结果、质量指标
9. 娱乐：电影评分、音乐评论、书籍评分、游戏分数
10. 情感分析：客户情绪、品牌认知、情绪跟踪、情感反馈

快速决策树

用户需要评分/反馈功能 ├─ 显示现有评分（只读）？ │ ├─ 设置 ReadOnly="true" │ ├─ 平均评分使用 Precision="PrecisionType.Exact" │ └─ 显示 ShowLabel="true" 和评论数 ├─ 收集用户的新评分？ │ ├─ 仅整颗星？→ Precision="PrecisionType.Full" │ ├─ 半颗星？→ Precision="PrecisionType.Half" │ ├─ 四分之一颗星？→ Precision="PrecisionType.Quarter" │ └─ 任意小数？→ Precision="PrecisionType.Exact" ├─ 自定义评分等级？ │ ├─ 3 分制 → ItemsCount="3" │ ├─ 7 分制 → ItemsCount="7" │ └─ 10 分制 → ItemsCount="10" ├─ 需要使用自定义图标而非星星？ │ ├─ 爱心 → 在 EmptyTemplate 和 FullTemplate 中定义 ♥ │ ├─ 点赞图标 → 使用 👍/👎 图标 │ ├─ 表情符号 → 使用 😞😐🙂😊🤩 递进序列 │ └─ 自定义 SVG → 在模板中渲染 SVG ├─ 仅需点赞/点踩？ │ ├─ 设置 EnableSingleSelection="true" │ ├─ 使用 ItemsCount="1" 或 ItemsCount="2" │ └─ 使用带有点赞图标的自定义模板 ├─ 需要与表单集成？ │ ├─ 在 <EditForm> 中使用 │ ├─ 添加验证属性 │ └─ 监听 ValueChanged 进行验证 ├─ 显示评分反馈？ │ ├─ 启用 ShowLabel="true" 以显示数值 │ ├─ 使用 LabelTemplate 显示自定义消息 │ ├─ 启用 ShowTooltip="true" 以显示悬停反馈 │ └─ 使用 TooltipTemplate 显示上下文相关消息 └─ 有无障碍要求？ ├─ 确保键盘导航正常（方向键） ├─ 测试屏幕阅读器兼容性 └─ 提供清晰的 ARIA 标签

---

InputMask

了解如何实现 Syncfusion Blazor InputMask（MaskedTextBox）组件，以便使用预定义模式、自定义掩码规则和提示字符输入格式化文本；并在 Blazor 应用中即时获取经过掩码处理的输入，适用于电话号码、SSN、信用卡、日期、邮政编码、车牌号，以及任何需要结构化文本输入、格式验证、保留字面字符和全面事件处理的场景。

文档

入门

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

• 安装和 NuGet 包设置
• 基本的 SfMaskedTextBox 组件设置
• 命名空间导入和服务注册
• CSS 主题配置
• 简单掩码示例（电话、日期、SSN）
• 值绑定基础
• 最小可运行示例

掩码模式和配置

📄 阅读： references/inputmask-mask-patterns.md

• 标准掩码字符（0、9、L、?、A、&、C、#）
• 预定义模式（电话、SSN、ZIP、日期、时间）
• 掩码属性配置
• 掩码中的字面字符
• 可选与必填位置
• 复杂模式示例
• 国际格式模式
• 模式验证规则

自定义字符和格式

📄 阅读： references/inputmask-custom-characters.md

• CustomCharacters 字典的用法
• 创建自定义掩码规则
• 基于正则表达式的字符验证
• 高级模式自定义
• 使用场景（车牌号、产品代码等）
• 将自定义掩码与标准掩码结合使用
• 自定义规则的最佳实践

提示字符配置

📄 阅读： references/inputmask-prompt-configuration.md

• PromptChar 属性（默认值：_）
• 用于显示的 PromptPlaceholder
• 用于包含值的 EnableLiterals
• Placeholder 与 PromptChar 的区别
• 视觉反馈配置
• 用户体验注意事项
• 不同配置的示例

事件和数据绑定

📄 阅读： references/inputmask-events-binding.md

• Value 属性和 @bind-Value
• ValueChange 事件（MaskChangeEventArgs）
• ValueChanged 事件回调
• Focus 和 Blur 事件（MaskFocusEventArgs、MaskBlurEventArgs）
• OnChange、OnInput 与 ValueChange 的触发时机
• 与 EditContext 集成的 EditForm
• 用于验证的 ValueExpression
• 实时验证模式
• 事件处理程序最佳实践

样式和无障碍

📄 阅读： references/inputmask-styling-accessibility.md

• FloatLabelType 配置
• ShowClearButton 功能
• 用于自定义样式的 CssClass
• 宽度和响应式尺寸
• Enabled 与 Readonly 状态
• 使用 Theme Studio 自定义主题
• 符合 WCAG 2.1 标准
• 键盘导航
• ARIA 属性
• 屏幕阅读器支持
• RTL（EnableRtl）支持
• HtmlAttributes 和 InputAttributes
• 无障碍最佳实践

快速入门示例

@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 = "";
}

常见模式

模式 1：电话号码输入（美国格式）

• 使用掩码 "(000) 000-0000" 输入美国电话号码
• 设置 PromptChar="_"，提供清晰的视觉反馈
• 启用 @bind-Value 实现双向绑定
• 使用 FloatLabelType.Auto 获得现代化的用户体验
• 配置 Placeholder 为用户提供指引
• 设置 EnableLiterals="false"，将括号和连字符排除在值之外

模式 2：社会安全号码（SSN）

• 使用掩码 "000-00-0000" 设置 SSN 格式
• 设置 PromptChar="#" 或 PromptChar="*"，保护隐私
• 输入时应用 Readonly="false"，显示时应用 Readonly="true"
• 使用 ShowClearButton="true" 快速重置
• 使用 ValueChange 事件实现验证
• 考虑对显示值进行掩码处理以确保安全

模式 3：带分隔符的信用卡号

• 使用掩码 "0000 0000 0000 0000" 输入 16 位卡号
• 设置 EnableLiterals="false"，仅获取数字
• 监听 ValueChange，检测卡片类型（Visa、MC、Amex）
• 根据卡号前几位显示卡片品牌图标
• 实时应用 Luhn 算法验证
• 使用 PromptChar="X" 清晰标示空位

模式 4：自定义格式的日期输入

• 使用掩码 "00/00/0000" 设置 MM/DD/YYYY 格式
• 或使用 "00-00-0000" 设置 DD-MM-YYYY 格式
• 设置 Placeholder="MM/DD/YYYY"，提示日期格式
• 实现自定义验证，确保日期有效
• 使用 ValueChange 验证日/月范围
• 对于复杂的日期选择，可考虑使用 DatePicker 组件

模式 5：自定义产品代码格式

• 为特殊规则定义 CustomCharacters 字典
• 示例：@(new Dictionary<string, string> { { "P", "[A-Z]" }, { "N", "[0-9]" } })
• 使用类似 "PPP-NNN-NNN" 的掩码，设置 ABC-123-456 格式
• 结合使用标准字符和自定义字符
• 使用 TextTransform 转换为大写
• 在事件中根据业务规则验证

模式 6：使用自定义字符的国际电话号码

• 使用 CustomCharacters 设置特定国家/地区的模式
• 示例："+00 (000) 000-0000"，包含国家代码
• 设置 EnableLiterals="true"，包含 + 号和格式字符
• 根据代码显示国家/地区旗帜
• 实现按国家/地区动态切换掩码
• 支持多种国际格式

主要属性

属性	默认值	使用场景
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 导航顺序

常见用例

1. 联系信息：电话号码、传真号码、手机号码及国家/地区代码
2. 个人身份信息：SSN、纳税人识别号、国家身份证号、护照号码、驾照号码
3. 财务数据：信用卡号、银行账号、路由号码、CVV 码
4. 日期和时间：自定义日期格式、时间输入、采用特定模式的日期范围
5. 邮政编码：ZIP 码（美国）、邮政编码（国际）、带格式的区号
6. 产品标识：SKU 编号、序列号、产品代码、条形码输入
7. 许可证号码：车牌号、软件许可证号、采用特定模式的注册号
8. 网络信息：IP 地址、MAC 地址、采用点分表示法的子网掩码
9. 版本号：软件版本（1.2.3）、采用自定义格式的构建编号
10. 自定义代码：优惠券码、促销码、采用特定模式的跟踪号码

快速决策树

用户需要按模式输入格式化文本 ├─ 标准格式？ │ ├─ 美国电话号码 → Mask="(000) 000-0000" │ ├─ 社会安全号码（SSN）→ Mask="000-00-0000" │ ├─ 邮政编码 → Mask="00000" 或 Mask="00000-0000" │ ├─ 信用卡号 → Mask="0000 0000 0000 0000" │ ├─ 日期 → Mask="00/00/0000"（MM/DD/YYYY） │ └─ 时间 → Mask="00:00"（HH:MM） ├─ 需要值中仅包含数字？ │ ├─ 设置 EnableLiterals="false" │ └─ 掩码中的字面字符将从 Value 中排除 ├─ 在值中包含格式字符？ │ ├─ 设置 EnableLiterals="true"（默认） │ └─ Value 将包含括号、连字符等 ├─ 自定义模式（非标准）？ │ ├─ 使用 CustomCharacters 字典 │ ├─ 为每个自定义字符定义正则表达式 │ ├─ 示例：{ "P", "[A-Z]" } 表示大写字母 │ └─ 在掩码中组合："PPP-000-NNN" ├─ 有隐私/安全方面的顾虑？ │ ├─ 设置 PromptChar="*" 或 PromptChar="#" │ ├─ 对仅用于显示的掩码数据使用 Readonly="true" │ └─ 如有需要，在显示时实施额外的掩码处理 ├─ 需要支持国际格式？ │ ├─ 使用 CustomCharacters 实现灵活模式 │ ├─ 根据区域设置实施动态掩码切换 │ └─ 考虑选择国家/地区 ├─ 需要表单验证？ │ ├─ 在 <EditForm> 中结合模型绑定使用 │ ├─ 添加 ValueExpression 以进行验证 │ ├─ 应用数据注释（[Required]、[StringLength]） │ ├─ 监听 ValueChange 以进行实时验证 │ └─ 实施自定义验证逻辑（Luhn、日期范围） ├─ 需要改善用户体验？ │ ├─ 设置 FloatLabelType="FloatLabelType.Auto" │ ├─ 启用 ShowClearButton="true" 以便快速重置 │ ├─ 使用有意义的 Placeholder 文本 │ └─ 提供验证的视觉反馈 └─ 无障碍功能是否重要？ ├─ 确保键盘导航正常工作 ├─ 通过 HtmlAttributes 设置适当的 ARIA 标签 ├─ 测试屏幕阅读器兼容性 └─ 在标签/占位符中提供清晰的格式说明

---

ColorPicker

了解如何实现 Syncfusion Blazor ColorPicker 组件，通过拾色器和调色板模式、不透明度控制、预设颜色集、内联或弹出式显示、模式切换，以及即时颜色输入，实现直观的颜色选择。适用于主题、UI 自定义、设计工具、数据可视化、品牌塑造，或任何需要选择十六进制/RGBA 值颜色、跟踪最近使用的颜色并在 Blazor 应用程序中进行全面事件处理的场景。

文档

入门

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

• 安装和 NuGet 包设置
• 基本 SfColorPicker 组件设置
• 命名空间导入和服务注册
• CSS 主题配置
• 绑定颜色格式的值
• 模式概述（Picker 与 Palette）
• 最小可运行示例

模式和配置

📄 阅读： references/colorpicker-modes-configuration.md

• ColorPickerMode（Picker 与 Palette）
• 使用 Picker 模式选择渐变颜色
• 使用 Palette 模式显示预定义颜色网格
• 内联与弹出式显示选项
• 用于让用户选择模式的 ModeSwitcher
• 用于调色板布局的 Columns 配置
• 用于应用/取消操作的 ShowButtons
• 特定模式的行为和用例

预设颜色和调色板

📄 阅读： references/colorpicker-presets-colors.md

• PresetColors 字典配置
• 自定义调色板分组
• 默认预设颜色集
• ShowRecentColors 功能
• 用于表示“无选择”的 NoColor 选项
• 组织预设类别
• 商业和设计用例

不透明度和值格式

📄 阅读：references/colorpicker-opacity-values.md

• 使用 EnableOpacity 控制 alpha 通道
• 不透明度滑块配置
• 值格式（hex、rgba、hsva）
• 读取和设置不透明度值
• 透明颜色处理
• 使用场景（叠加层、高亮、透明度）

事件和数据绑定

📄 阅读：references/colorpicker-events-binding.md

• Value 属性和双向绑定（@bind-Value）
• ValueChanged 事件回调
• 携带 ColorPickerEventArgs 的 Selected 事件
• 用于弹出窗口控制的 OnOpen 和 OnClose 事件
• ModeSwitched 事件处理
• 用于自定义调色板色块的 OnTileRender
• 与 EditForm 集成
• 实时颜色预览模式

自定义和无障碍访问

📄 阅读：references/colorpicker-customization-accessibility.md

• ShowButtons 配置
• 使用 CssClass 自定义样式
• Disabled 和 EnableRtl 状态
• 自定义 HtmlAttributes
• 键盘导航支持
• 无障碍访问的 ARIA 属性
• 符合 WCAG 2.1 标准
• 使用 Theme Studio 自定义主题
• 响应式设计模式

快速入门示例

@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";
}

常见模式

模式 1：基础调色板颜色选择器

• 使用 Mode="ColorPickerMode.Palette" 显示预定义颜色网格
• 启用 @bind-Value 进行双向绑定
• 设置 ShowButtons="true" 以显示应用/取消操作
• 使用默认 PresetColors 或进行自定义
• 绑定到字符串变量以存储 hex 值
• 使用所选颜色显示预览

模式 2：带不透明度的高级渐变选择器

• 设置 Mode="ColorPickerMode.Picker" 以使用渐变选择器
• 启用 EnableOpacity="true" 以控制 alpha 通道
• 使用 ModeSwitcher="true" 允许切换模式
• 显示 rgba 值以表示透明度
• 适用于设计工具、图形编辑器
• 显示带不透明度的实时预览

模式 3：内嵌颜色选择器（无弹出窗口）

• 设置 Inline="true"，始终显示选择器
• 用于颜色自定义面板
• 无弹出窗口触发器，立即显示
• 适用于 Picker 和 Palette 模式
• 与 ShowButtons="false" 结合，实现即时选择
• 非常适合设置面板、主题构建器

模式 4：自定义预设调色板

• 使用自定义分组定义 PresetColors 字典
• 按类别整理（品牌色、柔和色等）
• 设置 Columns 属性以配置网格布局
• 使用 ShowRecentColors="true" 显示历史记录
• 启用 NoColor="true"，提供“不选择颜色”选项
• 适用于品牌配色系统、设计系统

关键属性

属性	默认值	使用场景
Value	""	绑定所选颜色（hex、rgba、hsva）
Mode	ColorPickerMode.Picker	选择 Picker（渐变）或 Palette（网格）
Inline	false	内嵌显示选择器，而非使用弹出窗口
ModeSwitcher	false	允许用户在 Picker 和 Palette 之间切换
EnableOpacity	false	启用 alpha 通道/透明度控制
ShowButtons	false	显示应用和取消按钮（弹出窗口模式）
ShowRecentColors	true	显示最近选择的颜色
PresetColors	null	自定义预设调色板字典
Columns	10	调色板模式下的列数
NoColor	false	允许选择“不使用颜色”
Disabled	false	禁用颜色选择
EnableRtl	false	启用从右到左的布局
CssClass	""	应用自定义 CSS 类
HtmlAttributes	null	添加自定义 HTML 属性

常见用例

1. UI 主题自定义：用户可选主题、配色方案构建器、个性化设置
2. 设计工具：图形编辑器、绘图应用、图像批注、标记工具
3. 数据可视化：图表颜色选择、图形自定义、报告样式设置
4. 品牌塑造：Logo 颜色、品牌形象、风格指南实施、企业配色
5. Web 设计：CSS 颜色选择、背景颜色、文本颜色、边框颜色
6. 产品自定义：产品颜色变体、定制商品、个性化设置
7. 高亮工具：文本荧光笔、批注颜色、强调标记
8. 仪表板自定义：小组件颜色、状态指示器、类别颜色
9. 表单构建器：自定义表单样式、输入颜色、验证颜色
10. 日历／日程安排：事件颜色、类别编码、优先级指示器

快速决策树

用户需要颜色选择功能 ├─ 仅使用特定的预定义颜色？ │ ├─ 使用 Mode="ColorPickerMode.Palette" │ ├─ 设置 PresetColors 以使用自定义调色板 │ └─ 配置 Columns 以设置网格布局 ├─ 可选择渐变中的任意颜色？ │ ├─ 使用 Mode="ColorPickerMode.Picker"（默认） │ └─ 用户可从完整色谱中选择 ├─ 允许使用这两种模式？ │ ├─ 启用 ModeSwitcher="true" │ └─ 用户可在 Picker 和 Palette 之间切换 ├─ 需要透明度／不透明度？ │ ├─ 设置 EnableOpacity="true" │ ├─ 值将包含 alpha（rgba 格式） │ └─ 显示不透明度滑块，供用户控制 ├─ 始终可见（无弹出窗口）？ │ ├─ 设置 Inline="true" │ ├─ 用于设置面板、侧边栏 │ └─ 可考虑设置 ShowButtons="false"，以便立即选择 ├─ 弹出窗口中需要确认？ │ ├─ 使用 Inline="false"（默认） │ ├─ 设置 ShowButtons="true" 以显示 Apply/Cancel │ └─ 监听 Selected 事件以获取确认后的选择 ├─ 需要跟踪最近使用的颜色？ │ ├─ 启用 ShowRecentColors="true"（默认） │ └─ 最近使用的颜色会自动显示 ├─ 允许选择“无颜色”？ │ ├─ 设置 NoColor="true" │ └─ 用户可清除颜色选择 ├─ 需要自定义调色板？ │ ├─ 定义 PresetColors 字典 │ ├─ 按类别对颜色分组 │ └─ 示例：{ "Basic": ["#fff", "#000"], "Brand": ["#e74c3c", "#3498db"] } ├─ 需要与表单集成？ │ ├─ 在 <EditForm> 中使用 │ ├─ 应用验证属性 │ └─ 监听 ValueChanged 以进行验证 └─ 无障碍功能很重要？ ├─ 确保键盘导航正常（Tab、Enter、Escape） ├─ 测试屏幕阅读器兼容性 └─ 通过 HtmlAttributes 提供清晰的标签