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 クラスを使ったヘッダーアイコンのカスタマイズ
• カスタムアクション付きヘッダーツールバー（通話、ビデオ、設定、プロフィール）
• 項目と itemClicked イベントを含む ToolbarSettingsModel の設定
• フッターの表示と制御
• カスタムレイアウト用のフッターテンプレート

イベントとインタラクション

📄 参照： 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）とそれぞれの利点および使用例
• CDN／クラウドストレージ向けの path プロパティを使ったカスタム保存パス
• ドラッグ＆ドロップによるファイルアップロード
• ファイル数の上限設定
• ファイルプレビュー用テンプレート
• 添付ファイル用テンプレート
• カスタムのファイル操作（プレビュー、ダウンロード、メタデータ）を実装するための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 イベントの処理
• メッセージステータスの追跡（送信済み、配信済み、既読）
• 日付整理のためのメッセージ間の時間区切り

ボット連携

📄 読む: references/bot-integrations.md

• AI との会話に向けた Google Dialogflow との連携
• Azure を使った Microsoft Bot Framework との連携
• Direct Line API の設定
• セキュリティを確保するためのトークンサーバーのセットアップ
• バックエンド API の設定
• 認証情報の安全な取り扱い
• ボット応答メッセージの処理
• セッション管理

---

クイックスタートの例

始めるための最小限の例を紹介します。

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. カスタマーサポートチャット

• サポートチーム名を含むヘッダーを設定
• スクリーンショットやドキュメントを添付できるようにする
• 配信状況の追跡にメッセージステータスを使用
• AI による応答のために Dialogflow と統合

2. チームメッセージングアプリ

• プレゼンスステータス付きの複数ユーザー
• @メンションでチームメイトにメンション
• 重要な決定事項やお知らせを固定
• タイムゾーンに対応するためにタイムスタンプ形式を使用

3. AI アシスタント

• Microsoft Bot Framework または Dialogflow と統合
• ボットの応答中に入力中インジケーターを表示
• 候補の配列でクイック返信を提案
• ボット固有のメッセージ形式に対応

4. 読み込みパフォーマンス

• 1000 件以上のメッセージを含む会話では、必要に応じた読み込みを有効化
• スムーズなスクロールのために自動スクロールを実装
• コンパクトモードを使用して縦方向のスペースを削減
• 添付ファイルやメディアを遅延読み込み

5. 国際化（i18n）

• ローカライズされた入力中インジケーター（「X さんが入力中」）を表示
• アラビア語、ヘブライ語、ペルシア語のユーザー向けに RTL を有効化
• ロケールごとに日付と時刻の形式をカスタマイズ
• ボタンのラベルとプレースホルダーを翻訳

---