syncfusion-winui-ai-assistview

实现 WinUI AI AssistView

何时使用此技能

在用户需要执行以下操作时使用此技能：

• 创建 AI 聊天界面或对话式 UI
• 实现 AI 助手或聊天机器人
• 集成 AI 服务（OpenAI、Azure AI 等）
• 显示带格式的 AI 生成回复
• 在 AI 处理期间显示输入指示器
• 提供 AI 驱动的快捷回复建议
• 为聊天操作添加自定义工具栏（复制、重新生成、点赞/点踩）
• 允许用户停止耗时较长的 AI 回复
• 构建客户支持机器人或帮助系统
• 创建智能对话应用程序

用户提及以下内容时，始终应用此技能： WinUI 应用程序中的 AI 聊天、AI 助手、聊天机器人、对话式 UI、AI 回复、聊天界面、AI 集成、输入指示器、AI 建议或 AI 驱动的对话。

组件概览

SfAIAssistView 是 Syncfusion WinUI 控件，可提供全面的 AI 聊天界面，帮助构建可与 AI 服务集成的智能响应式应用程序。它提供易用的对话式 UI，并内置建议、输入指示器、回复工具栏和可自定义外观等功能。

命名空间： Syncfusion.UI.Xaml.Chat
NuGet 包： Syncfusion.Chat.WinUI
平台： WinUI 3 桌面版（.NET 5+、Windows App SDK 1.0+）

主要优势： 开箱即用的完整 AI 聊天体验，内置工具栏、建议、输入指示器和停止回复功能，无需从头构建聊天 UI。

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置（Syncfusion.Chat.WinUI）
• 命名空间导入（Syncfusion.UI.Xaml.Chat）
• SfAIAssistView 基本初始化
• CurrentUser 和 Messages 属性
• 使用 TextMessage 和 Author 类创建 ViewModel
• 首个完整 AI 聊天示例
• 许可证注册

AI 建议

📄 阅读： references/suggestions.md

• 用于 AI 驱动建议的 Suggestions 属性
• 显示快捷回复选项
• 定位在右下角
• 动态更新建议
• 处理建议选择
• 加快对话流程的使用场景

回复工具栏

📄 阅读： references/response-toolbar.md

• 内置工具栏项（复制、重新生成、点赞、点踩）
• ResponseToolbarItem 类及其属性
• 使用 ItemTemplate 添加自定义工具栏项
• IsResponseToolbarVisible 属性
• ResponseToolbarItemClicked 事件
• 自定义工具栏外观
• 为回复添加自定义操作

输入工具栏

📄 阅读： references/input-toolbar.md

• 用于自定义输入操作的 InputToolbarItem 类
• 在文本输入区域添加工具栏项
• InputToolbarPosition（Left、Right）
• IsInputToolbarVisible 属性
• InputToolbarItemClicked 事件
• 用于文件上传的 InputToolbarHeaderTemplate
• 自定义输入区域操作

输入指示器与停止回复

📄 阅读： references/typing-and-stop-responding.md

• 用于反馈 AI 处理状态的 TypingIndicator 属性
• ShowTypingIndicator 布尔属性
• AI 生成回复期间的实时反馈
• EnableStopResponding 属性
• StopResponding 事件和命令
• 自定义 StopRespondingTemplate
• 取消正在进行的 AI 回复

主题与事件

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

• RequestedTheme 属性（Dark、Light 主题）
• 在 App.xaml 中支持主题
• PromptRequest 事件
• InputMessage 和 Handled 属性
• 处理前验证用户输入
• 提交提示词时执行自定义操作
• 自定义主题

快速入门示例

<Page
    xmlns:syncfusion="using:Syncfusion.UI.Xaml.Chat">
    <Grid>
        <syncfusion:SfAIAssistView 
            x:Name="aiAssistView"
            CurrentUser="{Binding CurrentUser}"
            Messages="{Binding Chats}"
            Suggestions="{Binding Suggestions}"
            ShowTypingIndicator="{Binding IsProcessing}"
            TypingIndicator="{Binding TypingIndicator}"/>
    </Grid>
</Page>

using Syncfusion.UI.Xaml.Chat;
using System.Collections.ObjectModel;

public class ViewModel : INotifyPropertyChanged
{
    private ObservableCollection<object> chats;
    private Author currentUser;
    private IEnumerable<string> suggestions;
    private TypingIndicator typingIndicator;
    private bool isProcessing;

    public ViewModel()
    {
        this.CurrentUser = new Author { Name = "User" };
        this.Chats = new ObservableCollection<object>();
        this.TypingIndicator = new TypingIndicator { Author = new Author { Name = "AI" } };
        this.Suggestions = new ObservableCollection<string>();
        InitializeChat();
    }

    private async void InitializeChat()
    {
        // User asks a question
        this.Chats.Add(new TextMessage 
        { 
            Author = CurrentUser, 
            Text = "What is WinUI?" 
        });
        
        // Show typing indicator
        IsProcessing = true;
        await Task.Delay(1000);
        
        // AI responds
        IsProcessing = false;
        this.Chats.Add(new TextMessage 
        { 
            Author = new Author { Name = "AI" }, 
            Text = "WinUI is a user interface layer that contains modern controls and styles for building Windows apps." 
        });
        
        // Update suggestions
        Suggestions = new ObservableCollection<string> 
        { 
            "What is the future of WinUI?", 
            "What is XAML?", 
            "What is the difference between WinUI 2 and WinUI 3?" 
        };
    }

    public ObservableCollection<object> Chats
    {
        get => chats;
        set { chats = value; RaisePropertyChanged(nameof(Chats)); }
    }

    public Author CurrentUser
    {
        get => currentUser;
        set { currentUser = value; RaisePropertyChanged(nameof(CurrentUser)); }
    }

    public IEnumerable<string> Suggestions
    {
        get => suggestions;
        set { suggestions = value; RaisePropertyChanged(nameof(Suggestions)); }
    }

    public TypingIndicator TypingIndicator
    {
        get => typingIndicator;
        set { typingIndicator = value; RaisePropertyChanged(nameof(TypingIndicator)); }
    }

    public bool IsProcessing
    {
        get => isProcessing;
        set { isProcessing = value; RaisePropertyChanged(nameof(IsProcessing)); }
    }

    public event PropertyChangedEventHandler PropertyChanged;
    private void RaisePropertyChanged(string propertyName) =>
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
}

常见模式

1. 带消息的基本 AI 聊天

<syncfusion:SfAIAssistView 
    CurrentUser="{Binding CurrentUser}"
    Messages="{Binding Chats}"/>

public class ViewModel
{
    public Author CurrentUser { get; set; } = new Author { Name = "John" };
    public ObservableCollection<object> Chats { get; set; } = new();

    public ViewModel()
    {
        Chats.Add(new TextMessage { Author = CurrentUser, Text = "Hello!" });
        Chats.Add(new TextMessage { Author = new Author { Name = "Bot" }, Text = "Hi! How can I help you?" });
    }
}

适用场景： 不带建议或输入指示器的简单 AI 聊天。

2. 带有输入指示器的 AI 聊天

<syncfusion:SfAIAssistView 
    CurrentUser="{Binding CurrentUser}"
    Messages="{Binding Chats}"
    ShowTypingIndicator="{Binding IsAIProcessing}"
    TypingIndicator="{Binding TypingIndicator}"/>

private async void SendMessageToAI(string userMessage)
{
    Chats.Add(new TextMessage { Author = CurrentUser, Text = userMessage });
    
    // Show typing indicator
    IsAIProcessing = true;
    
    // Call AI service
    var aiResponse = await CallAIService(userMessage);
    
    // Hide typing indicator and show response
    IsAIProcessing = false;
    Chats.Add(new TextMessage { Author = new Author { Name = "AI" }, Text = aiResponse });
}

使用场景： 在 AI 生成回复时提供实时反馈。

3. AI 快速回复建议

<syncfusion:SfAIAssistView 
    CurrentUser="{Binding CurrentUser}"
    Messages="{Binding Chats}"
    Suggestions="{Binding CurrentSuggestions}"/>

private void UpdateSuggestions(string lastAIResponse)
{
    // Generate contextual suggestions based on AI response
    CurrentSuggestions = new ObservableCollection<string>
    {
        "Tell me more",
        "Show me an example",
        "What are the alternatives?"
    };
}

使用场景： 通过提供符合上下文的快速回复，加快对话进程。

4. 带操作项的自定义回复工具栏

<syncfusion:SfAIAssistView 
    CurrentUser="{Binding CurrentUser}"
    Messages="{Binding Chats}"
    IsResponseToolbarVisible="True"
    ResponseToolbarItemClicked="ResponseToolbar_ItemClicked"/>

private void ResponseToolbar_ItemClicked(object sender, ResponseToolbarItemClickedEventArgs e)
{
    switch (e.Item.ItemType)
    {
        case ResponseToolbarItemType.Copy:
            CopyToClipboard(e.Message.Text);
            break;
        case ResponseToolbarItemType.Regenerate:
            RegenerateAIResponse(e.Message);
            break;
        case ResponseToolbarItemType.Like:
            SendFeedback("like", e.Message);
            break;
        case ResponseToolbarItemType.Dislike:
            SendFeedback("dislike", e.Message);
            break;
    }
}

使用场景： 允许用户与 AI 回复交互（复制、重新生成、评分）。

5. 带文件上传功能的自定义输入工具栏

<syncfusion:SfAIAssistView IsInputToolbarVisible="True">
    <syncfusion:SfAIAssistView.InputToolbarItems>
        <syncfusion:InputToolbarItem Tooltip="Attach file">
            <syncfusion:InputToolbarItem.ItemTemplate>
                <DataTemplate><Button Click="AttachFile_Click"><SymbolIcon Symbol="Attach"/></Button></DataTemplate>
            </syncfusion:InputToolbarItem.ItemTemplate>
        </syncfusion:InputToolbarItem>
    </syncfusion:SfAIAssistView.InputToolbarItems>
</syncfusion:SfAIAssistView>

使用场景： 允许用户将文件附加到 AI 提示词中。完整实现请参阅 input-toolbar.md。

6. 长篇 AI 回复的停止响应功能

<syncfusion:SfAIAssistView 
    CurrentUser="{Binding CurrentUser}"
    Messages="{Binding Chats}"
    EnableStopResponding="True"
    StopResponding="StopResponding_Event"/>

private CancellationTokenSource aiCancellationToken;

private async void SendToAI(string prompt)
{
    aiCancellationToken = new CancellationTokenSource();
    
    try
    {
        var response = await CallAIServiceAsync(prompt, aiCancellationToken.Token);
        Chats.Add(new TextMessage { Author = new Author { Name = "AI" }, Text = response });
    }
    catch (OperationCanceledException)
    {
        Chats.Add(new TextMessage { Author = new Author { Name = "AI" }, Text = "Response canceled." });
    }
}

private void StopResponding_Event(object sender, EventArgs e)
{
    aiCancellationToken?.Cancel();
}

使用场景： 允许用户取消长时间运行的 AI 回复。

7. 用于输入验证的 PromptRequest 事件

private void PromptRequest_Event(object sender, PromptRequestEventArgs e)
{
    if (string.IsNullOrWhiteSpace(e.InputMessage.Text))
    {
        e.Handled = true;
        ShowError("Please enter a message.");
    }
}

使用场景： 在 AI 处理前验证或预处理用户输入。

8. OpenAI 集成模式

private async Task<string> CallOpenAI(string prompt)
{
    var client = new OpenAIClient(apiKey);
    var response = await client.CompleteChatAsync("gpt-4", new ChatCompletionOptions
    {
        Messages = { new SystemChatMessage("You are a helpful assistant."), new UserChatMessage(prompt) }
    });
    return response.Value.Content[0].Text;
}

使用场景： 与 OpenAI GPT 模型集成。主题配置请参阅 theming-and-events.md。

主要属性

属性	类型	默认值	描述
Messages	ObservableCollection<object>	null	聊天消息集合（TextMessage 对象）。
CurrentUser	Author	null	当前用户的作者信息。用于区分用户消息和 AI 回复。
Suggestions	IEnumerable<string>	null	AI 提供的建议，显示在右下角，供用户快速回复。
ShowTypingIndicator	bool	false	在 AI 处理期间显示或隐藏输入指示器。
TypingIndicator	TypingIndicator	null	输入指示器配置（作者、文本）。
IsResponseToolbarVisible	bool	true	显示或隐藏回复工具栏（复制、重新生成、赞、踩）。
ResponseToolbarItems	ObservableCollection<ResponseToolbarItem>	内置项	用于回复操作的自定义工具栏项。
IsInputToolbarVisible	bool	false	显示或隐藏文本输入区域中的输入工具栏。
InputToolbarItems	ObservableCollection<InputToolbarItem>	null	输入区域的自定义工具栏项（例如，附加文件）。
InputToolbarPosition	ToolbarPosition	Right	输入工具栏的位置（Left 或 Right）。
InputToolbarHeaderTemplate	DataTemplate	null	输入区域标题的自定义模板（例如，文件上传信息）。
EnableStopResponding	bool	false	启用停止响应按钮，以取消正在进行的 AI 回复。
StopRespondingTemplate	DataTemplate	null	停止响应按钮的自定义模板。
StopRespondingCommand	ICommand	null	单击停止响应按钮时执行的命令。
RequestedTheme	ElementTheme	Default	控件的主题（Light、Dark 或 Default）。在 App.xaml 中设置。

主要事件

事件	描述
PromptRequest	用户提交提示词时触发。提供 InputMessage 和 Handled 属性。
ResponseToolbarItemClicked	单击回复工具栏项时触发。提供项的详细信息。
InputToolbarItemClicked	单击输入工具栏项时触发。提供项的详细信息。
StopResponding	单击停止响应按钮时触发。用于取消 AI 操作。

常见使用场景

AI 聊天机器人和助手

• 客户支持聊天机器人
• 虚拟助手
• 服务台自动化
• 常见问题机器人
• 产品推荐助手

最佳方式： 使用 Messages 保存对话历史，通过 Suggestions 提供常见查询，并使用输入指示器提供反馈。

AI 驱动的开发工具

• 代码生成助手
• 文档生成器
• 代码审查机器人
• 调试助手

最佳方式： 启用回复工具栏以复制代码和重新生成回复。使用输入工具栏上传文件或代码。

教育 AI 家教

• 交互式学习助手
• 作业辅导机器人
• 语言学习家教
• 特定学科家教

最佳实践： 使用建议推荐学习路径，使用回复工具栏为答案评分，并使用输入指示器提升互动性。

内容生成

• 写作助手
• 电子邮件撰写工具
• 社交媒体内容创作工具
• 营销文案生成器

最佳实践： 在回复工具栏中启用复制/重新生成，使用建议提供不同的内容变体。

数据分析与洞察

• 商业智能助手
• 数据查询界面
• 报告生成机器人
• 分析辅助工具

最佳实践： 使用输入工具栏上传数据，对耗时较长的查询启用停止响应，并在回复工具栏中提供导出操作。

实现技巧

1. 消息管理： 将 Messages 用于 ObservableCollection，以便在添加或移除消息时自动更新 UI。

2. 输入指示器： 在 AI 异步调用期间显示，收到回复后隐藏。将其绑定到 ViewModel 的布尔属性。

3. 建议： 根据对话上下文动态更新。用户选择后或几轮对话后清除。

4. 错误处理： 使用 PromptRequest 事件验证输入。妥善捕获 AI 服务错误。

5. 性能： 对于较长的对话，可考虑实现消息分页或限制可见消息数量。

6. AI 服务集成： 使用 async/await 调用 AI 服务。通过停止响应功能实现取消令牌。

7. 回复工具栏： 默认项（Copy、Regenerate、Like、Dislike）会自动生效。自定义逻辑可通过 ResponseToolbarItemClicked 处理。

8. 输入工具栏： 用于文件上传、语音输入或表情选择器等常用操作。

9. 主题支持： 在 App.xaml 中设置 RequestedTheme，以应用全局主题。控件会自动适配浅色/深色模式。

10. 无障碍功能： 设置 Author.Name，方便屏幕阅读器读取。确保自定义模板具有足够的对比度。

相关文档

• 入门指南： 有关设置和基本用法，请参阅 references/getting-started.md
• 建议： 有关 AI 驱动的快速回复，请参阅 references/suggestions.md
• 回复工具栏： 有关回复操作，请参阅 references/response-toolbar.md
• 输入工具栏： 有关输入区域自定义，请参阅 references/input-toolbar.md
• 输入指示器与停止响应： 有关指示器和取消操作，请参阅 references/typing-and-stop-responding.md
• 主题与事件： 有关主题和事件，请参阅 references/theming-and-events.md