syncfusion-react-ai-assistview

Syncfusion React AI AssistView 组件

组件概述

Syncfusion React AI AssistView 组件是一款功能全面的交互式聊天组件，专为构建 AI 驱动的对话界面而设计。它提供：

核心能力

• 提示词-响应管理：通过自动收集数据来管理对话历史
• 实时流式传输：逐字符流式传输 AI 响应，实现实时打字效果
• 思维链：通过思考块可视化 AI 推理过程，并支持多阶段工作流
• 模板系统：自定义每个 UI 元素（横幅、提示词项、响应、建议、页脚）
• 多视图支持：在对话助手视图和自定义内容视图之间切换
• 语音集成：内置语音转文本（语音输入）和文本转语音（语音输出）
• 文件附件：上传文件并将其包含在提示词中
• 高级工具栏：可为页眉、页脚、响应和提示词配置工具栏
• 遥测跟踪：跟踪 AI 交互指标（时长、工具调用、令牌、模型信息），并在每条响应上通过内置报告提示框显示
• 提及：通过触发字符（@、/）从已配置的数据源引用项目，支持筛选、高亮和可自定义模板
• AI 服务集成：直接集成 OpenAI、Azure OpenAI 等 AI 服务
• 事件驱动架构：为提示词提交、变更和组件生命周期提供钩子

主要功能

• Markdown 支持：通过 Markdown 解析将 AI 响应渲染为格式化 HTML
• 对话历史：自动跟踪所有提示词和响应
• 建议系统：显示有用的提示词建议，为用户提供引导
• 头像自定义：自定义用户和 AI 图标/头像
• 滚动管理：自动滚动或使用手动滚动到底部按钮
• 清除功能：清除当前提示词或整个对话
• 重新生成响应：无需重新提交查询，即可为现有提示词请求其他 AI 响应
• 响应式设计：支持桌面和移动设备，并采用响应式布局
• 遥测报告：每条响应的工具栏上均内置遥测按钮，支持配置指标、通过 beforeReport 自定义报告、支持自定义属性，以及跟踪每条响应的令牌/模型
• 提示词编辑器中的提及：可配置触发字符、本地或远程数据源、字段映射、筛选类型、高亮、弹出窗口尺寸、显示/项目/无记录模板，以及用于自定义处理的 mentionSelect 事件

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-react-interactive-chat package
• 添加 CSS 主题导入
• 创建基本组件初始化
• 将组件渲染到 DOM
• 查看首个可正常运行的组件示例

配置要点

📄 阅读： references/configuration-essentials.md

• 设置初始提示词文本和占位符
• 配置提示词建议和建议标题
• 自定义用户和 AI 头像图标
• 控制清除按钮的可见性
• 启用/禁用滚动到底部功能
• 通过 refs 管理组件实例
• 设置组件尺寸（高度和宽度）
• 应用自定义 CSS 类进行样式设置
• 控制页眉可见性
• 配置全球化（区域设置、RTL 支持）
• 启用跨会话状态持久化

对话管理

📄 阅读： references/conversation-management.md

• 使用预配置的对话数据进行初始化
• 添加响应（字符串或对象格式）
• 访问和管理对话历史
• 使用 PromptModel 数据结构
• 在响应中渲染 Markdown
• 持久化和恢复对话

事件与交互

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

• 处理组件生命周期（created 事件）
• 响应提示词提交（promptRequest 事件）
• 跟踪提示词文本更改（promptChanged 事件）
• 访问详细的事件参数（PromptChangedEventArgs、PromptRequestEventArgs）
• 以编程方式取消提示词提交
• 处理长时间运行操作的停止响应事件
• 动态修改建议和工具栏项目
• 实现事件驱动的工作流
• 通过事件处理程序与 AI 服务集成

工具栏自定义

📄 阅读： references/toolbar-customization.md

• 配置四种工具栏类型（header、footer、response、prompt）
• 添加自定义工具栏项目
• 控制工具栏位置（Inline 或 Bottom）
• 自定义工具栏图标
• 处理项目点击事件
• 配置所有 ToolbarItemModel 属性（align、cssClass、disabled、tabIndex、template、type、visible）
• 创建自定义工具栏项目模板
• 动态控制项目的可见性和启用状态
• 设置键盘导航的 Tab 顺序
• 管理附件按钮行为
• 为多个 AI 生成的回复启用重新生成回复功能
• 通过上一个／下一个按钮浏览重新生成的回复

文件附件

📄 阅读： references/file-attachments.md

• 启用文件附件支持
• 配置上传端点（saveUrl、removeUrl）
• 限制文件类型（allowedFileType）
• 设置文件大小限制（maxFileSize）
• 限制附件数量（maximumCount）
• 通过 attachedFiles 数组（FileInfo 接口）访问附件
• 处理附件生命周期事件（beforeAttachmentUpload、attachmentUploadSuccess、attachmentUploadFailure、attachmentRemoved、attachmentRemoving）
• 在上传前验证文件
• 使用预先附加的文件初始化提示词
• 处理服务器端文件
• 自定义附件模板（attachmentTemplate）

自定义视图

📄 阅读： references/custom-views.md

• 创建多个视图（Assist 和 Custom 类型）
• 设置视图名称和图标
• 定义特定于视图的模板
• 配置 activeView 属性以设置初始视图
• 以编程方式切换视图
• 跨会话保留活动视图
• 根据用户角色或状态有条件地设置初始视图
• 并排显示内容面板
• 多视图布局的使用场景

模板系统

📄 阅读： references/templating-system.md

• 自定义横幅模板（欢迎内容）
• 创建提示词项目模板（用户消息显示）
• 设计回复项目模板（AI 回复显示）
• 在生成回复期间，使用 responseAnimationTemplate 呈现自定义加载动画
• 构建建议项目模板
• 创建自定义页脚模板
• 访问模板上下文数据

AI 服务集成

📄 阅读： references/ai-integration-setup.md

• 与 Azure OpenAI、OpenAI、Gemini、Claude 集成
• 配置 API 凭据和身份验证
• 处理实时提示词
• 流式传输回复，实现实时打字效果
• 使用 marked 库解析 Markdown 回复
• 错误处理和速率限制
• API 密钥的安全注意事项

生成式 UI

📄 阅读： references/generative-ui.md

• 使用 registerToolUI() 方法注册自定义工具
• 配置用于呈现的工具模板和处理程序
• 通过 blocks 属性添加交互元素（图表、卡片、自定义工具）
• 在单条 AI 回复中呈现多个工具
• 配置 AI 系统提示词，以生成结构化 JSON
• 将 AI 服务与生成式 UI 块集成

语音功能

📄 阅读： references/speech-capabilities.md

• 启用语音转文本（语音输入）
• 配置语音识别语言
• 处理说话时生成的临时转录文本
• 通过 Web Speech API 实现文本转语音（语音输出）
• 将 AI 响应转换为语音
• 使用 textToSpeechSettings（language、speechPitch、speechRate、volume、voice）自定义 TTS
• 自定义按钮标签和图标
• 处理语音事件（start、stop、transcript、error）
• 浏览器兼容性说明

思维链

📄 阅读： references/chain-of-thoughts.md

• 通过思考区块可视化 AI 推理过程
• 配置包含阶段和状态更新的思考区块
• 添加多阶段推理工作流（completed、inprogress、failed）
• 自定义思考区块模板
• 添加带有徽标和工具提示的内联上下文项
• 处理用于交互式上下文的 editableContextClicked 事件
• 配置阶段级别的项目模板
• 实时流式传输思考区块，直观呈现推理过程

方法和 API

📄 阅读： references/methods-and-apis.md

• 使用 addPromptResponse() 方法
• 使用 executePrompt() 动态执行提示词
• 以编程方式滚动到底部
• 通过 refs 访问组件实例
• 管理组件状态
• 常见模式和注意事项

遥测

📄 阅读： references/telemetry.md

• 通过 telemetrySettings.enable 启用遥测跟踪
• 在每条响应的工具栏上显示内置遥测按钮，并通过悬停提示显示报告
• 配置 metrics 筛选器，以限制提示中的行并调整其顺序（status、duration、toolCalls、streamingChunks、model、inputTokens、outputTokens、totalTokens、reasoningTokens、cachedInputTokens）
• 通过 beforeReport 事件拦截报告以修改报告、添加 customAttributes，或返回 null 以抑制报告
• 将 TelemetryData（模型、输入/输出令牌、推理/缓存令牌）传递给 addPromptResponse()，将 AI 使用详情合并到报告中
• 通过 TelemetryData.customAttributes 显示领域专属指标（无论 metrics 筛选器如何设置，都会始终显示）
• 了解自动测量的指标与外部提供的指标，以及它们的显示优先级
• 使用 TelemetrySettingsModel、TelemetryData 和 TelemetryReport 类型

提及

📄 阅读： references/mentions.md

• 通过 mentions 属性（提及设置数组）在提示词编辑器中启用提及功能
• 配置触发字符（mentionChar），例如 @ 或 /；同一组件可配置多个提及设置
• 将本地数组（字符串/对象/数字/布尔值）或 Syncfusion DataManager 用作本地/远程数据源
• 使用 fields 属性映射基于对象的数据源（默认值 { text: 'text', value: 'id' }）
• 使用 query 属性（来自 @syncfusion/ej2-data 的 Query）应用其他数据操作
• 通过 filterType（Contains、StartsWith、EndsWith）选择文本匹配方式
• 使用 highlight 突出显示匹配文本，并通过 showMentionChar 控制是否显示触发字符
• 使用 displayTemplate 自定义提示词中的提及内容，并使用 itemTemplate 自定义建议项
• 使用 popupWidth / popupHeight 设置弹出窗口大小，并使用 noRecordsTemplate 自定义空状态
• 通过 mentionSelect 事件处理提及选择，以访问所选项的数据

---

快速入门示例

import { AIAssistViewComponent, PromptRequestEventArgs, TelemetrySettingsModel } from '@syncfusion/ej2-react-interactive-chat';
import * as React from 'react';
import * as ReactDOM from "react-dom";

function App() {
    const assistInstance = React.useRef<AIAssistViewComponent>(null);
    
    // Enable the built-in telemetry button on every response toolbar
    const telemetrySettings: TelemetrySettingsModel = { enable: true };
    const onPromptRequest = (args: PromptRequestEventArgs) => {
        setTimeout(() => {
            let defaultResponse = 'For real-time AI processing, connect to your preferred service (OpenAI, Azure OpenAI, etc.).';
            assistInstance.current.addPromptResponse(defaultResponse);
        }, 1000);
    };
  
    return (
        <AIAssistViewComponent 
            id="aiAssistView" 
            ref={assistInstance} 
            promptRequest={onPromptRequest}
            prompt={'Welcome! How can I help?'}
            promptSuggestions={['Ask about features', 'Get started guide']}
            telemetrySettings={telemetrySettings}
        />
    );
}

ReactDOM.render(<App />, document.getElementById('container'));

---

常见模式

模式 1：带建议的基础聊天

创建带有预定义建议的简单对话界面：

• 启用提示词建议，引导用户交互
• 使用简单响应处理 promptRequest 事件
• 自动显示对话历史

模式 2：AI 服务集成

连接真实 AI 服务，提供智能响应：

• 使用 promptRequest 事件获取用户输入
• 使用提示词文本调用 AI API
• 逐字符流式传输响应，呈现实时效果
• 解析 Markdown 响应，生成格式化输出

模式 3：多视图仪表板

将聊天与辅助内容结合：

• 创建用于对话的 Assist 视图
• 添加用于设置／侧边栏的 Custom 视图
• 根据用户交互切换 activeView
• 在视图之间共享数据

模式 4：语音聊天

通过语音启用免手动交互：

• 启用 speechToTextSettings 以捕获语音
• 配置文本转语音，为响应生成音频
• 使用工具栏中的语音控制按钮
• 处理语音事件以反馈状态

模式 5：附带文件的提示词

支持在提示词中上传文件：

• 使用 enableAttachments 属性启用附件
• 配置附件端点和文件限制
• 将文件数据纳入提示词上下文
• 将文件发送到后端 API

模式 6：思维链推理

可视化 AI 的逐步推理过程：

• 注入 AssistThinking 模块，以支持思考区块
• 创建包含多个推理阶段的思考区块
• 使用状态更新（completed、inprogress、failed）实时展示进度
• 与文本响应一同流式传输思考区块
• 添加上下文项，突出显示引用的工具或文件
• 自定义区块和阶段模板，打造品牌化样式

模式 7：启用遥测的 AI 助手

在内置工具提示中显示每条响应的 AI 指标：

• 设置 telemetrySettings={{ enable: true }}，在每条响应上显示遥测按钮
• 使用 telemetrySettings.metrics 限定要收集的指标，并固定其在工具提示中的显示顺序
• 将 TelemetryData 传递给 addPromptResponse()，以将模型、令牌、推理和缓存用量合并到报告中
• 使用 beforeReport 回调添加 customAttributes（region、tenant、sessionId、feature），或返回 null 以抑制报告
• status 和 duration 始终保留；无论 metrics 筛选条件如何，都会始终显示 customAttributes

模式 8：由提及驱动的提示词编辑器

让用户在提示词中引用 Agent 或斜杠命令：

• 将 mentions 设置为一组配置项，每项都有自己的 mentionChar（例如，用 @ 表示 Agent，用 / 表示命令）
• 通过 dataSource 提供本地或远程数据，并使用 fields: { text, value } 映射字段
• 使用 filterType、highlight、showMentionChar、popupWidth 和 popupHeight 调整建议弹出窗口
• 使用 displayTemplate、itemTemplate 和 noRecordsTemplate 自定义外观
• 通过 mentionSelect 事件响应选择，以驱动路由、分析或下游 AI 上下文

模式 9：自定义响应加载动画

用品牌动画替换默认的输入指示器：

• 将函数、字符串或 JSX 元素传递给 responseAnimationTemplate，以在生成响应时进行渲染
• 用户提交提示词后，模板会立即显示；当 addPromptResponse()（或取消操作）完成后，会自动移除
• 结合品牌 CSS，渲染脉冲网格、旋转图标、阶段标签（例如“正在搜索知识库……”）或骨架占位符

---

关键属性和配置

基本属性

• promptRequest：用户提交提示词时触发的事件处理程序
• prompt：提示词输入框中的初始／默认文本
• promptPlaceholder：输入区域的占位文本
• promptSuggestions：建议提示词数组
• prompts：预配置的对话数据

自定义 Props

• promptIconCss：用户头像的 CSS 类
• responseIconCss：AI 头像的 CSS 类
• showClearButton：显示/隐藏清除按钮（默认值：false）
• showHeader：显示/隐藏组件标题栏（默认值：true）
• enableScrollToBottom：显示滚动到底部按钮（默认值：true）
• height：组件高度（string | number，默认值：'100%'）
• width：组件宽度（string | number，默认值：'100%'）
• cssClass：用于设置样式的自定义 CSS 类
• activeView：当前显示的视图索引（number，默认值：0）

模板 Props

• bannerTemplate：欢迎横幅内容
• promptItemTemplate：用户消息显示模板
• responseItemTemplate：AI 回复显示模板
• responseAnimationTemplate：自定义加载指示器/动画，在回复生成期间替代回复显示（添加回复或取消请求后会自动移除）
• promptSuggestionItemTemplate：建议项样式
• footerTemplate：自定义提示词输入区域

高级 Props

• enableAttachments：启用文件上传（默认值：false）
• attachmentSettings：文件上传配置
• speechToTextSettings：语音输入配置
• textToSpeechSettings：文本转语音配置
• toolbarSettings：标题栏工具栏配置
• footerToolbarSettings：页脚工具栏配置
• responseToolbarSettings：回复操作工具栏
• promptToolbarSettings：提示词工具栏配置
• blockTemplate：思考块和其他回复块的自定义模板
• itemTemplate：思考块中各个阶段的自定义模板
• locale：本地化/全球化设置（默认值：'en-US'）
• enableRtl：启用从右到左的渲染（默认值：false）
• enablePersistence：启用状态持久化（默认值：false）

遥测 Props

• telemetrySettings：遥测配置对象（TelemetrySettingsModel），包含 enable 标志、metrics 筛选器和 beforeReport 回调

提及 Props

• mentions：提及设置数组——每个条目配置 mentionChar、dataSource、fields、query、filterType、highlight、showMentionChar、popupWidth、popupHeight、displayTemplate、itemTemplate 和 noRecordsTemplate

生成式 UI Props

• blocks：回复块数组（TextBlock、ToolBlock、ThinkingBlock），用于在回复中渲染动态 UI 元素
• registerToolUI()：用于注册自定义工具模板的公共方法，可在 AI 回复中渲染交互式组件（图表、卡片、自定义工具）

事件 Props

• created：组件生命周期事件
• promptRequest：提示词提交事件
• promptChanged：提示词文本更改事件
• stopRespondingClick：停止按钮点击事件
• beforeAttachmentUpload：文件上传前事件
• attachmentUploadSuccess：文件上传成功事件
• attachmentUploadFailure：文件上传失败事件
• attachmentRemoved：文件移除后事件
• attachmentRemoving：文件移除前事件（可通过 args.cancel 确认、记录或取消移除操作）
• editableContextClicked：用户点击思考块中的内嵌上下文项时触发
• mentionSelect：用户从提及建议弹出窗口中选择条目时触发（所选条目数据位于 args.itemData）- editableContextClicked：用户点击思考块中的内嵌上下文项时触发

---

常见用例

集成 AI 的聊天机器人

构建连接到 OpenAI 或 Azure 服务的客户服务聊天机器人：

1. 设置带有建议项的组件
2. 处理 promptRequest 以向 AI API 发送请求
3. 流式传输回复，提供实时反馈
4. 使用模板打造品牌外观

语音助手

创建免手动操作的语音交互：

1. 启用 speechToTextSettings
2. 配置文本转语音工具栏按钮
3. 处理语音事件以获取状态
4. 在语音采集期间提供视觉反馈

文件分析聊天

允许用户上传并讨论文件：

1. 启用附件
2. 配置文件限制（类型、大小、数量）
3. 将文件与提示词一起发送到后端
4. 在对话中显示文件信息

多功能仪表板

将聊天与设置和内容结合起来：

1. 创建多个视图（Assist + 自定义）
2. 使用模板设置自定义视图内容
3. 实现视图切换逻辑
4. 在视图间共享对话状态

支持思考的推理助手

展示 AI 处理复杂任务的推理过程：

1. 注入 AssistThinking 模块以支持思考块
2. 配置包含多个阶段的思考块
3. 流式传输块并更新状态（进行中 → 已完成）
4. 在各阶段添加上下文项（工具、文件、搜索结果）
5. 自定义块模板，以透明地展示推理过程
6. 处理 editableContextClicked，以便进行交互式探索

结合动态交互式工具的生成式 UI

在 AI 回复中渲染动态交互组件和自定义工具：

1. 使用 registerToolUI() 注册自定义工具（图表、卡片、表单）
2. 配置工具模板，以实现响应式 UI 渲染
3. 定义包含 TextBlock 和 ToolBlock 组合的 blocks 数组
4. 配置 AI 系统提示词，以生成结构化 JSON
5. 在 addPromptResponse() 调用中发送工具块
6. 利用 AI 生成的 UI 元素，创建丰富的交互体验

启用遥测的 AI 助手

跟踪并显示每条回复的 AI 交互指标：

1. 设置 telemetrySettings={{ enable: true }}，即可在每条回复的工具栏上显示遥测按钮
2. 使用 telemetrySettings.metrics 限制采集的指标，并固定这些指标在工具提示中的显示顺序
3. 将 TelemetryData 传递给 addPromptResponse()，以便将模型、令牌、推理和缓存用量合并到报告中
4. 使用 beforeReport 回调添加 customAttributes（区域、租户、sessionId、功能），或返回 null 以禁止生成报告
5. 通过 TelemetryData.customAttributes 展示特定领域的指标（无论 metrics 筛选条件如何，这些指标始终显示）
6. 复用 totalTokens 自动计算、时长格式化（毫秒 / 秒，保留 2 位小数）和重新生成流程语义

由提及触发的提示词编辑器

在提示词中引用 Agent、斜杠命令或任何数据源：

1. 将 mentions 属性配置为提及设置数组，每项设置都包含自己的 mentionChar（@、/ 等）
2. 提供 dataSource（本地数组或 Syncfusion DataManager），并使用 fields: { text, value } 映射字段
3. 使用 filterType（Contains、StartsWith、EndsWith）调整匹配方式，并启用 highlight 提供视觉反馈
4. 使用 displayTemplate、itemTemplate、noRecordsTemplate、popupWidth 和 popupHeight 自定义外观
5. 使用 showMentionChar 控制插入的提及内容是否包含触发字符
6. 使用 query 属性（来自 @syncfusion/ej2-data）应用其他数据操作
7. 处理 mentionSelect 事件，以响应用户的选择（路由、分析、下游 AI 上下文等）

自定义回复加载动画

在生成回复时，用品牌专属动画替换默认的输入指示器：

1. 定义 responseAnimationContent 函数（或字符串 / JSX），使其返回加载 UI
2. 将其传递给 <AIAssistViewComponent responseAnimationTemplate={responseAnimationContent} />
3. 提交提示词后（或执行 executePrompt 后）会立即显示动画；当 addPromptResponse() 执行完成后，动画会自动移除
4. 使用 CSS 为动画添加样式——常见形式包括脉冲网格、旋转器、阶段标签或骨架占位符

---