syncfusion-angular-chat-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion Angular Chat UI Component

Syncfusion Angular Chat UI组件

Component Overview

组件概述

The Syncfusion Angular Chat UI component provides a complete, feature-rich solution for building conversational interfaces in Angular applications. It enables real-time messaging, user presence indicators, file attachments, typing indicators, and seamless integration with bot frameworks and AI services.

Key Capabilities:

Message Management - Configure messages with text, rich templates, media, replies, pinning, and forwarding
User System - Define current user, presence status, avatars with custom styling and mentions
Appearance Control - Customize width, height, placeholder, CSS classes, compact mode, and suggestions
Header & Footer - Control visibility, titles, icons, custom templates, and header toolbar with actions
Events & Interactions - Handle message send, typing indicators, toolbar actions (copy, reply, pin, delete)
Templates - Customize empty chat, messages, time breaks, typing indicators, and suggestion items
File Attachments - Enable uploads with type/size restrictions, drag-and-drop, custom paths, attachment click events
Methods - Programmatically add/update messages, scroll to bottom, scroll to specific message, focus input
Globalization - Support multiple languages (i18n), RTL text direction, and locale-based formatting
Advanced Features - Load on demand, state persistence, mentions, message status, time breaks, bot integrations

Syncfusion Angular Chat UI组件为在Angular应用中构建对话界面提供了一套功能完整的解决方案。它支持实时消息收发、用户在线状态提示、文件附件、输入状态提示，还能与机器人框架和AI服务无缝集成。

核心功能：

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

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup (Ivy vs ngcc)
Setup Angular environment with Angular CLI
Basic component initialization
Configuring messages and users
CSS imports and theme configuration
Running the application

📄 阅读： references/getting-started.md

安装与包配置（Ivy vs ngcc）
使用Angular CLI搭建Angular环境
基础组件初始化
配置消息与用户
CSS导入与主题配置
运行应用

Messages and Users

消息与用户

📄 Read: references/messages-and-users.md

Message configuration and properties (text, id, author, timestamp)
User models and avatars
Defining current user with unique identifier
Avatar URLs and custom background colors
User presence status (online, offline, away, busy)
Message pinning for important messages
Enhanced MessageReplyModel with complete interface documentation
Reply with attachments and timestamp formatting
Dynamic reply creation patterns
Message forwarding
Compact mode for group conversations
Markdown message support

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

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

Appearance and Layout

外观与布局

📄 Read: references/appearance-and-layout.md

Placeholder text customization
Width and height properties
CSS class customization for styling
Compact mode configuration
Auto-scroll to bottom behavior
Suggestions display for quick replies

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

占位符文本定制
宽高属性配置
CSS类定制样式
紧凑模式配置
自动滚动到底部行为
快捷回复建议展示

Header and Footer

页眉与页脚

📄 Read: references/header-and-footer.md

Header visibility control
Header text (title) configuration
Header icon customization with CSS classes
Header toolbar with custom actions (call, video, settings, profile)
ToolbarSettingsModel configuration with items and itemClicked event
Footer visibility and control
Footer template for custom layouts

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

页眉可见性控制
页眉文本（标题）配置
带CSS类的页眉图标定制
带自定义操作的页眉工具栏（通话、视频、设置、个人资料）
ToolbarSettingsModel配置及项点击事件
页脚可见性与控制
自定义布局的页脚模板

Events and Interactions

事件与交互

📄 Read: references/events-and-interactions.md

Component lifecycle events (created)
Message send event handling
User typing event and typing indicators
Message toolbar configuration
Complete ToolbarItemModel properties (align, cssClass, disabled, iconCss, tabIndex, template, text, tooltip, type, visible)
Toolbar items customization (copy, reply, pin, delete, forward)
Item click event handling
Toolbar width configuration
Before/after attachment events
Header toolbar vs message toolbar differences

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

组件生命周期事件（创建）
消息发送事件处理
用户输入事件与输入状态提示
消息工具栏配置
完整的ToolbarItemModel属性（对齐方式、CSS类、禁用状态、图标CSS、Tab索引、模板、文本、提示、类型、可见性）
工具栏项定制（复制、回复、置顶、删除、转发）
项点击事件处理
工具栏宽度配置
附件上传前后事件
页眉工具栏与消息工具栏的区别

Templates and Content

模板与内容

📄 Read: references/templates-and-content.md

Message template customization
Empty chat template for initial state
Time break template for date separators
Message status and delivery icons
Timestamp display and visibility
Timestamp format customization (dd/MM/yyyy hh:mm a)
Suggestion template customization with context variables (index, suggestion)
Advanced suggestion examples (category-based, search-highlighted, icon-based)
Typing indicator template

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

消息模板定制
初始状态的空聊天模板
日期分隔的时间间隔模板
消息状态与送达图标
时间戳显示与可见性
时间戳格式定制（dd/MM/yyyy hh:mm a）
带上下文变量的快捷回复模板定制（索引、回复项）
高级快捷回复示例（基于分类、搜索高亮、带图标）
输入状态提示模板

Attachments and File Handling

附件与文件处理

📄 Read: references/attachments-and-file-handling.md

Enable file attachment support
Attachment settings configuration
Server endpoints (saveUrl, removeUrl)
File type restrictions and filters
File size limits (default 30MB)
SaveFormat enum (Blob vs Base64) with advantages and use cases
Custom storage paths with path property for CDN/cloud storage
Drag-and-drop file upload
Maximum file count restrictions
File preview templates
Attachment templates
attachmentClick event for custom file interactions (preview, download, metadata)
attachedFile property for pre-populating messages with files
Upload event handling (success, failure)

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

启用文件附件支持
附件设置配置
服务器端点（saveUrl、removeUrl）
文件类型限制与过滤
文件大小限制（默认30MB）
SaveFormat枚举（Blob vs Base64）及优势与使用场景
自定义存储路径（用于CDN/云存储的path属性）
拖拽文件上传
最大文件数量限制
文件预览模板
附件模板
attachmentClick事件（用于自定义文件交互：预览、下载、元数据）
attachedFile属性（用于预填充带文件的消息）
上传事件处理（成功、失败）

Methods and Programmatic Control

方法与编程控制

📄 Read: references/methods-and-programmatic-control.md

addMessage() - Add new messages programmatically
updateMessage() - Edit existing messages
scrollToBottom() - Scroll to latest messages
scrollToMessage(messageId) - Navigate to specific message (pinned messages, search results, deep linking)
focus() - Set focus to chat input programmatically (auto-focus, modal close, command execution)
ViewChild component access
Accessing chat instance for direct control

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

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

Globalization and Localization

全球化与本地化

📄 Read: references/globalization-and-localization.md

Localization (L10n) and i18n support
Typing indicator translations
Multiple language support
Right-to-Left (RTL) layout for Arabic, Hebrew, Persian
Locale configuration
Language-specific string customization

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

本地化（L10n）与i18n支持
输入状态提示翻译
多语言支持
阿拉伯语、希伯来语、波斯语的从右到左（RTL）布局
区域设置配置
特定语言的字符串定制

Advanced Features

高级功能

📄 Read: references/advanced-features.md

State persistence with enablePersistence (localStorage, cross-tab sync, browser refresh protection)
Custom persistence implementations for sensitive data
Load on demand for large message histories (1000+ messages)
Mention integration with @character
Trigger character customization
Predefined mentions in messages
mentionSelect event handling
Message status tracking (sent, delivered, read)
Time breaks between messages for date organization

📄 阅读： references/advanced-features.md

状态持久化（enablePersistence，支持localStorage、跨标签页同步、浏览器刷新保护）
敏感数据的自定义持久化实现
大消息历史（1000+条消息）的按需加载
带@字符的用户提及集成
触发字符定制
消息中的预定义提及
mentionSelect事件处理
消息状态跟踪（已发送、已送达、已读）
消息间的时间间隔分隔

Bot Integrations

机器人集成

📄 Read: references/bot-integrations.md

Google Dialogflow integration for AI conversations
Microsoft Bot Framework integration with Azure
Direct Line API configuration
Token server setup for security
Backend API configuration
Secure credential handling
Bot response message handling
Session management

📄 阅读： references/bot-integrations.md

集成Google Dialogflow实现AI对话
集成Microsoft Bot Framework与Azure
Direct Line API配置
安全令牌服务器设置
后端API配置
安全凭证处理
机器人回复消息处理
会话管理

Quick Start Example

快速入门示例

Here's a minimal example to get started:

typescript

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

Installation:

bash

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

CSS Import (src/styles.css):

css

@import "../node_modules/@syncfusion/ej2-base/styles/material3.css";
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-angular-interactive-chat/styles/material3.css';

以下是一个极简入门示例：

typescript

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

安装：

bash

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

CSS导入（src/styles.css）：

css

@import "../node_modules/@syncfusion/ej2-base/styles/material3.css";
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-angular-interactive-chat/styles/material3.css';

Key Components and Props

核心组件与属性

Core Component:

```
<ejs-chatui>
```
- Main chat container
- ```
[user]
```
  - Current user model (UserModel)
- ```
[messages]
```
  - Message collection
- ```
headerText
```
  - Header title
- ```
[headerToolbar]
```
  - Header toolbar with custom actions
- ```
[height]
```
  /
```
[width]
```
  - Dimensions
- ```
[enableAttachments]
```
  - File upload support
- ```
[enablePersistence]
```
  - State persistence across sessions
- ```
[enableRtl]
```
  - Right-to-left layout
- ```
[attachmentSettings]
```
  - File upload configuration
- ```
[messageToolbarSettings]
```
  - Message-level toolbar
- ```
[suggestions]
```
  - Quick reply suggestions
- ```
[suggestionTemplate]
```
  - Custom suggestion rendering

Message Element:

```
<e-message>
```
- Individual message
- ```
text
```
  - Message content
- ```
[author]
```
  - User who sent message
- ```
[timeStamp]
```
  - Message timestamp
- ```
[timeStampFormat]
```
  - Custom timestamp format
- ```
[isPinned]
```
  - Pin importance
- ```
[replyTo]
```
  - Thread context (MessageReplyModel)
- ```
[isForwarded]
```
  - Forwarded indicator
- ```
[attachedFile]
```
  - Pre-populated file attachments (FileInfo)
- ```
[status]
```
  - Message delivery status (MessageStatusModel)
- ```
[mentionUsers]
```
  - Users mentioned in message

User Model Properties:

```
id
```
- Unique user identifier
```
user
```
- Display name
```
avatarUrl
```
- Avatar image
```
avatarBgColor
```
- Avatar background color
```
statusIconCss
```
- Presence status icon

核心组件：

```
<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
```
- 在线状态图标

Common Use Cases

常见使用场景

1. Customer Support Chat

Configure header with support team name
Enable file attachments for screenshots/documents
Use message status for delivery tracking
Integrate with Dialogflow for AI-powered responses

2. Team Messaging App

Multiple users with presence status
Mention teammates with @mentions
Pin important decisions/announcements
Use timestamp format for timezone support

3. AI Assistant

Integrate with Microsoft Bot Framework or Dialogflow
Show typing indicator while bot responds
Suggest quick replies with suggestions array
Handle bot-specific message formatting

4. Load Performance

Enable load on demand for 1000+ message conversations
Implement auto-scroll for smooth scrolling
Use compact mode to reduce vertical space
Lazy load attachments and media

5. Internationalization (i18n)

Provide localized typing indicators ("X is typing")
Enable RTL for Arabic/Hebrew/Persian users
Customize date/time format per locale
Translate button labels and placeholders

1. 客户支持聊天

配置带支持团队名称的页眉
启用文件附件以支持截图/文档上传
使用消息状态跟踪送达情况
集成Dialogflow实现AI驱动回复

2. 团队消息应用

带在线状态的多用户支持
使用@提及功能提及队友
置顶重要决策/公告
支持时区的时间戳格式

3. AI助手

集成Microsoft Bot Framework或Dialogflow
机器人回复时显示输入状态提示
使用suggestions数组提供快捷回复
处理机器人特定的消息格式

4. 加载性能优化

为1000+条消息的对话启用按需加载
实现自动滚动以获得流畅体验
使用紧凑模式减少垂直空间
懒加载附件与媒体内容

5. 国际化（i18n）

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