syncfusion-angular-chat-ui

Syncfusion Angular Chat UI 组件

组件概述

Syncfusion Angular Chat UI 组件为在 Angular 应用中构建对话界面提供了功能完备、特性丰富的解决方案。它支持实时消息传递、用户在线状态指示器、文件附件、输入指示器，并可与机器人框架和 AI 服务无缝集成。

主要功能：

• 消息管理 - 配置消息文本、富模板、媒体、回复、置顶和转发
• 用户系统 - 定义当前用户、在线状态、带自定义样式的头像和提及
• 外观控制 - 自定义宽度、高度、占位符、CSS 类、紧凑模式和建议
• 页眉和页脚 - 控制可见性、标题、图标、自定义模板，以及带操作项的页眉工具栏
• 事件和交互 - 处理消息发送、输入指示器和工具栏操作（复制、回复、置顶、删除）
• 模板 - 自定义空聊天界面、消息、时间分隔线、输入指示器和建议项
• 文件附件 - 启用上传并设置类型/大小限制，支持拖放、自定义路径和附件点击事件
• 方法 - 以编程方式添加/更新消息、滚动到底部、滚动到指定消息和聚焦输入框
• 全球化 - 支持多种语言（i18n）、RTL 文本方向和基于区域设置的格式化
• 高级功能 - 按需加载、状态持久化、提及、消息状态、时间分隔线和机器人集成

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置（Ivy 与 ngcc）
• 使用 Angular CLI 设置 Angular 环境
• 基本组件初始化
• 配置消息和用户
• CSS 导入和主题配置
• 运行应用

消息和用户

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

• 消息配置和属性（文本、id、作者、时间戳）
• 用户模型和头像
• 使用唯一标识符定义当前用户
• 头像 URL 和自定义背景颜色
• 用户在线状态（在线、离线、离开、忙碌）
• 为重要消息置顶
• 增强的 MessageReplyModel 完整接口文档
• 带附件的回复和时间戳格式
• 动态创建回复的模式
• 消息转发
• 群组对话的紧凑模式
• Markdown 消息支持

外观和布局

📄 阅读： references/appearance-and-layout.md

• 自定义占位符文本
• 宽度和高度属性
• 自定义 CSS 类以调整样式
• 紧凑模式配置
• 自动滚动到底部的行为
• 显示快速回复建议

页眉和页脚

📄 阅读： references/header-and-footer.md

• 控制页眉可见性
• 配置页眉文本（标题）
• 使用 CSS 类自定义页眉图标
• 带自定义操作项的页眉工具栏（通话、视频、设置、个人资料）
• ToolbarSettingsModel 配置，包含项和 itemClicked 事件
• 页脚可见性和控制
• 用于自定义布局的页脚模板

事件和交互

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

• 组件生命周期事件（created）
• 消息发送事件处理
• 用户输入事件和输入指示器
• 消息工具栏配置
• 完整的 ToolbarItemModel 属性（align、cssClass、disabled、iconCss、tabIndex、template、text、tooltip、type、visible）
• 自定义工具栏项（复制、回复、置顶、删除、转发）
• 项目点击事件处理
• 工具栏宽度配置
• 附件前后事件
• 页眉工具栏与消息工具栏的区别

模板和内容

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

• 消息模板自定义
• 用于初始状态的空聊天模板
• 用于日期分隔符的时间分隔模板
• 消息状态和发送图标
• 时间戳显示和可见性
• 时间戳格式自定义（dd/MM/yyyy hh:mm a）
• 建议模板自定义，支持上下文变量（index、suggestion）
• 高级建议示例（基于类别、搜索高亮、基于图标）
• 输入指示器模板

附件和文件处理

📄 阅读： references/attachments-and-file-handling.md

• 启用文件附件支持
• 附件设置配置
• 服务端端点（saveUrl、removeUrl）
• 文件类型限制和筛选器
• 文件大小限制（默认 30MB）
• SaveFormat 枚举（Blob 与 Base64），包括优点和适用场景
• 使用 path 属性设置自定义存储路径，用于 CDN／云存储
• 拖放文件上传
• 文件数量上限
• 文件预览模板
• 附件模板
• 用于自定义文件交互（预览、下载、元数据）的 attachmentClick 事件
• 用于为消息预填充文件的 attachedFile 属性
• 上传事件处理（成功、失败）

方法和程序化控制

📄 阅读： references/methods-and-programmatic-control.md

• addMessage() - 以编程方式添加新消息
• updateMessage() - 编辑现有消息
• scrollToBottom() - 滚动到最新消息
• scrollToMessage(messageId) - 跳转到指定消息（置顶消息、搜索结果、深层链接）
• focus() - 以编程方式聚焦聊天输入框（自动聚焦、关闭模态框、执行命令）
• ViewChild 组件访问
• 访问聊天实例以直接控制

全球化和本地化

📄 阅读： references/globalization-and-localization.md

• 本地化（L10n）和国际化（i18n）支持
• 输入指示器翻译
• 多语言支持
• 阿拉伯语、希伯来语和波斯语的从右到左（RTL）布局
• 区域设置配置
• 针对特定语言自定义字符串

高级功能

📄 阅读： references/advanced-features.md

• 使用 enablePersistence 实现状态持久化（localStorage、跨标签页同步、防止浏览器刷新导致状态丢失）
• 面向敏感数据的自定义持久化实现
• 按需加载大量消息历史（1000 条以上消息）
• 使用 @character 集成提及功能
• 触发字符自定义
• 消息中的预定义提及
• mentionSelect 事件处理
• 消息状态跟踪（已发送、已送达、已读）
• 在消息之间插入时间分隔，以便按日期整理

Bot 集成

📄 阅读： references/bot-integrations.md

• 集成 Google Dialogflow，实现 AI 对话
• 与 Azure 集成 Microsoft Bot Framework
• Direct Line API 配置
• 设置令牌服务以确保安全
• 后端 API 配置
• 安全地处理凭据
• Bot 响应消息处理
• 会话管理

---

快速入门示例

以下是一个帮助快速入门的最简示例：

import { Component } from '@angular/core';
import { ChatUIModule } from '@syncfusion/ej2-angular-interactive-chat';
import { UserModel } from '@syncfusion/ej2-interactive-chat';

@Component({
  imports: [ChatUIModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div id="chatui" ejs-chatui 
         [user]="currentUserModel" 
         headerText="TeamSync Professionals">
      <e-messages>
        <e-message text="Hi, how are you?" [author]="currentUserModel"></e-message>
        <e-message text="Great! How can I help?" [author]="michaleUserModel"></e-message>
      </e-messages>
    </div>
  `,
  styles: [`
    #chatui {
      height: 500px;
      width: 100%;
    }
  `]
})
export class AppComponent {
  public currentUserModel: UserModel = { user: 'Albert', id: 'user1' };
  public michaleUserModel: UserModel = { user: 'Michale', id: 'user2' };
}

安装：

npm install @syncfusion/ej2-angular-interactive-chat

CSS 导入（src/styles.css）：

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

---

关键组件和属性

核心组件：

• <ejs-chatui> - 主聊天容器
  • [user] - 当前用户模型（UserModel）
  • [messages] - 消息集合
  • headerText - 标题
  • [headerToolbar] - 带自定义操作的标题工具栏
  • [height] / [width] - 尺寸
  • [enableAttachments] - 文件上传支持
  • [enablePersistence] - 跨会话状态持久化
  • [enableRtl] - 从右到左布局
  • [attachmentSettings] - 文件上传配置
  • [messageToolbarSettings] - 消息级工具栏
  • [suggestions] - 快捷回复建议
  • [suggestionTemplate] - 自定义建议渲染

消息元素：

• <e-message> - 单条消息
  • text - 消息内容
  • [author] - 消息发送者
  • [timeStamp] - 消息时间戳
  • [timeStampFormat] - 自定义时间戳格式
  • [isPinned] - 是否置顶
  • [replyTo] - 线程上下文（MessageReplyModel）
  • [isForwarded] - 转发标记
  • [attachedFile] - 预先填充的文件附件（FileInfo）
  • [status] - 消息传送状态（MessageStatusModel）
  • [mentionUsers] - 消息中提及的用户

用户模型属性：

• id - 用户唯一标识符
• user - 显示名称
• avatarUrl - 头像图片
• avatarBgColor - 头像背景颜色
• statusIconCss - 在线状态图标

---

常见用例

1. 客户支持聊天

• 将标题配置为支持团队名称
• 启用文件附件，以便上传屏幕截图或文档
• 使用消息状态跟踪消息传送情况
• 与 Dialogflow 集成，实现 AI 驱动的回复

2. 团队消息应用

• 支持多个用户及其在线状态
• 使用 @mentions 提及队友
• 置顶重要决策或公告
• 使用时间戳格式支持时区

3. AI 助手

• 与 Microsoft Bot Framework 或 Dialogflow 集成
• 机器人回复时显示正在输入指示器
• 使用 suggestions 数组提供快捷回复建议
• 处理机器人专属的消息格式

4. 加载性能优化

• 为包含 1000 多条消息的对话启用按需加载
• 实现自动滚动，确保滚动流畅
• 使用紧凑模式减少垂直空间占用
• 延迟加载附件和媒体

5. 国际化（i18n）

• 提供本地化的输入状态提示（“X 正在输入”）
• 为阿拉伯语、希伯来语和波斯语用户启用 RTL
• 根据区域设置自定义日期和时间格式
• 翻译按钮标签和占位符

---