syncfusion-blazor-chat-ui

Syncfusion Blazor Chat UI

使用 Syncfusion Blazor Chat UI 组件构建功能丰富的对话式聊天界面。本技能提供了完整指南，帮助你在 Blazor Server、WebAssembly 和 Web App 项目中创建多用户消息应用、聊天面板和交互式对话 UI。

组件概述

SfChatUI 组件是一种专用 UI 控件，用于构建对话式聊天应用。它管理完整的聊天界面，包括：

• 消息管理： 聊天消息集合及完整的消息生命周期
• 用户管理： 支持多用户，包括个人资料、头像和状态
• 在线状态功能： 输入状态指示器、在线状态、用户识别
• 丰富的渲染能力： 消息、时间戳、输入状态指示器和建议的模板
• 文件支持： 文件附件上传与集成
• 事件系统： 生命周期事件和用户交互回调
• 自定义： 完整的样式与主题控制

导航指南

开始使用

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• 基本组件结构和初始化
• 用户与消息配置
• 包含对话的最小可运行示例

消息与用户管理

📄 阅读： references/messages-and-users.md

• ChatMessage 配置和属性
• UserModel 设置和属性
• 消息文本内容管理
• 作者识别与用户分配
• 构建消息集合和对话历史

用户个人资料与头像

📄 阅读： references/user-profiles-avatars.md

• 使用图像配置头像 URL
• 自定义头像背景颜色
• 用户状态指示器（在线、离线、忙碌、离开）
• 用户自定义 CSS 样式
• 用户识别和显示名称

输入状态指示器

📄 阅读： references/typing-indicators.md

• TypingUsers 属性配置
• 显示/隐藏输入状态指示器
• 管理多个正在输入的用户
• 动态更新输入状态
• 自定义输入状态指示器模板

时间戳与格式设置

📄 阅读： references/timestamps-and-formatting.md

• 使用 ShowTimestamp 属性启用/禁用时间戳
• 消息时间戳配置
• 自定义 TimestampFormat
• TimeBreak 分隔符（今天、昨天、具体日期）
• 设置 TimeBreak 模板样式

模板与自定义

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

• 使用 EmptyChatTemplate 显示初始状态
• 使用 MessageTemplate 自定义消息渲染
• 使用 TimeBreakTemplate 设置日期分隔符
• 使用 TypingUsersTemplate 显示输入状态
• 使用 SuggestionTemplate 设置快速回复按钮
• CSS 样式和主题集成

附件与事件

📄 阅读： references/attachments-and-events.md

• 文件附件配置（Enable）
• SaveUrl 和 RemoveUrl 端点设置
• AllowedFileTypes 筛选
• MaxFileSize 限制与约束
• SaveFormat 选项（Blob 与 Base64）
• 事件处理：Created、MessageSend、UserTyping
• 附件事件：OnAttachmentUploadReady、UploadSuccess、UploadFailed

编程 API 与方法 🆕

📄 阅读： references/programmatic-api.md

• 使用 ScrollToBottomAsync() 跳转到最新消息
• 使用 ScrollToMessageAsync() 跳转到指定消息
• 使用 UpdateMessageAsync() 编辑现有消息
• 使用 FocusAsync() 控制输入字段
• 包含错误处理的完整示例

高级功能 🆕

📄 阅读： references/advanced-features.md

• AutoScrollToBottom 配置
• 为群聊启用 CompactMode
• 自定义页眉和页脚
• 设置提及系统（@mention）
• 快速回复建议
• 使用 LoadOnDemand 提升性能
• 支持 RTL（从右到左）
• 使用 CssClass 自定义样式

快速开始

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

常见模式

模式 1：带状态的多用户对话

显示多个用户及其在线／离线状态指示器：

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

模式 2：带输入指示器的聊天

显示用户正在输入的状态：

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

模式 3：自定义消息模板

个性化消息外观：

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

模式 4：带文件附件的聊天

允许用户分享文件：

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

模式 5：通过程序控制自动滚动

自动滚动到底部并跳转到指定消息：

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

模式 6：使用 UpdateMessageAsync 编辑消息

以编程方式编辑现有消息：

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

模式 7：用于标记用户的提及系统

允许用户在消息中提及他人：

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

模式 8：群聊紧凑模式

将所有消息左对齐，呈现群聊样式：

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

关键属性

属性	类型	用途
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>	自定义附件预览

程序化方法

Chat UI 组件提供了用于程序化控制的异步方法：

ScrollToBottomAsync()

将聊天滚动到底部，便于显示最新消息：

@ref="chatRef"

private SfChatUI chatRef;

private async Task ShowLatestMessages()
{
    await chatRef.ScrollToBottomAsync();
}

ScrollToMessageAsync(string messageId)

根据 ID 跳转到指定消息：

private async Task NavigateToMessage(string targetMessageId)
{
    await chatRef.ScrollToMessageAsync(targetMessageId);
}

UpdateMessageAsync(ChatMessage message, string msgId)

更新现有消息的内容：

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()

将焦点设在聊天输入框中：

private async Task FocusChatInput()
{
    await chatRef.FocusAsync();
}

常见用例

1. 客户支持聊天 - 带有客服在线状态的实时支持小组件
2. 团队消息 - 内部通信平台
3. 机器人集成 - 带有用户界面的 AI 聊天机器人
4. 社区聊天 - 多用户对话聊天室
5. 服务台 - 工单和消息界面
6. 社交功能 - 应用内消息和通知
7. 实时协作 - 共享活动期间的实时聊天