syncfusion-aspnetcore-chat-ui

Syncfusion ASP.NET Core Chat-UI 控件

概述

Chat-UI 组件提供完整的对话界面，支持实时消息、文件附件、用户在线状态以及丰富的自定义选项。本指南将指导你使用 ASP.NET Core 标记帮助程序和 Razor 页面，为客户支持、团队协作和交互式应用构建聊天界面。

Chat-UI 组件是一个交互式消息界面，具有以下功能：

• 丰富的消息支持： 文本内容、置顶消息、线程回复、消息转发
• 用户管理： 多用户对话、在线状态、用户配置
• 文件附件： 上传、预览、下载，并可限制文件类型和大小
• 事件系统： 创建、发送消息、用户正在输入、附件事件
• 模板： 可自定义的空聊天、消息、正在输入指示器、建议和页脚 UI
• 外观： 可配置占位文本、宽度、高度和 CSS 类
• 时间戳： 显示或隐藏时间戳，并可自定义格式
• 高级功能： 紧凑模式、全球化、RTL 支持、语音转文本

快速入门示例

@using Syncfusion.EJ2.InteractiveChat;

<div style="height:400px; width:450px">
    <ejs-chatui id="chatUI">
        <e-chatui-user id="user1" user="Albert"></e-chatui-user>
        <e-chatui-messages>
            @foreach (var message in ViewBag.ChatMessagesData)
            {
                <e-chatui-message text="@message.Text" author="@message.Author"></e-chatui-message>
            }
        </e-chatui-messages>
    </ejs-chatui>
</div>

对应的 C# 控制器：

using Syncfusion.EJ2.InteractiveChat;

public ActionResult Default()
{
    var currentUser = new ChatUIUser() { Id = "user1", User = "Albert" };
    var otherUser = new ChatUIUser() { Id = "user2", User = "Michale Suyama" };
    
    var messages = new List<ChatUIMessage>()
    {
        new ChatUIMessage() { Text = "Hi Michale, are we on track?", Author = currentUser },
        new ChatUIMessage() { Text = "Yes, all set!", Author = otherUser }
    };
    
    ViewBag.ChatMessagesData = messages;
    return View();
}

文档导航

开始使用

📄 阅读： references/getting-started.md

• NuGet 包安装和依赖项
• 使用 Razor 页面的 ASP.NET Core 项目设置
• 标记帮助程序注册和配置
• CDN 样式表和脚本设置
• 脚本管理器注册
• 基本 Chat-UI 实现
• 初始用户和消息配置

消息配置

📄 阅读： references/messages-configuration.md

• 消息模型设置和属性
• 添加和管理文本消息
• 消息配置（ID、文本、作者、时间戳）
• 为重要对话置顶消息
• 线程对话的回复对象
• 转发消息和消息跟踪
• 用于简化布局的紧凑模式

用户配置

📄 阅读： references/user-configuration.md

• ChatUIUser 模型设置和属性
• 用户身份配置
• 设置当前用户上下文
• 多用户支持和管理
• 用户在线状态和状态指示器
• 头像配置和样式设置

外观与样式

📄 阅读： references/appearance-styling.md

• 自定义占位文本
• 宽度和高度配置
• CSS 类应用和自定义
• 组件级样式设置
• 主题自定义方法
• 响应式设计模式

事件与交互

📄 阅读： references/events-interactions.md

• 用于初始化的创建事件
• 消息发送事件处理
• 用户正在输入事件检测
• 附件上传事件（上传前、成功、失败）
• 附件移除和点击事件
• 事件绑定模式和最佳实践

方法与 API

📄 阅读： references/methods-api.md

• 用于以编程方式添加消息的 addMessage 方法
• 用于编辑现有消息的 updateMessage 方法
• 用于视图导航的 scrollToBottom 方法
• 使用 SignalR 的实时集成
• 性能和错误处理最佳实践

模板与自定义

📄 阅读： references/templates-customization.md

• 用于初始状态的空聊天模板
• 使用 jsrender 的自定义消息模板
• 用于消息整理的时间分隔模板
• 正在输入指示器模板自定义
• 用于自动完成的建议模板
• 用于自定义输入区域的页脚模板
• 高级模板模式和样式设置

文件附件

📄 阅读： references/file-attachments.md

• 使用 enableAttachments 启用附件支持
• 配置附件设置
• 保存和移除 URL 端点
• 文件类型限制（allowedFileTypes）
• 文件大小限制（maxFileSize）
• 保存格式选项（Blob 或 Base64）
• 配置拖放支持
• 服务端路径和上传处理

页眉和页脚

📄 阅读： references/header-footer.md

• 使用 showHeader 属性显示或隐藏页眉
• 配置页眉文本和显示方式
• 使用 headerIconCss 设置页眉图标样式
• 使用 showFooter 属性显示或隐藏页脚
• 自定义页脚模板
• 配置输入区域

时间戳和时间分隔

📄 阅读： references/timestamps-timebreaks.md

• 使用 showTimeStamp 显示或隐藏时间戳
• 自定义时间戳格式（timeStampFormat）
• 使用时间分隔符整理消息
• 按日期对消息分组
• 时间戳模板模式

正在输入指示器

📄 阅读： references/typing-indicator.md

• 显示或隐藏正在输入指示器
• 显示多位用户的输入状态
• 自定义正在输入指示器模板
• 检测用户状态
• 设置正在输入指示器 UI 的样式

提及和用户引用

📄 阅读： references/mentions-integration.md

• 配置可提及的用户
• 自定义提及触发字符
• 在消息中预定义提及
• 提及选择和事件
• 提及项模板和样式

全球化和 RTL

📄 阅读： references/globalization-rtl.md

• 本地化和多语言支持
• 设置区域性和语言区域
• 支持 RTL（从右向左）布局
• 特定语言的模板
• 语音转文本本地化

工具栏配置

📄 阅读： references/toolbar-configuration.md

• 配置页眉工具栏及其项目
• 消息工具栏设置和自定义
• 工具栏项目配置和事件
• 自定义工具栏操作和处理程序
• 工具栏可见性和样式

高级功能

📄 阅读： references/advanced-features.md

• 使用滚动处理实现按需加载
• 自动滚动到底部
• 启用持久化以管理状态
• 性能优化技巧
• 服务端数据加载策略

建议功能

📄 阅读： references/suggestions-feature.md

• 使用 suggestions 属性启用建议
• 自定义建议模板
• 根据上下文筛选建议
• 建议选择和处理
• 自定义建议 UI 和样式

常见模式

创建基本聊天界面

<div style="height:400px; width:500px">
    <ejs-chatui id="chatUI" 
                 placeholder="Type a message..."
                 showHeader="true"
                 headerText="Support Chat">
        <e-chatui-user id="user1" user="Support Agent"></e-chatui-user>
    </ejs-chatui>
</div>

使用事件添加消息

<ejs-chatui id="chatUI" messageSend="onMessageSend">
    <e-chatui-user id="user1" user="Albert"></e-chatui-user>
    <e-chatui-messages>
        @foreach (var message in ViewBag.ChatMessagesData)
        {
            <e-chatui-message text="@message.Text" 
                            author="@message.Author"
                            timeStamp="@message.TimeStamp"></e-chatui-message>
        }
    </e-chatui-messages>
</ejs-chatui>

<script>
    function onMessageSend(args) {
        // Handle message send event
        console.log("Message sent:", args);
    }
</script>

启用文件附件

<ejs-chatui id="chatUI" enableAttachments="true">
    <e-chatui-user id="user1" user="Albert"></e-chatui-user>
    <e-chatui-attachmentsettings 
        [email protected]("https://services.syncfusion.com/aspnet/production/api/FileUploader/Save")
        [email protected]("https://services.syncfusion.com/aspnet/production/api/FileUploader/Remove")
        maxFileSize="5000000"
        allowedFileTypes=".pdf,.docx,.xlsx">
    </e-chatui-attachmentsettings>
</ejs-chatui>

关键属性

属性	类型	用途
id	string	ChatUI 组件的唯一标识符
placeholder	string	输入框提示文本（默认值："Type your message…"）
width	string	聊天界面的宽度（默认值：100%）
height	string	聊天界面的高度（默认值：100%）
showHeader	boolean	显示标题区域（默认值：true）
headerText	string	显示标题/名称
headerToolbar	object	配置标题栏中的工具栏项
showFooter	boolean	显示输入框底部区域（默认值：true）
showTimeStamp	boolean	显示消息时间戳（默认值：true）
timeStampFormat	string	时间戳格式模式（默认值："dd/MM/yyyy hh:mm a"）
cssClass	string	用于样式设置的 CSS 类
enableAttachments	boolean	启用文件上传支持（默认值：false）
enableCompactMode	boolean	将所有消息左对齐（默认值：false）
loadOnDemand	boolean	启用消息的延迟加载（默认值：false）
autoScrollToBottom	boolean	自动滚动到最新消息（默认值：true）
enablePersistence	boolean	在不同会话间保留聊天状态（默认值：false）
suggestions	array	为用户提供快速回复建议
messageToolbarSettings	object	配置消息级工具栏操作

常见用例

用例 1：客户支持聊天

• 多个支持 Agent 处理客户咨询
• 附加截图/文档等文件
• 显示带时间戳的消息历史记录
• 使用输入指示器显示 Agent 正在参与对话
• 标题栏显示支持 Agent 的姓名和状态

用例 2：团队协作

• 使用 @ 提及团队成员
• 置顶重要讨论内容
• 转发消息以供参考
• 编辑和删除消息
• 显示多用户在线状态指示器

用例 3：多语言支持

• 支持阿拉伯语/希伯来语的 RTL 布局
• 通过全球化功能本地化 UI 字符串
• 使用特定于区域设置的时间戳格式
• 支持多种字符集