syncfusion-angular-ai-assistview

Syncfusion Angular AI AssistView 组件

组件概述

Syncfusion AI AssistView 是一个功能强大的 Angular 组件，可提供开箱即用的界面，用于构建对话式 AI 应用。

主要功能：

• 对话管理 - 管理提示词-响应对，并支持历史记录、持久化和 Markdown 渲染
• AI 服务集成 - 连接 OpenAI、Gemini、Ollama、Lite-LLM 和 MCP 提供方，并支持流式传输
• 思维链 - 通过可注入的 AssistThinking 模块，将 AI 推理可视化为可折叠的思考区块，并支持多阶段动态状态更新
• 生成式 UI - 使用 blocks 和 registerToolUI 在 AI 响应中呈现交互式工具、图表和自定义组件
• 语音功能 - 内置语音转文本功能，提供 11 个可配置属性和 4 个事件
• 工具栏系统 - 四种工具栏类型（页眉、提示词、响应、页脚），支持自定义操作和标记指令
• 遥测 - 内置每条响应的遥测按钮，可显示指标（状态、持续时间、工具调用、令牌、模型）；提供 beforeReport 事件以便自定义，并支持在 addPromptResponse 中传入 TelemetryData 参数来显示使用数据
• 提及 - 在提示词编辑器中提供基于触发字符的提及选择器，支持本地或 DataManager 数据源、筛选、高亮、弹出窗口尺寸设置，以及显示、项目和无记录模板
• 视图管理 - 支持多个视图，可通过 activeView 进行编程控制和动态切换
• 事件与交互 - 提供类型化事件参数（PromptRequestEventArgs、PromptChangedEventArgs、StopRespondingEventArgs）
• 文件附件 - 支持文件上传和类型/大小限制，并提供完整的附件生命周期事件：beforeAttachmentUpload、attachmentUploadSuccess、attachmentUploadFailure、attachmentRemoved、attachmentRemoving 和 attachmentClick
• 模板 - 可灵活自定义提示词、响应、建议、横幅、页脚和响应动画，包括用于品牌化加载状态的逐条响应 responseAnimationTemplate
• 方法 - 以编程方式添加/更新响应、执行提示词并控制组件行为
• 全球化 - 全面支持 RTL 和 12 种以上语言的本地化，并采用基于区域设置的格式
• 可自定义 UI - 支持自定义高度、宽度、CSS 类、HTML 属性和主题

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和依赖项设置
• Angular 环境配置
• 基本组件初始化
• CSS 导入和主题配置
• 第一个可运行示例

核心功能与对话管理

📄 阅读： references/assist-view-basics.md

• 设置提示词文本和占位符
• 管理提示词-响应集合
• Markdown 响应渲染
• 配置提示词建议
• 自定义用户和助手头像
• UI 控件（清除按钮、滚动到底部）
• 组件配置（高度、宽度、showHeader、cssClass、htmlAttributes）
• 使用 enablePersistence 持久化状态
• 全球化与本地化（使用 locale 属性支持 12 种以上语言）
• 使用 enableRtl 支持阿拉伯语、希伯来语、波斯语和乌尔都语的 RTL 布局

外观与样式

📄 阅读： references/appearance-customization.md

• 设置组件宽度和高度
• 应用自定义 CSS 类
• 自定义主题
• 响应式设计模式

多视图与自定义内容

📄 阅读： references/custom-views.md

• 添加自定义视图模型
• 视图类型（Assist 和 Custom）
• 视图配置与命名
• 在一个组件中管理多个视图
• 使用 activeView 属性以编程方式切换视图
• 动态视图导航模式
• 视图历史记录与面包屑导航
• 基于工作流的视图切换
• 根据用户角色有条件地显示视图

编程控制与方法

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

• 添加提示词响应（字符串和对象
• 完整的事件参数参考部分
• PromptRequestEventArgs，包含 6 个属性（prompt、attachedFiles、promptSuggestions、cancel 等）
• PromptChangedEventArgs，包含 5 个属性（value、previousValue、element、event）
• 用于取消响应的 StopRespondingEventArgs
• 带有 FileInfo 接口的 AttachmentClickEventArgs
• 涵盖所有事件类型格式的生产就绪示例）
• 动态执行提示词
• 响应处理模式
• 编程式交互

思维链

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

• 使用可注入的 AssistThinking 模块启用推理可视化
• 思考块配置（blocks 属性、blockType: 'thinking'）
• 使用 addPromptResponse 和 isFinalUpdate 流式传输多步骤推理
• 使用 stages 数组和 ThinkingStage 属性添加阶段
• 阶段状态指示器（completed、inprogress、failed）
• 使用 editableContext 和 {index} 占位符添加内联上下文项
• 处理 editableContextClicked 事件
• 使用 blockTemplate 和 itemTemplate 自定义渲染

生成式 UI

📄 阅读： references/generative-ui.md

• 使用 registerToolUI 注册自定义工具（toolName、template、handler）
• 配置工具模板和交互式处理函数
• 通过 addPromptResponse 向响应添加 tool 块（toolName、props）
• 配置 AI 服务系统提示词，使其返回结构化的 blocks JSON
• 在工具交互后使用 executePrompt 链式执行后续提示词
• 完整的生产示例：使用自定义工具和基于图表的工具构建食谱

文本转语音

📄 阅读： references/text-to-speech.md

• 使用 e-assist-audio 响应工具栏项启用内置文本转语音
• 通过浏览器的 SpeechSynthesisUtterance API 朗读 AI 响应
• 使用 textToSpeechSettings 自定义语音行为（language、speechPitch、speechRate、volume、voice）

遥测

📄 阅读： references/telemetry.md

• 使用 telemetrySettings.enable 启用每条响应的遥测
• 使用 metrics 数组筛选捕获的指标（status、duration、toolCalls、streamingChunks、model、inputTokens、outputTokens、totalTokens、reasoningTokens、cachedInputTokens）
• 使用 beforeReport 事件自定义报告（修改、通过 customAttributes 扩充，或返回 null 以禁止报告）
• 通过传递给 addPromptResponse 的可选 TelemetryData 参数提供模型和令牌用量
• 通过 TelemetryData.customAttributes 传递特定领域的指标
• 关键行为：轮次跟踪、遥测按钮状态、时长格式、指标筛选优先级和重新生成流程

提及

📄 阅读： references/mentions.md

• 使用 mentionChar 配置提及触发字符（例如，使用 @ 触发 Agent，使用 / 触发命令）
• 在单个组件上注册多个提及配置（mentions 数组）
• 使用本地数组或 DataManager 实例作为 dataSource 属性
• 使用 fields 映射基于对象的数据源，并使用 Query 应用其他筛选条件
• 通过 filterType（Contains、StartsWith、EndsWith）和 highlight 控制匹配行为
• 使用 showMentionChar 控制编辑器中是否显示触发字符
• 使用 popupWidth / popupHeight 自定义弹出窗口尺寸
• 使用 displayTemplate、itemTemplate 和 noRecordsTemplate 自定义渲染
• 通过 mentionSelect 事件和 MentionSelectEventArgs 响应选择

4 种工具栏类型的完整文档

• 标题工具栏（toolbarSettings）- 全局操作和导航
• 提示词工具栏（promptToolbarSettings）- 用户提示词操作
• 响应工具栏（responseToolbarSettings）- AI 响应操作
• 页脚工具栏（footerToolbarSettings）- 输入区域自定义
• 包含 10 个属性的 ToolbarItemModel 接口
• 处理 dataIndex 的 ToolbarItemClickedEventArgs
• 标签指令方式：<e-toolbarsettings>、<e-toolbaritem>
• 动态工具栏项的属性绑定方式
• 常见模式、最佳实践和故障排除est、promptChanged)
• 文件上传事件（beforeAttachmentUpload、attachmentUploadSuccess、attachmentUploadFailure、attachmentRemoved、attachmentRemoving）
• 事件参数：PromptRequestEventArgs、PromptChangedEventArgs、StopRespondingEventArgs、AttachmentClickEventArgs、RemovingEventArgs（来自 @syncfusion/ej2-inputs）
• 事件处理模式和最佳实践

文件附件

📄 阅读： references/file-attachments.md

• 文件附件配置
• 上传处理和验证
• 文件大小和类型限制
• 附件显示和管理
• 自定义附件模板（attachmentTemplate）

工具栏配置

📄 阅读： references/toolbar-items.md

• 工具栏自定义
• 内置语音转文本功能，使用 speechToTextSettings（推荐方式）
• 包含 11 个可配置属性的 SpeechToTextSettingsModel
• ButtonSettingsModel 和 TooltipSettingsModel 接口
• 4 个语音事件：onStart、onStop、transcriptChanged、onError
• 事件参数：StartListeningEventArgs、StopListeningEventArgs、TranscriptChangedEventArgs、ErrorEventArgs
• 支持 10 种以上语言代码（en-US、es-ES、fr-FR、de-DE、ja-JP 等）
• 使用 allowInterimResults 处理临时结果
• 自定义 Web Speech API 实现（替代方式）
• 语音转文本的设置与配置
• 浏览器兼容性和错误处理
• 使用 e-assist-regenerate 图标重新生成响应、响应导航 UI，以及 regeneratedResponses 属性
• 工具栏项对齐方式：通过 align 属性（Left、Center、Right）设置——所有 ToolbarItemModel 和四种工具栏类型均支持

模板与自定义渲染

📄 阅读： references/templates.md

• 模板系统概览
• 提示词模板
• 响应模板
• 响应动画模板（responseAnimationTemplate），用于在生成响应时显示品牌化的加载状态，并在调用 addPromptResponse() 后移除
• 创建自定义模板

AI 服务集成

📄 阅读： references/ai-integrations.md

• Azure OpenAI 集成设置
• Gemini 集成
• Lite-LLM 集成
• Model Context Protocol (MCP) 集成
• Ollama 集成
• 安全最佳实践和 API 管理

语音功能

📄 阅读： references/speech-features.md

• 语音转文本的设置与配置
• 文本转语音的设置与配置
• 音频处理
• 浏览器兼容性注意事项

---

方法（生成式 UI）

方法	描述
registerToolUI({ toolName, template, handler })	注册工具的渲染模板和可选的交互处理程序。在任何响应中引用该工具之前调用。
executePrompt(prompt)	以编程方式触发新的提示词/响应周期，适用于在工具交互后串联后续 AI 响应。

---

快速入门示例

下面是一个可运行的最简示例，助你快速上手：

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

@Component({
  imports: [AIAssistViewModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div ejs-aiassistview 
      id='aiAssistView'
      [promptSuggestions]="suggestions"
      (promptRequest)="onPromptRequest($event)">
    </div>
  `,
  styles: [`
    :host ::ng-deep #aiAssistView {
      height: 100vh;
    }
  `]
})
export class AppComponent {
  suggestions = [
    'What is Angular?',
    'How to create components?',
    'Explain dependency injection'
  ];

  onPromptRequest(args: any) {
    // Handle prompt and provide response
    setTimeout(() => {
      const response = 'This is a sample response from your AI service.';
      // Add response using component method
    }, 1000);
  }
}

---

常见模式

模式 1：基本对话流程

1. 使用建议初始化组件
2. 用户输入提示词
3. 触发 promptRequest 事件
4. 调用你的 AI 服务
5. 使用 addPromptResponse() 显示结果
6. 自动维护对话历史

模式 2：集成支持流式传输的 AI 服务

1. 使用 [enableStreaming]="true" 启用流式传输
2. 配置 AI 提供商凭据（OpenAI、Gemini 等）
3. 在 promptRequest 事件中，使用流式传输调用提供商 API
4. 使用 ReadableStream 接收分块响应
5. 处理 stopRespondingClick 事件以取消操作
6. 使用 addPromptResponse() 增量更新 UI

模式 3：使用 activeView 管理自定义视图

1. 定义多种视图类型（Assist、Custom）
2. 使用 [activeView]="currentIndex" 控制显示内容
3. 根据用户操作以编程方式切换视图
4. 跟踪视图历史记录，以支持前进/后退导航
5. 每个视图都可以有不同的配置
6. 为每个视图维护独立状态

模式 4：完整的工具栏配置

1. 配置标题栏工具栏以执行全局操作（新建聊天、导出、设置）
2. 设置提示词工具栏以执行用户提示词操作（编辑、复制、重试）
3. 添加响应工具栏以执行 AI 响应操作（复制、重新生成、点赞/点踩）
4. 配置页脚工具栏以执行输入操作（格式化、附件）
5. 使用标签指令或属性绑定方式
6. 使用 dataIndex 处理 itemClicked 事件，以获取上下文
7. 使用每个 ToolbarItemModel 上的 align 属性，将主要操作放在 Left，将次要操作（设置、导出）放在 Right

模式 5：支持语音的界面

1. 配置 speechToTextSettings 中的语言和选项
2. 启用 allowInterimResults 以实时转录
3. 处理语音事件：onStart、onStop、transcriptChanged、onError
4. 自动将识别出的文本作为提示词提交
5. 在聆听状态期间提供视觉反馈

模式 6：使用带类型参数的事件驱动操作

1. 使用 PromptRequestEventArgs 访问提示词、attachedFiles 和取消标志
2. 使用 PromptChangedEventArgs 实时验证输入
3. 处理 StopRespondingEventArgs 以取消长时间运行的请求
4. 使用 beforeAttachmentUpload 验证文件
5. 使用 editableContextClicked 处理内联上下文徽标交互

模式 7：思维链（推理可视化）

1. 通过 AIAssistView.Inject(AssistThinking) 注入 AssistThinking 模块
2. 通过 addPromptResponse 推送带有 blockType: 'thinking' 的 blocks，流式传输期间使用 isFinalUpdate: false
3. 随着推理进展更新 stages[].status（inprogress → completed/failed）
4. 使用带有 {index} 占位符的 editableContext，创建可点击的内联引用
5. 在最后一次 isFinalUpdate: true 调用中一并提供最终的 response 文本
6. 可选地使用 blockTemplate（完整区块）或 itemTemplate（每个阶段）自定义渲染

模式 8：生成式 UI（响应中的交互式工具）

1. 使用 registerToolUI({ toolName, template, handler }) 注册每个工具一次，通常在 ngAfterViewInit 中注册
2. 在响应中使用 blocks: [{ blockType: 'tool', toolName, props }] 引用已注册的工具
3. 在同一个 blocks 数组中组合 text 和 tool 块，以提供叙述内容和交互式内容
4. 配置 AI 系统提示词，使其返回结构化的 blocks JSON 数组，以动态调用工具
5. 用户与渲染出的工具交互后，使用 executePrompt 触发后续 AI 响应
6. 防御性解析 AI 返回的 JSON；若输出格式错误，则回退为纯文本

模式 9：AI 响应指标遥测

1. 设置 telemetrySettings = { enable: true } 以启用遥测按钮
2. 使用 telemetrySettings 上的 metrics 数组选择要捕获的指标，并控制工具提示中的行顺序（例如，['duration', 'model', 'inputTokens', 'outputTokens', 'totalTokens']）
3. 将可选的 TelemetryData 参数传递给 addPromptResponse(response, isFinalUpdate, telemetryData)，以显示 model、inputTokens、outputTokens、reasoningTokens 和 cachedInputTokens；totalTokens 会自动计算
4. 使用 beforeReport(report) 事件，通过 report.customAttributes 添加特定领域的条目；也可以返回 null 以抑制报告
5. 将鼠标悬停在任意响应上的遥测按钮上，即可查看渲染后的工具提示——始终显示 status 和 duration，且无论 metrics 筛选器如何设置，都会包含 customAttributes

模式 10：提示词编辑器中的提及选择器

1. 为每个提及组（例如，Agent、命令、知识条目）定义本地数组（或 DataManager 实例）
2. 在组件上构建 mentions 数组，每个触发字符对应一个条目：{ mentionChar: '@', dataSource, fields: { text, value } }，并可选配置 filterType、query、highlight、popupWidth/Height 和模板
3. 通过 [mentions]="mentions" 将数组传递给组件，并设置有助于提示可用触发字符的 promptPlaceholder
4. 对于斜杠式命令，使用 showMentionChar: false，这样插入的提及内容中就不会保留 /
5. 使用 itemTemplate（弹出列表行）、displayTemplate（已选中的标记）和 noRecordsTemplate（空状态）自定义外观
6. 通过 mentionSelect 事件或每个提及项的 mentionSelect 回调响应选择，以捕获所选条目并执行相应操作

---

关键属性

属性	类型	默认值	使用场景
prompt	string	''	预填提示词文本
promptPlaceholder	string	'Type prompt for assistance...'	引导用户输入
promptSuggestions	string[]	[]	提供可快速开始使用的提示词
prompts	object[]	[]	初始化对话历史
showClearButton	boolean	false	显示清除输入的按钮
enableScrollToBottom	boolean	true	显示滚动到底部指示器
blockTemplate	string | object	''	自定义思考块的渲染方式
itemTemplate	string | object	''	自定义各个思考阶段条目的渲染方式
responseAnimationTemplate	string | object	''	自定义生成响应期间用于替代响应显示的加载指示器或动画

布局与外观

属性	类型	默认值	使用场景
width	string | number	'100%'	设置容器宽度
height	string | number	'100%'	设置容器高度
cssClass	string	''	应用自定义 CSS 样式和主题
showHeader	boolean	true	控制标题栏的显示
htmlAttributes	object	{}	添加自定义 HTML 属性（aria-、data- 等）

流式传输和功能

属性	类型	默认值	使用场景
enableStreaming	boolean	false	启用实时流式响应
speechToTextSettings	SpeechToTextSettingsModel	null	配置内置语音识别
textToSpeechSettings	TextToSpeechSettingsModel	null	配置内置文本转语音支持
activeView	number	0	以编程方式在视图之间切换
telemetrySettings	TelemetrySettingsModel	null	跟踪每条响应的 AI 指标（enable、metrics、beforeReport），并在响应工具栏中显示遥测按钮
mentions	MentionSettings[]	null	配置提示词编辑器中由触发字符激活的提及选择器（数据源、字段、查询、筛选类型、模板）

全球化

属性	类型	默认值	使用场景
locale	string	'en-US'	设置语言/区域文化（en-US、es-ES、fr-FR、de-DE、ja-JP、ar-SA 等）
enableRtl	boolean	false	启用从右向左的文本方向（阿拉伯语、希伯来语、波斯语、乌尔都语）
enablePersistence	boolean	false	在页面重新加载期间保存组件状态

工具栏配置

属性	类型	默认值	使用场景
toolbarSettings	ToolbarSettingsModel	null	配置页眉工具栏（全局操作）
promptToolbarSettings	PromptToolbarSettingsModel	null	配置提示词工具栏（编辑、复制、重试）
responseToolbarSettings	ResponseToolbarSettingsModel	null	配置响应工具栏（复制、重新生成、点赞/点踩）
footerToolbarSettings	FooterToolbarSettingsModel	null	配置页脚工具栏（格式设置、附件）

---

常见用例

1. 客服聊天机器人： 构建集成知识库的客服界面
2. 代码助手： 创建可借助 AI 审查和建议代码的编码助手
3. 内容写作助手： 实现可提供语法和文风建议的写作工具
4. 数据分析工具： 创建界面，让用户通过自然语言查询和分析数据
5. 学习平台： 构建能够回答学生问题的教育助手
6. 内部知识机器人： 创建用于公司文档和常见问题解答的企业助手
7. 多语言支持： 实现翻译和本地化功能
8. 无障碍助手： 提供阅读辅助或操作指导
9. 推理可视化： 构建界面，通过可折叠的思维链区块呈现 AI 推理
10. 生成式 UI 应用： 在 AI 回复中内嵌呈现交互式工具和图表（卡片、仪表盘、自定义小组件）
11. 逐条回复遥测： 使用 telemetrySettings 和 addPromptResponse 的 TelemetryData 参数，在每条 AI 回复中呈现耗时、模型和令牌用量
12. 基于用量的分析： 使用 customAttributes（区域、租户、sessionId、功能）补充遥测报告，以便在回复工具栏提示框中进行租户级别／功能级别的分析
13. 通过提及路由 Agent： 使用 @ 提及将提示词路由到特定 Agent（TechSupport、HRAssistant、KnowledgeBase），并在 mentionSelect 事件中解析 args.itemData，以便在发送前预加载 Agent 上下文
14. 通过提及使用斜杠命令： 使用 / 提及（设置 showMentionChar: false）提供 /table、/rewrite、/checklist 等快捷操作，以改变 AI 服务的回复方式
15. 远程知识选择器： 将提及的 dataSource 绑定到 DataManager 并应用 Query（支持分页／筛选），让用户能够在大型远程目录中搜索并插入条目
16. 品牌化加载状态： 使用 responseAnimationTemplate 在生成 AI 回复时显示自定义加载器、品牌化旋转图标或进度指示器 — 调用 addPromptResponse() 后会自动移除该模板
17. 对齐工具栏布局： 使用每个 ToolbarItemModel 上的 align 属性来放置主要操作（Left）、居中的快捷操作（Center）和设置／导出等次要操作（Right）— 适用于所有四种工具栏类型
18. 确认或取消附件移除： 使用 attachmentRemoving 事件（以及 RemovingEventArgs）在文件移除前进行拦截 — 设置 args.cancel = true 可保留附件，也可在附件分离前执行清理（撤销对象 URL、释放预览状态）

---