syncfusion-javascript-chat-ui

实现 Syncfusion TypeScript 聊天 UI

概述

聊天 UI 组件提供了现代化、功能丰富的界面，可用于构建对话应用，包括客户支持聊天、AI 聊天机器人、消息系统和协作沟通工具。

Syncfusion 聊天 UI（ChatUI）控件来自 @syncfusion/ej2-interactive-chat 包，提供以下功能：

• 消息管理 - 显示、发送和管理包含丰富内容的聊天消息
• 用户区分 - 以视觉方式区分当前用户和其他参与者
• 实时指示器 - 显示活跃参与者的输入指示器
• 文件附件 - 上传并在消息中显示文件、图像和文档
• 智能功能 - @提及、快速回复建议、消息回复
• 自定义 - 支持自定义消息、空状态、页眉和页脚的模板
• 无障碍功能 - 键盘导航、ARIA 支持、RTL 布局
• 消息工具栏 - 每条消息的操作（复制、回复、固定、删除）
• 按需加载 - 为较长的对话历史记录提供延迟加载

包： @syncfusion/ej2-interactive-chat

依赖项： ej2-base、ej2-navigations、ej2-inputs、ej2-buttons、ej2-dropdowns、ej2-popups

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装包
• 主题 CSS 导入（material、bootstrap、fabric 等）
• 基本聊天 UI 初始化
• UserModel 配置（当前用户和参与者）
• 初始消息的 MessageModel 结构
• 组件尺寸（宽度、高度）
• created 事件和组件生命周期

消息配置

📄 阅读： references/messages.md

• MessageModel 属性（id、text、author、timestamp、status）
• messages 属性 - 初始消息集合
• 消息状态指示器（已发送、已接收、已读）
• 消息回复（replyTo、MessageReplyModel）
• 消息标记（isForwarded、isPinned）
• 自动滚动行为（autoScrollToBottom）
• 按发送者对消息分组
• 消息中的提及（mentionUsers 数组）
• 消息中的附件

页眉和页脚配置

📄 阅读： references/header-footer.md

• 显示/隐藏页眉和页脚（showHeader、showFooter）
• 页眉文本和图标（headerText、headerIconCss）
• 页眉工具栏配置（headerToolbar、ToolbarSettingsModel）
• 工具栏项设置（包含 text、icon、alignment、tooltip 的 ToolbarItemModel）
• 工具栏项点击事件（itemClicked）
• 自定义页脚占位文本
• 用于自定义布局的页脚模板

输入指示器

📄 阅读： references/typing-indicator.md

• 显示/隐藏输入指示器（typingUsers 属性）
• 动态更新输入用户（UserModel 数组）
• 多个用户同时输入的场景
• 自定义输入指示器模板（typingUsersTemplate）
• userTyping 事件（isTyping、message、user）

模板与自定义

📄 阅读： references/templates.md

• 空聊天模板（emptyChatTemplate）
• 消息模板（messageTemplate）及其上下文
• 输入用户模板（typingUsersTemplate）
• 时间分隔模板（timeBreakTemplate）
• 建议模板（suggestionTemplate）
• 页脚模板（footerTemplate）
• 模板上下文和数据绑定模式

时间分隔与时间戳

📄 阅读： references/timebreak-timestamp.md

• 显示时间分隔（showTimeBreak），按日期分组
• 自定义时间分隔模板
• 按消息显示时间戳（showTimeStamp）
• 全局时间戳格式（timeStampFormat）
• 覆盖单条消息的时间戳格式
• 日期/时间格式模式
• 基于区域设置的格式化

文件附件

📄 阅读： references/file-attachments.md

• 启用附件（enableAttachments）
• 附件设置（attachmentSettings、FileAttachmentSettingsModel）
• 服务端上传配置（saveUrl、removeUrl）
• 保存格式选项（Base64 与 Blob）
• 文件类型限制（allowedFileTypes）
• 文件大小限制（maxFileSize）
• 最大附件数量（maximumCount）
• 支持拖放（enableDragAndDrop）
• 自定义附件模板（attachmentTemplate、previewTemplate）
• 附件事件（click、upload、success、failure、removed）

@提及集成

📄 阅读： references/mention.md

• 提及触发字符（mentionTriggerChar，默认为 '@'）
• 提及用户列表（mentionUsers 属性）
• 用于提及的 UserModel 配置
• 提及弹窗筛选
• mentionSelect 事件及取消操作
• 消息中的提及数据
• 自定义提及处理

建议

📄 阅读： references/suggestions.md

• 快捷回复建议（suggestions 属性）
• 自定义建议模板（suggestionTemplate）
• 在输入框上方显示建议
• 建议点击行为
• 动态更新建议

按需加载

📄 阅读： references/load-on-demand.md

• 启用延迟加载（loadOnDemand 属性）
• 滚动触发消息加载
• 大型会话的性能优化
• 分页模式
• 以编程方式添加较早的消息

方法

📄 阅读： references/methods.md

• addMessage() - 添加字符串或 MessageModel
• updateMessage() - 修改现有消息
• scrollToBottom() - 滚动到最新消息
• scrollToMessage() - 按 ID 滚动到指定消息
• focus() - 将焦点设到输入文本区域
• 用于更新的 refresh() 和 dataBind()
• 其他组件方法

事件

📄 阅读： references/events.md

• created - 组件初始化
• messageSend - 发送消息前触发（可取消）
• userTyping - 输入状态更新
• mentionSelect - 提及选择处理
• itemClicked - 工具栏项目点击（标题栏和消息工具栏）
• 附件事件（click、beforeUpload、uploadSuccess、uploadFailure、removed）
• 事件处理模式

消息工具栏与外观

📄 阅读： references/message-toolbar-appearance.md

• 消息工具栏设置（messageToolbarSettings）
• 单条消息的工具栏项目（Copy、Reply、Pin、Delete）
• 自定义工具栏项目
• 消息工具栏点击事件
• 紧凑模式（enableCompactMode）- 将所有消息左对齐
• CSS 自定义（cssClass）
• 主题集成
• RTL 支持（enableRtl）
• 本地化（locale）
• 持久化（enablePersistence）
• 无障碍功能

---

快速开始

基本聊天界面设置

import { ChatUI, UserModel, MessageModel } from '@syncfusion/ej2-interactive-chat';
import { enableRipple } from '@syncfusion/ej2-base';

enableRipple(true);

// Define current user
let currentUser: UserModel = {
    id: "user1",
    user: "Albert",
    avatarUrl: "https://example.com/avatar1.png"
};

// Define other participant
let participantUser: UserModel = {
    id: "user2",
    user: "Michale Suyama",
    avatarUrl: "https://example.com/avatar2.png"
};

// Initial messages
let chatMessages: MessageModel[] = [
    {
        author: currentUser,
        text: "Hi Michale, are we on track for the deadline?"
    },
    {
        author: participantUser,
        text: "Yes, the design phase is complete."
    },
    {
        author: currentUser,
        text: "Great! I'll review it and send feedback by today."
    }
];

// Initialize Chat UI
let chatUI: ChatUI = new ChatUI({
    user: currentUser,
    messages: chatMessages,
    headerText: 'Michale Suyama',
    showTimeStamp: true,
    autoScrollToBottom: true
});

// Render
chatUI.appendTo('#chatUI');

HTML 结构

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Chat UI Example</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    
    
    <link href="https://cdn.syncfusion.com/ej2/32.1.19/fluent2.css" rel="stylesheet" />
</head>
<body>
    <div class="chatui-container" style="height: 500px; width: 400px;">
        <div id="chatUI"></div>
    </div>
</body>
</html>

CSS 导入（通过 npm）

@import "../../node_modules/@syncfusion/ej2-fluent2-theme/styles/chat-ui/index.css";

---

常见模式

以编程方式添加新消息

// Add as string (uses current user)
chatUI.addMessage("This is a new message");

// Add as MessageModel (any user)
chatUI.addMessage({
    text: "Response from bot",
    author: botUser,
    timestamp: new Date()
});

处理消息发送事件

let chatUI: ChatUI = new ChatUI({
    user: currentUser,
    messageSend: (args: MessageSendEventArgs) => {
        console.log("Message being sent:", args.message.text);
        
        // Cancel send if needed
        if (args.message.text.trim() === '') {
            args.cancel = true;
        }
        
        // Send to server/API
        sendToServer(args.message);
    }
});

显示输入指示器

// Show user is typing
chatUI.typingUsers = [participantUser];

// Hide typing indicator (after message received)
chatUI.typingUsers = [];

启用带上传功能的文件附件

let chatUI: ChatUI = new ChatUI({
    user: currentUser,
    enableAttachments: true,
    attachmentSettings: {
        saveUrl: 'https://your-server.com/api/upload',
        removeUrl: 'https://your-server.com/api/remove',
        allowedFileTypes: '.jpg,.png,.pdf,.docx',
        maxFileSize: 5242880, // 5MB in bytes
        maximumCount: 3
    },
    attachmentUploadSuccess: (args) => {
        console.log("File uploaded successfully:", args.file.name);
    }
});

添加 @提及支持

let mentionableUsers: UserModel[] = [
    { id: "user1", user: "Albert" },
    { id: "user2", user: "Michale" },
    { id: "user3", user: "Janet" }
];

let chatUI: ChatUI = new ChatUI({
    user: currentUser,
    mentionTriggerChar: '@',
    mentionUsers: mentionableUsers,
    mentionSelect: (args: MentionSelectEventArgs) => {
        console.log("Mentioned user:", args.itemData);
    }
});

更新现有消息

// Update message content
chatUI.updateMessage({
    text: "Updated message content",
    author: currentUser
}, "message-id-123");

滚动到指定消息

// Scroll to bottom (latest message)
chatUI.scrollToBottom();

// Scroll to specific message by ID
chatUI.scrollToMessage("message-id-456");

---

关键属性摘要

属性	类型	描述
user	UserModel	当前与聊天互动的用户
messages	MessageModel[]	聊天消息集合
showHeader	boolean	显示/隐藏页眉（默认：true）
showFooter	boolean	显示/隐藏页脚（默认：true）
headerText	string	页眉中显示的文本
placeholder	string	输入框占位文本
typingUsers	UserModel[]	当前正在输入的用户
showTimeStamp	boolean	显示消息时间戳（默认：true）
showTimeBreak	boolean	按日期对消息分组（默认：false）
autoScrollToBottom	boolean	收到新消息时自动滚动（默认：false）
enableAttachments	boolean	启用文件附件（默认：false）
attachmentSettings	FileAttachmentSettingsModel	文件上传配置
mentionTriggerChar	string	触发提及的字符（默认：'@'）
mentionUsers	UserModel[]	可供 @mention 的用户
suggestions	string[]	快捷回复建议
loadOnDemand	boolean	延迟加载消息（默认：false）
enableCompactMode	boolean	将所有消息左对齐（默认：false）
messageToolbarSettings	MessageToolbarSettingsModel	单条消息的工具栏配置
headerToolbar	ToolbarSettingsModel	页眉工具栏配置
width	string | number	组件宽度（默认：'100%'）
height	string | number	组件高度（默认：'100%'）
cssClass	string	自定义 CSS 类
enableRtl	boolean	从右向左布局（默认：false）
locale	string	本地化区域设置

---

常见用例

客户支持聊天

• 实时 Agent 与客户对话
• 通过输入状态指示 Agent 是否可用
• 通过文件附件发送屏幕截图/文档
• 消息状态（已发送、已送达、已读）
• 为常见回复提供快捷回复建议

AI 聊天机器人界面

• 区分用户与机器人的消息
• AI 处理期间显示输入状态指示
• 建议回复和快捷操作
• 用于丰富回复的消息模板
• 显示欢迎消息的空状态

团队协作工具

• @提及团队成员
• 回复消息并进行串联讨论
• 置顶重要消息
• 支持预览的文件共享
• 长对话按需加载

实时帮助小组件

• 嵌入式小组件采用紧凑模式
• 带有 Agent 信息的自定义页眉
• 显示输入状态的页脚
• 自动滚动到最新消息
• 最小化/最大化功能

文档问答

• 采用问答格式，清楚区分用户
• 附加代码片段
• 按对话会话显示时间分隔
• 带有复制功能的消息工具栏
• 搜索并滚动到指定消息