syncfusion-flutter-chat

Syncfusion Flutter Chat 与 AI AssistView

本技能介绍 Syncfusion Flutter 的两个相关对话式 UI 组件：SfChat（Chat 组件）和 SfAIAssistView（AI AssistView 组件）。虽然它们在视觉和配置方面有许多共同之处，但主要用途各不相同。

何时使用此技能

在以下情况下使用此技能：

• 实现聊天界面，支持多用户对话和消息
• 添加 AI 助手功能，支持请求-响应模式
• 构建消息应用，支持接收和发送消息
• 创建 AI 聊天机器人界面，并集成 AI 服务
• 显示对话 UI，包含消息、头像和时间戳
• 处理消息撰写，使用文本编辑器和操作按钮
• 自定义消息外观，使用构建器、主题和样式
• 为空对话状态支持占位页面
• 启用建议标签，用于快速回复或操作
• 集成响应消息的工具栏操作（如点赞、复制、重试）
• 显示加载指示器，提示 AI 正在生成响应
• 实现 RTL 支持，适配从右向左书写的语言

选择合适的组件

在以下情况下使用 SfChat（Chat 组件）：

• 需要多用户对话界面
• 应用需要区分接收和发送的消息
• 需要传统消息应用功能（WhatsApp、Telegram 风格）
• 为以下场景构建聊天功能：团队协作、客户支持、社交消息、群聊
• 消息建议应同时显示在接收和发送的消息上
• 需要明确指定发送用户

在以下情况下使用 SfAIAssistView（AI AssistView 组件）：

• 需要 AI 助手或聊天机器人功能
• 主要目标是通过 AI 服务实现请求-响应模式
• 需要在响应消息上显示工具栏项（如点赞、点踩、复制、重试）
• 需要在 AI 生成响应时显示加载指示器
• 为以下场景构建 UI：AI 助手、聊天机器人、帮助机器人、问答界面
• 消息建议只应显示在 AI 响应消息上
• 需要明确区分请求与响应消息

主要差异汇总：

特性	SfChat	SfAIAssistView
主要用途	多用户消息	AI 助手交互
消息类型	接收/发送	请求/响应
用户标识	outgoingUser 属性	每条消息中的 Author
建议	可显示在任意消息上	只显示在响应消息上
工具栏项	❌ 不支持	✅ 支持响应工具栏
加载指示器	❌ 不包含	✅ 响应加载构建器
使用场景	聊天应用、消息	AI 聊天机器人、助手
消息类	ChatMessage	AssistMessage
撰写器类	ChatComposer	AssistComposer
操作按钮类	ChatActionButton	AssistActionButton

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 两个组件的安装与包配置
• 基本 SfChat 实现
• 基本 SfAIAssistView 实现
• 包依赖项与导入
• 快速比较与首个示例

组件概览

📄 Chat： references/chat-overview.md

• SfChat 组件概览与功能
• 何时使用 Chat 与 AI AssistView
• 多用户对话功能
• 接收/发送消息模式
• Chat 专属功能
• 基本 Chat 配置

📄 AI AssistView： references/aiassistview-overview.md

• SfAIAssistView 组件概览与功能
• 何时使用 AI AssistView 与 Chat
• 请求/响应模式
• AI 集成功能
• AIAssistView 专属功能
• 基本 AIAssistView 配置

对话区域和消息

📄 阅读： references/conversation-area.md

• 消息结构和显示
• 接收/发送消息（Chat）
• 请求/响应消息（AIAssistView）
• 消息设置和自定义
• 标题和时间戳
• 页脚和附加信息
• 消息头像
• 内容区域样式
• 消息建议（两个组件均支持）
• 工具栏项（仅限 AIAssistView）
• 加载指示器（仅限 AIAssistView）

编辑器和输入

📄 阅读： references/composer.md

• 默认编辑器配置
• 文本编辑器自定义
• 最小行数和最大行数
• 装饰和样式
• 提示文本和占位符
• 边框和内边距
• 前缀和后缀图标
• 文本样式自定义
• 外边距配置
• 自定义编辑器构建器

操作按钮

📄 阅读： references/action-button.md

• 操作按钮概述
• 发送按钮功能
• 自定义子组件
• onPressed 回调
• 工具提示文本
• 颜色（前景、背景、焦点、悬停、涟漪）
• 高度设置
• 鼠标光标自定义
• 形状和边框圆角
• 外边距和尺寸

占位符

📄 阅读： references/placeholder.md

• 占位符构建器概述
• 自定义占位组件
• 空对话状态设计
• 欢迎消息
• 入门提示
• 两个组件的示例

主题和自定义

📄 阅读： references/theming.md

• 主题概述（Chat 与 AIAssistView）
• SfChatTheme 和 SfAIAssistViewTheme
• 操作按钮主题
• 头像颜色和样式
• 消息背景颜色
• 内容文本样式
• 标题文本样式
• 建议样式
• 消息形状和边框
• 工具栏主题（仅限 AIAssistView）

本地化和无障碍功能

📄 阅读： references/right-to-left.md

• 从右向左（RTL）支持
• Directionality 组件的用法
• 所有元素的 RTL 渲染
• 占位符的 RTL
• 编辑器的 RTL
• 操作按钮的 RTL
• 消息和内容的 RTL

常见模式

📄 阅读： references/common-patterns.md

• 消息设置自定义
• 带多个操作的自定义编辑器
• 用于空状态的自定义占位符
• AI 响应的加载指示器
• 统一品牌体验的主题设置

快速入门示例

带消息的基础 Chat

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_chat/chat.dart';

class MyChat extends StatefulWidget {
  @override
  State<MyChat> createState() => _MyChatState();
}

class _MyChatState extends State<MyChat> {
  List<ChatMessage> _messages = <ChatMessage>[];

  @override
  void initState() {
    super.initState();
    _messages = <ChatMessage>[
      ChatMessage(
        text: 'Hi! How can I help you today?',
        time: DateTime.now(),
        author: const ChatAuthor(
          id: '123-001',
          name: 'John Doe',
        ),
      ),
      ChatMessage(
        text: 'I need help with my order.',
        time: DateTime.now(),
        author: const ChatAuthor(
          id: '123-002',
          name: 'Jane Smith',
        ),
      ),
    ];
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Chat')),
      body: SfChat(
        messages: _messages,
        outgoingUser: '123-002',
        composer: const ChatComposer(
          decoration: InputDecoration(
            hintText: 'Type a message',
          ),
        ),
        actionButton: ChatActionButton(
          onPressed: (String newMessage) {
            setState(() {
              _messages.add(
                ChatMessage(
                  text: newMessage,
                  time: DateTime.now(),
                  author: const ChatAuthor(
                    id: '123-002',
                    name: 'Jane Smith',
                  ),
                ),
              );
            });
          },
        ),
      ),
    );
  }
}

集成 AI 的基础 AI AssistView

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_chat/assist_view.dart';

class MyAIAssistView extends StatefulWidget {
  @override
  State<MyAIAssistView> createState() => _MyAIAssistViewState();
}

class _MyAIAssistViewState extends State<MyAIAssistView> {
  List<AssistMessage> _messages = <AssistMessage>[];

  void _generateAIResponse(String userRequest) async {
    // Call your AI service here
    final String aiResponse = await _getAIResponse(userRequest);
    setState(() {
      _messages.add(
        AssistMessage.response(
          data: aiResponse,
          time: DateTime.now(),
          author: const AssistMessageAuthor(
            id: 'ai-001',
            name: 'AI Assistant',
          ),
        ),
      );
    });
  }

  Future<String> _getAIResponse(String request) async {
    // Connect with your preferred AI service
    // Example: OpenAI, Google AI, Azure AI, etc.
    await Future.delayed(Duration(seconds: 2)); // Simulate API call
    return 'This is a response to: $request';
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('AI Assistant')),
      body: SfAIAssistView(
        messages: _messages,
        composer: const AssistComposer(
          decoration: InputDecoration(
            hintText: 'Ask me anything',
          ),
        ),
        actionButton: AssistActionButton(
          onPressed: (String userRequest) {
            setState(() {
              _messages.add(
                AssistMessage.request(
                  data: userRequest,
                  time: DateTime.now(),
                  author: const AssistMessageAuthor(
                    id: 'user-001',
                    name: 'User',
                  ),
                ),
              );
              _generateAIResponse(userRequest);
            });
          },
        ),
        placeholderBuilder: (BuildContext context) {
          return const Center(
            child: Text(
              'What can I help you with today?',
              style: TextStyle(fontSize: 16),
            ),
          );
        },
      ),
    );
  }
}

带建议的 Chat

SfChat(
  messages: <ChatMessage>[
    ChatMessage(
      text: 'Which programming language should I learn?',
      time: DateTime.now(),
      author: const ChatAuthor(id: '1', name: 'Alice'),
    ),
    ChatMessage(
      text: 'It depends on your goals. What interests you?',
      time: DateTime.now(),
      author: const ChatAuthor(id: '2', name: 'Bob'),
      suggestions: <ChatMessageSuggestion>[
        const ChatMessageSuggestion(data: 'Web Development'),
        const ChatMessageSuggestion(data: 'Mobile Apps'),
        const ChatMessageSuggestion(data: 'Data Science'),
        const ChatMessageSuggestion(data: 'Game Development'),
      ],
    ),
  ],
  outgoingUser: '1',
)

带工具栏项的 AI AssistView

void _generateResponse(String request) async {
  final String response = await _getAIResponse(request);
  setState(() {
    _messages.add(
      AssistMessage.response(
        data: response,
        time: DateTime.now(),
        author: const AssistMessageAuthor(id: 'ai', name: 'AI'),
        toolbarItems: <AssistMessageToolbarItem>[
          const AssistMessageToolbarItem(
            content: Icon(Icons.thumb_up_outlined),
            tooltip: 'Like',
          ),
          const AssistMessageToolbarItem(
            content: Icon(Icons.thumb_down_outlined),
            tooltip: 'Dislike',
          ),
          const AssistMessageToolbarItem(
            content: Icon(Icons.copy),
            tooltip: 'Copy',
          ),
          const AssistMessageToolbarItem(
            content: Icon(Icons.restart_alt),
            tooltip: 'Regenerate',
          ),
        ],
      ),
    );
  });
}

SfAIAssistView(
  messages: _messages,
  onToolbarItemSelected: (bool selected, int messageIndex,
      AssistMessageToolbarItem item, int toolbarItemIndex) {
    // Handle toolbar action (like, dislike, copy, etc.)
    print('Toolbar item selected at index $toolbarItemIndex');
  },
)

关键属性

SfChat 的核心属性

• messages - 要显示的 ChatMessage 对象列表
• outgoingUser - 发送消息的用户 ID（用于区分接收和发送消息）
• composer - 用于文本输入的 ChatComposer
• actionButton - 用于发送消息的 ChatActionButton
• placeholderBuilder - 空状态下使用的自定义组件
• incomingMessageSettings - 接收消息的设置
• outgoingMessageSettings - 发送消息的设置
• messageHeaderBuilder - 每条消息的自定义标题
• messageFooterBuilder - 每条消息的自定义页脚
• messageContentBuilder - 每条消息的自定义内容
• messageAvatarBuilder - 每条消息的自定义头像

SfAIAssistView 的基本属性

• messages - AssistMessage 对象列表（请求/响应）
• composer - 用于文本输入的 AssistComposer
• actionButton - 用于发送请求的 AssistActionButton
• placeholderBuilder - 用于空状态的自定义组件
• requestMessageSettings - 请求消息的设置
• responseMessageSettings - 响应消息的设置
• messageHeaderBuilder - 每条消息的自定义标题
• messageFooterBuilder - 每条消息的自定义页脚
• messageContentBuilder - 每条消息的自定义内容
• messageAvatarBuilder - 每条消息的自定义头像
• responseLoadingBuilder - AI 响应期间的自定义加载指示器
• onToolbarItemSelected - 点击工具栏项目时的回调
• onSuggestionItemSelected - 点击建议标签时的回调

ChatMessage / AssistMessage 属性

ChatMessage：

• text - 消息内容
• time - 消息时间戳
• author - 包含 id、名称和头像的 ChatAuthor
• suggestions - ChatMessageSuggestion 项目列表

AssistMessage：

• data - 消息内容
• time - 消息时间戳
• author - 包含 id、名称和头像的 AssistMessageAuthor
• suggestions - AssistMessageSuggestion 项目列表（仅响应消息）
• toolbarItems - AssistMessageToolbarItem 列表（仅响应消息）

撰写器属性（两个组件均适用）

• minLines - 文本编辑器的最小行数（默认值：1）
• maxLines - 文本编辑器的最大行数（默认值：6）
• decoration - 用于设置样式的 InputDecoration
• margin - 撰写器周围的空白
• textStyle - 输入文本样式
• builder - 自定义撰写器组件

操作按钮属性（两个组件均适用）

• child - 按钮的自定义组件
• onPressed - 按钮按下时的回调
• tooltip - 提示文本
• foregroundColor - 图标/文本颜色
• backgroundColor - 按钮背景颜色
• focusColor - 聚焦时的颜色
• hoverColor - 悬停时的颜色
• splashColor - 涟漪效果颜色
• elevation - 阴影高度
• focusElevation - 聚焦时的高度
• hoverElevation - 悬停时的高度
• highlightElevation - 按下时的高度
• mouseCursor - 悬停时的光标样式
• shape - 按钮形状和边框
• margin - 按钮周围的空白
• size - 按钮尺寸

消息设置属性（两个组件均适用）

• showAuthorName - 显示/隐藏作者名称
• showTimestamp - 显示/隐藏时间戳
• showAuthorAvatar - 显示/隐藏头像
• timestampFormat - 时间戳的 DateFormat
• backgroundColor - 消息背景颜色
• textStyle - 消息文本样式
• headerTextStyle - 标题文本样式
• shape - 消息气泡形状
• widthFactor - 消息相对于屏幕的宽度（0-1）
• avatarSize - 头像尺寸
• margin - 消息周围的空白
• padding - 消息内部的内边距
• avatarPadding - 头像周围的内边距
• headerPadding - 标题周围的内边距
• footerPadding - 页脚周围的内边距

常见用例

对于 SfChat： 客户支持聊天、团队消息、社交消息、支持多用户对话以及传入/传出消息模式的实时聊天支持。

对于 SfAIAssistView： AI 聊天机器人、AI 助手、帮助机器人、采用请求/响应模式并包含工具栏项目和加载指示器的问答界面。