syncfusion-blazor-chat-ui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syncfusion 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

关键属性

PropertyTypePurpose
ID
stringUnique component identifier
User
UserModelCurrent logged-in user
Messages
List<ChatMessage>Conversation messages collection
ShowTimestamp
boolDisplay message timestamps (default: true)
TimestampFormat
stringDate/time format (default: "dd/MM/yyyy hh:mm tt")
ShowTimeBreak
boolDisplay date separators between messages
TypingUsers
List<UserModel>Users currently typing
AutoScrollToBottom
boolAuto-scroll to bottom on new messages (default: false)
EnableCompactMode
boolAlign all messages to left side (default: false)
Height
stringComponent height (default: "100%")
Width
stringComponent width (default: "100%")
HeaderText
stringHeader text display (default: "Chat")
ShowHeader
boolShow/hide header (default: true)
ShowFooter
boolShow/hide footer (default: true)
Placeholder
stringInput placeholder text (default: "Type your message…")
Suggestions
List<string>Quick reply suggestions
MentionChar
charMention trigger character (default: '@')
MentionUsers
List<UserModel>Users available for mention
LoadOnDemand
boolLoad messages on demand (default: false)
CssClass
stringCustom CSS styling
EnableRtl
boolRight-to-left direction support (default: false)
EmptyChatTemplate
RenderFragmentCustom empty state content
MessageTemplate
RenderFragment<MessageTemplateContext>Custom message rendering
TimeBreakTemplate
RenderFragment<TimeBreakTemplateContext>Custom date separator
TypingUsersTemplate
RenderFragment<TypingUsersTemplateContext>Custom typing indicator
SuggestionTemplate
RenderFragment<SuggestionTemplateContext>Custom suggestion display
FooterTemplate
RenderFragmentCustom footer area
PreviewTemplate
RenderFragment<PreviewTemplateContext>Custom attachment preview
属性类型用途
ID
string组件唯一标识符
User
UserModel当前登录用户
Messages
List<ChatMessage>对话消息集合
ShowTimestamp
bool显示消息时间戳(默认:true)
TimestampFormat
string日期/时间格式(默认:"dd/MM/yyyy hh:mm tt")
ShowTimeBreak
bool在消息之间显示日期分隔符
TypingUsers
List<UserModel>当前正在输入的用户
AutoScrollToBottom
bool新消息到来时自动滚动到底部(默认:false)
EnableCompactMode
bool将所有消息左对齐(默认:false)
Height
string组件高度(默认:"100%")
Width
string组件宽度(默认:"100%")
HeaderText
string页眉显示文本(默认:"Chat")
ShowHeader
bool显示/隐藏页眉(默认:true)
ShowFooter
bool显示/隐藏页脚(默认:true)
Placeholder
string输入框占位文本(默认:"Type your message…")
Suggestions
List<string>快速回复建议
MentionChar
char提及触发字符(默认:'@')
MentionUsers
List<UserModel>可被提及的用户列表
LoadOnDemand
bool按需加载消息(默认:false)
CssClass
string自定义CSS样式
EnableRtl
bool从右到左方向支持(默认:false)
EmptyChatTemplate
RenderFragment自定义空状态内容
MessageTemplate
RenderFragment<MessageTemplateContext>自定义消息渲染
TimeBreakTemplate
RenderFragment<TimeBreakTemplateContext>自定义日期分隔符
TypingUsersTemplate
RenderFragment<TypingUsersTemplateContext>自定义输入指示器
SuggestionTemplate
RenderFragment<SuggestionTemplateContext>自定义建议显示
FooterTemplate
RenderFragment自定义页脚区域
PreviewTemplate
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

常见使用场景

  1. Customer Support Chat - Live support widget with agent presence
  2. Team Messaging - Internal communication platform
  3. Bot Integration - AI chatbot with user interface
  4. Community Chat - Multi-user conversation rooms
  5. Help Desk - Ticketing and messaging interface
  6. Social Features - In-app messaging and notifications
  7. Real-time Collaboration - Live chat during shared activities
  1. 客户支持聊天 - 带客服在线状态的实时支持组件
  2. 团队消息 - 内部沟通平台
  3. 机器人集成 - 带用户界面的AI聊天机器人
  4. 社区聊天 - 多用户对话房间
  5. 帮助台 - 工单与消息界面
  6. 社交功能 - 应用内消息与通知
  7. 实时协作 - 共享活动期间的实时聊天