syncfusion-blazor-chat-ui
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSyncfusion Blazor Chat UI
Syncfusion Blazor Chat UI 组件
Build feature-rich conversational chat interfaces with the Syncfusion Blazor Chat UI component. This skill provides complete guidance for creating multi-user messaging applications, chat panels, and interactive conversation UIs in Blazor Server, WebAssembly, and Web App projects.
借助Syncfusion Blazor Chat UI组件构建功能丰富的对话式聊天界面。本技能提供完整指南,帮助你在Blazor Server、WebAssembly和Web App项目中创建多用户消息应用、聊天面板和交互式对话UI。
Component Overview
组件概述
The SfChatUI component is a specialized UI control for building conversational chat applications. It manages the complete chat interface including:
- Message Management: Collections of chat messages with full message lifecycle
- User Management: Multi-user support with profiles, avatars, and status
- Presence Features: Typing indicators, online status, user identification
- Rich Rendering: Templates for messages, timestamps, typing indicators, suggestions
- File Support: File attachment upload and integration
- Event System: Lifecycle events and user interaction callbacks
- Customization: Complete styling and theming control
SfChatUI组件是用于构建对话式聊天应用的专用UI控件。它管理完整的聊天界面,包括:
- 消息管理: 包含完整消息生命周期的聊天消息集合
- 用户管理: 支持多用户,包含用户资料、头像和状态
- Presence功能:输入指示器、在线状态、用户身份识别
- 丰富渲染: 消息、时间戳、输入指示器、建议的模板
- 文件支持: 文件附件上传与集成
- 事件系统: 生命周期事件和用户交互回调
- 自定义: 完整的样式和主题控制
Navigation Guide
导航指南
Getting Started
快速入门
📄 Read: references/getting-started.md
- Installation and NuGet package setup
- Basic component structure and initialization
- User and message configuration
- Minimal working example with conversation
📄 阅读: references/getting-started.md
- 安装和NuGet包配置
- 基础组件结构与初始化
- 用户和消息配置
- 包含对话的最小可用示例
Messages & Users Management
消息与用户管理
📄 Read: references/messages-and-users.md
- ChatMessage configuration and properties
- UserModel setup and properties
- Message text content management
- Author identification and user assignment
- Building message collections and conversation history
📄 阅读: references/messages-and-users.md
- ChatMessage配置与属性
- UserModel设置与属性
- 消息文本内容管理
- 作者识别与用户分配
- 构建消息集合与对话历史
User Profiles & Avatars
用户资料与头像
📄 Read: references/user-profiles-avatars.md
- Avatar URL configuration with images
- Avatar background color customization
- User status indicators (online, offline, busy, away)
- Custom CSS styling for users
- User identification and display names
📄 阅读: references/user-profiles-avatars.md
- 带图片的头像URL配置
- 头像背景颜色自定义
- 用户状态指示器(在线、离线、忙碌、离开)
- 用户自定义CSS样式
- 用户身份识别与显示名称
Typing Indicators
输入指示器
📄 Read: references/typing-indicators.md
- TypingUsers property configuration
- Showing/hiding typing status indicators
- Managing multiple typing users
- Dynamic typing status updates
- Typing indicator template customization
📄 阅读: references/typing-indicators.md
- TypingUsers属性配置
- 显示/隐藏输入状态指示器
- 管理多个正在输入的用户
- 动态输入状态更新
- 输入指示器模板自定义
Timestamps & Formatting
时间戳与格式化
📄 Read: references/timestamps-and-formatting.md
- ShowTimestamp property to enable/disable timestamps
- Message timestamp configuration
- TimestampFormat customization
- TimeBreak separators (Today, Yesterday, specific dates)
- TimeBreak template styling
📄 阅读: references/timestamps-and-formatting.md
- ShowTimestamp属性用于启用/禁用时间戳
- 消息时间戳配置
- TimestampFormat自定义
- TimeBreak分隔符(今天、昨天、特定日期)
- TimeBreak模板样式
Templates & Customization
模板与自定义
📄 Read: references/templates-and-customization.md
- EmptyChatTemplate for initial state display
- MessageTemplate for custom message rendering
- TimeBreakTemplate for date separators
- TypingUsersTemplate for typing display
- SuggestionTemplate for quick reply buttons
- CSS styling and theme integration
📄 阅读: references/templates-and-customization.md
- EmptyChatTemplate用于初始状态显示
- MessageTemplate用于自定义消息渲染
- TimeBreakTemplate用于日期分隔符
- TypingUsersTemplate用于输入状态显示
- SuggestionTemplate用于快速回复按钮
- CSS样式与主题集成
Attachments & Events
附件与事件
📄 Read: references/attachments-and-events.md
- File attachment configuration (Enable)
- SaveUrl and RemoveUrl endpoint setup
- AllowedFileTypes filtering
- MaxFileSize limits and constraints
- SaveFormat options (Blob vs Base64)
- Event handling: Created, MessageSend, UserTyping
- Attachment events: OnAttachmentUploadReady, UploadSuccess, UploadFailed
📄 阅读: references/attachments-and-events.md
- 文件附件配置(启用)
- SaveUrl和RemoveUrl端点设置
- AllowedFileTypes筛选
- MaxFileSize限制与约束
- SaveFormat选项(Blob vs Base64)
- 事件处理:Created、MessageSend、UserTyping
- 附件事件:OnAttachmentUploadReady、UploadSuccess、UploadFailed
Programmatic API & Methods 🆕
程序化API与方法 🆕
📄 Read: references/programmatic-api.md
- ScrollToBottomAsync() for navigating to latest messages
- ScrollToMessageAsync() for jumping to specific messages
- UpdateMessageAsync() for editing existing messages
- FocusAsync() for input field control
- Complete examples with error handling
📄 阅读: references/programmatic-api.md
- ScrollToBottomAsync()用于导航到最新消息
- ScrollToMessageAsync()用于跳转到特定消息
- UpdateMessageAsync()用于编辑现有消息
- FocusAsync()用于控制输入框焦点
- 包含错误处理的完整示例
Advanced Features 🆕
高级功能 🆕
📄 Read: references/advanced-features.md
- AutoScrollToBottom configuration
- EnableCompactMode for group chats
- Header and Footer customization
- Mention system (@mention) setup
- Quick reply suggestions
- LoadOnDemand for performance
- RTL (Right-to-Left) support
- Custom styling with CssClass
📄 阅读: references/advanced-features.md
- AutoScrollToBottom配置
- EnableCompactMode用于群聊
- 页眉和页脚自定义
- 提及系统(@mention)设置
- 快速回复建议
- LoadOnDemand提升性能
- RTL(从右到左)支持
- 使用CssClass自定义样式
Quick Start
快速开始
csharp
@using Syncfusion.Blazor.InteractiveChat
<div style="height: 500px; width: 600px;">
<SfChatUI ID="chatUser" User="CurrentUser" Messages="Messages"></SfChatUI>
</div>
@code {
private UserModel CurrentUser = new UserModel
{
ID = "user1",
User = "Albert",
AvatarBgColor = "#4a90e2"
};
private UserModel OtherUser = new UserModel
{
ID = "user2",
User = "Michale Suyama",
AvatarBgColor = "#7cb342"
};
private List<ChatMessage> Messages = new()
{
new ChatMessage
{
Text = "Hi, how are you?",
Author = new UserModel { ID = "user1", User = "Albert" }
},
new ChatMessage
{
Text = "I'm doing great! How about you?",
Author = new UserModel { ID = "user2", User = "Michale Suyama" }
}
};
}csharp
@using Syncfusion.Blazor.InteractiveChat
<div style="height: 500px; width: 600px;">
<SfChatUI ID="chatUser" User="CurrentUser" Messages="Messages"></SfChatUI>
</div>
@code {
private UserModel CurrentUser = new UserModel
{
ID = "user1",
User = "Albert",
AvatarBgColor = "#4a90e2"
};
private UserModel OtherUser = new UserModel
{
ID = "user2",
User = "Michale Suyama",
AvatarBgColor = "#7cb342"
};
private List<ChatMessage> Messages = new()
{
new ChatMessage
{
Text = "Hi, how are you?",
Author = new UserModel { ID = "user1", User = "Albert" }
},
new ChatMessage
{
Text = "I'm doing great! How about you?",
Author = new UserModel { ID = "user2", User = "Michale Suyama" }
}
};
}Common Patterns
常见模式
Pattern 1: Multi-User Conversation with Status
模式1:带状态的多用户对话
Display multiple users with online/offline status indicators:
csharp
<SfChatUI ID="chat" User="CurrentUser" Messages="Messages">
</SfChatUI>
@code {
private UserModel CurrentUser = new UserModel
{
ID = "user1",
User = "Albert",
StatusIconCss = "e-icons e-user-online"
};
private List<ChatMessage> Messages = new();
}显示带有在线/离线状态指示器的多个用户:
csharp
<SfChatUI ID="chat" User="CurrentUser" Messages="Messages">
</SfChatUI>
@code {
private UserModel CurrentUser = new UserModel
{
ID = "user1",
User = "Albert",
StatusIconCss = "e-icons e-user-online"
};
private List<ChatMessage> Messages = new();
}Pattern 2: Chat with Typing Indicators
模式2:带输入指示器的聊天
Show when users are typing:
csharp
<SfChatUI
ID="chat"
User="CurrentUser"
Messages="Messages"
TypingUsers="TypingUsers">
</SfChatUI>
@code {
private List<UserModel> TypingUsers = new();
private void UserStartTyping(UserModel user)
{
TypingUsers.Add(user);
StateHasChanged();
}
}显示用户正在输入的状态:
csharp
<SfChatUI
ID="chat"
User="CurrentUser"
Messages="Messages"
TypingUsers="TypingUsers">
</SfChatUI>
@code {
private List<UserModel> TypingUsers = new();
private void UserStartTyping(UserModel user)
{
TypingUsers.Add(user);
StateHasChanged();
}
}Pattern 3: Custom Message Templates
模式3:自定义消息模板
Personalize message appearance:
csharp
<SfChatUI ID="chat" User="CurrentUser" Messages="Messages">
<MessageTemplate>
<div class="custom-message">
<strong>@context.Message.Author.User</strong>
<p>@((MarkupString)context.Message.Text)</p>
</div>
</MessageTemplate>
</SfChatUI>个性化消息外观:
csharp
<SfChatUI ID="chat" User="CurrentUser" Messages="Messages">
<MessageTemplate>
<div class="custom-message">
<strong>@context.Message.Author.User</strong>
<p>@((MarkupString)context.Message.Text)</p>
</div>
</MessageTemplate>
</SfChatUI>Pattern 4: Chat with File Attachments
模式4:带文件附件的聊天
Enable users to share files:
csharp
<SfChatUI ID="chat" User="CurrentUser" Messages="Messages">
<ChatUIAttachment
Enable
SaveUrl="@SaveUrl"
RemoveUrl="@RemoveUrl"
AllowedFileTypes=".pdf,.docx,.jpg,.png">
</ChatUIAttachment>
</SfChatUI>
@code {
private string SaveUrl = "api/upload/save";
private string RemoveUrl = "api/upload/remove";
}允许用户分享文件:
csharp
<SfChatUI ID="chat" User="CurrentUser" Messages="Messages">
<ChatUIAttachment
Enable
SaveUrl="@SaveUrl"
RemoveUrl="@RemoveUrl"
AllowedFileTypes=".pdf,.docx,.jpg,.png">
</ChatUIAttachment>
</SfChatUI>
@code {
private string SaveUrl = "api/upload/save";
private string RemoveUrl = "api/upload/remove";
}Pattern 5: Auto-Scroll with Programmatic Control
模式5:带程序化控制的自动滚动
Automatically scroll to bottom and navigate to specific messages:
csharp
<SfChatUI
@ref="chatRef"
ID="chat"
User="CurrentUser"
Messages="Messages"
AutoScrollToBottom="true">
</SfChatUI>
<button @onclick="ScrollToBottom">Go to Latest</button>
<button @onclick="FocusInput">Focus Input</button>
@code {
private SfChatUI chatRef;
private async Task ScrollToBottom()
{
await chatRef.ScrollToBottomAsync();
}
private async Task FocusInput()
{
await chatRef.FocusAsync();
}
}自动滚动到底部并导航到特定消息:
csharp
<SfChatUI
@ref="chatRef"
ID="chat"
User="CurrentUser"
Messages="Messages"
AutoScrollToBottom="true">
</SfChatUI>
<button @onclick="ScrollToBottom">Go to Latest</button>
<button @onclick="FocusInput">Focus Input</button>
@code {
private SfChatUI chatRef;
private async Task ScrollToBottom()
{
await chatRef.ScrollToBottomAsync();
}
private async Task FocusInput()
{
await chatRef.FocusAsync();
}
}Pattern 6: Message Editing with UpdateMessageAsync
模式6:使用UpdateMessageAsync编辑消息
Edit existing messages programmatically:
csharp
<SfChatUI @ref="chatRef" ID="chat" User="CurrentUser" Messages="Messages">
</SfChatUI>
@code {
private SfChatUI chatRef;
private async Task EditMessage(string messageId, string newText)
{
var message = Messages.FirstOrDefault(m => m.ID == messageId);
if (message != null)
{
message.Text = newText;
await chatRef.UpdateMessageAsync(message, messageId);
}
}
}通过程序化方式编辑现有消息:
csharp
<SfChatUI @ref="chatRef" ID="chat" User="CurrentUser" Messages="Messages">
</SfChatUI>
@code {
private SfChatUI chatRef;
private async Task EditMessage(string messageId, string newText)
{
var message = Messages.FirstOrDefault(m => m.ID == messageId);
if (message != null)
{
message.Text = newText;
await chatRef.UpdateMessageAsync(message, messageId);
}
}
}Pattern 7: Mention System for User Tagging
模式7:用于用户标记的提及系统
Enable users to mention others in messages:
csharp
<SfChatUI
ID="chat"
User="CurrentUser"
Messages="Messages"
MentionChar="@"
MentionUsers="AllUsers"
ValueSelecting="@OnMentionSelected">
</SfChatUI>
@code {
private List<UserModel> AllUsers = new()
{
new UserModel { ID = "user1", User = "Albert" },
new UserModel { ID = "user2", User = "Michale" },
new UserModel { ID = "user3", User = "Reena" }
};
private void OnMentionSelected(MentionValueSelectingEventArgs<UserModel> args)
{
Console.WriteLine($"User mentioned: {args.ItemData.User}");
}
}允许用户在消息中提及他人:
csharp
<SfChatUI
ID="chat"
User="CurrentUser"
Messages="Messages"
MentionChar="@"
MentionUsers="AllUsers"
ValueSelecting="@OnMentionSelected">
</SfChatUI>
@code {
private List<UserModel> AllUsers = new()
{
new UserModel { ID = "user1", User = "Albert" },
new UserModel { ID = "user2", User = "Michale" },
new UserModel { ID = "user3", User = "Reena" }
};
private void OnMentionSelected(MentionValueSelectingEventArgs<UserModel> args)
{
Console.WriteLine($"User mentioned: {args.ItemData.User}");
}
}Pattern 8: Compact Mode for Group Chats
模式8:群聊紧凑模式
Display all messages left-aligned for group chat style:
csharp
<SfChatUI
ID="chat"
User="CurrentUser"
Messages="Messages"
EnableCompactMode="true">
</SfChatUI>
@code {
// In compact mode, all messages appear on left side
// Useful for group chat or support ticket interfaces
}将所有消息左对齐,呈现群聊样式:
csharp
<SfChatUI
ID="chat"
User="CurrentUser"
Messages="Messages"
EnableCompactMode="true">
</SfChatUI>
@code {
// In compact mode, all messages appear on left side
// Useful for group chat or support ticket interfaces
}Key Props
关键属性
| Property | Type | Purpose |
|---|---|---|
| string | Unique component identifier |
| UserModel | Current logged-in user |
| List<ChatMessage> | Conversation messages collection |
| bool | Display message timestamps (default: true) |
| string | Date/time format (default: "dd/MM/yyyy hh:mm tt") |
| bool | Display date separators between messages |
| List<UserModel> | Users currently typing |
| bool | Auto-scroll to bottom on new messages (default: false) |
| bool | Align all messages to left side (default: false) |
| string | Component height (default: "100%") |
| string | Component width (default: "100%") |
| string | Header text display (default: "Chat") |
| bool | Show/hide header (default: true) |
| bool | Show/hide footer (default: true) |
| string | Input placeholder text (default: "Type your message…") |
| List<string> | Quick reply suggestions |
| char | Mention trigger character (default: '@') |
| List<UserModel> | Users available for mention |
| bool | Load messages on demand (default: false) |
| string | Custom CSS styling |
| bool | Right-to-left direction support (default: false) |
| RenderFragment | Custom empty state content |
| RenderFragment<MessageTemplateContext> | Custom message rendering |
| RenderFragment<TimeBreakTemplateContext> | Custom date separator |
| RenderFragment<TypingUsersTemplateContext> | Custom typing indicator |
| RenderFragment<SuggestionTemplateContext> | Custom suggestion display |
| RenderFragment | Custom footer area |
| RenderFragment<PreviewTemplateContext> | Custom attachment preview |
| 属性 | 类型 | 用途 |
|---|---|---|
| string | 组件唯一标识符 |
| UserModel | 当前登录用户 |
| List<ChatMessage> | 对话消息集合 |
| bool | 显示消息时间戳(默认:true) |
| string | 日期/时间格式(默认:"dd/MM/yyyy hh:mm tt") |
| bool | 在消息之间显示日期分隔符 |
| List<UserModel> | 当前正在输入的用户 |
| bool | 新消息到来时自动滚动到底部(默认:false) |
| bool | 将所有消息左对齐(默认:false) |
| string | 组件高度(默认:"100%") |
| string | 组件宽度(默认:"100%") |
| string | 页眉显示文本(默认:"Chat") |
| bool | 显示/隐藏页眉(默认:true) |
| bool | 显示/隐藏页脚(默认:true) |
| string | 输入框占位文本(默认:"Type your message…") |
| List<string> | 快速回复建议 |
| char | 提及触发字符(默认:'@') |
| List<UserModel> | 可被提及的用户列表 |
| bool | 按需加载消息(默认:false) |
| string | 自定义CSS样式 |
| bool | 从右到左方向支持(默认:false) |
| RenderFragment | 自定义空状态内容 |
| RenderFragment<MessageTemplateContext> | 自定义消息渲染 |
| RenderFragment<TimeBreakTemplateContext> | 自定义日期分隔符 |
| RenderFragment<TypingUsersTemplateContext> | 自定义输入指示器 |
| RenderFragment<SuggestionTemplateContext> | 自定义建议显示 |
| RenderFragment | 自定义页脚区域 |
| RenderFragment<PreviewTemplateContext> | 自定义附件预览 |
Programmatic Methods
程序化方法
The Chat UI component provides async methods for programmatic control:
Chat UI组件提供异步方法用于程序化控制:
ScrollToBottomAsync()
ScrollToBottomAsync()
Scrolls the chat to the bottom, useful for showing latest messages:
csharp
@ref="chatRef"
private SfChatUI chatRef;
private async Task ShowLatestMessages()
{
await chatRef.ScrollToBottomAsync();
}将聊天滚动到底部,适用于显示最新消息:
csharp
@ref="chatRef"
private SfChatUI chatRef;
private async Task ShowLatestMessages()
{
await chatRef.ScrollToBottomAsync();
}ScrollToMessageAsync(string messageId)
ScrollToMessageAsync(string messageId)
Navigates to a specific message by ID:
csharp
private async Task NavigateToMessage(string targetMessageId)
{
await chatRef.ScrollToMessageAsync(targetMessageId);
}通过ID导航到特定消息:
csharp
private async Task NavigateToMessage(string targetMessageId)
{
await chatRef.ScrollToMessageAsync(targetMessageId);
}UpdateMessageAsync(ChatMessage message, string msgId)
UpdateMessageAsync(ChatMessage message, string msgId)
Updates an existing message content:
csharp
private async Task EditMessage(string messageId, string newText)
{
var message = Messages.FirstOrDefault(m => m.ID == messageId);
if (message != null)
{
message.Text = newText;
await chatRef.UpdateMessageAsync(message, messageId);
}
}更新现有消息内容:
csharp
private async Task EditMessage(string messageId, string newText)
{
var message = Messages.FirstOrDefault(m => m.ID == messageId);
if (message != null)
{
message.Text = newText;
await chatRef.UpdateMessageAsync(message, messageId);
}
}FocusAsync()
FocusAsync()
Sets focus on the chat input field:
csharp
private async Task FocusChatInput()
{
await chatRef.FocusAsync();
}将焦点设置在聊天输入框上:
csharp
private async Task FocusChatInput()
{
await chatRef.FocusAsync();
}Common Use Cases
常见使用场景
- Customer Support Chat - Live support widget with agent presence
- Team Messaging - Internal communication platform
- Bot Integration - AI chatbot with user interface
- Community Chat - Multi-user conversation rooms
- Help Desk - Ticketing and messaging interface
- Social Features - In-app messaging and notifications
- Real-time Collaboration - Live chat during shared activities
- 客户支持聊天 - 带客服在线状态的实时支持组件
- 团队消息 - 内部沟通平台
- 机器人集成 - 带用户界面的AI聊天机器人
- 社区聊天 - 多用户对话房间
- 帮助台 - 工单与消息界面
- 社交功能 - 应用内消息与通知
- 实时协作 - 共享活动期间的实时聊天