syncfusion-javascript-chat-ui

Syncfusion TypeScript Chat UI の実装

概要

Chat UI コンポーネントは、カスタマーサポートチャット、AI チャットボット、メッセージングシステム、共同コミュニケーションツールなどの会話型アプリケーションを構築するための、モダンで機能豊富なインターフェイスを提供します。

Syncfusion Chat 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 など）
• Chat 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）

@Mention の統合

📄 参照： 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）
• メッセージごとのツールバー項目（コピー、返信、ピン留め、削除）
• カスタムツールバー項目
• メッセージツールバーのクリックイベント
• コンパクトモード（enableCompactMode）- すべてのメッセージを左揃えにする
• CSS のカスタマイズ（cssClass）
• テーマとの統合
• RTL サポート（enableRtl）
• ローカライズ（locale）
• 永続化（enablePersistence）
• アクセシビリティ機能

---

クイックスタート

基本的なチャット UI のセットアップ

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

@Mention のサポートを追加する

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[]	@メンションの対象となるユーザー
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	ローカライズのカルチャ

---

一般的なユースケース

カスタマーサポートチャット

• エージェントと顧客のリアルタイムの会話
• エージェントの対応状況を示す入力インジケーター
• スクリーンショットやドキュメント用のファイル添付
• メッセージのステータス（送信済み、配信済み、既読）
• よくある回答のクイック返信候補

AI チャットボットのインターフェース

• ユーザーとボットのメッセージを区別
• AI の処理中に入力インジケーターを表示
• 回答案とクイックアクション
• リッチな回答を表示するメッセージテンプレート
• ウェルカムメッセージを表示する空の状態

チームコラボレーションツール

• チームメンバーへの@メンション
• メッセージへの返信とスレッド
• 重要なメッセージをピン留め
• プレビュー付きのファイル共有
• 長い会話をオンデマンドで読み込み

ライブヘルプウィジェット

• 埋め込みウィジェット向けのコンパクトモード
• エージェント情報を含むカスタムヘッダー
• 入力状況を表示するフッター
• 最新のメッセージまで自動スクロール
• 最小化／最大化機能

ドキュメントの Q&A

• ユーザーを明確に区別した質問と回答の形式
• コードスニペットの添付
• 会話セッションごとの時間区切り
• コピー機能付きのメッセージツールバー
• 特定のメッセージの検索とスクロール