syncfusion-maui-chat

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syncfusion .NET MAUI Chat (SfChat)

Syncfusion .NET MAUI Chat(SfChat)

The Syncfusion .NET MAUI Chat control (
SfChat
) delivers a contemporary conversational UI for building chatbot interfaces, customer support screens, and multi-user messaging experiences. It supports rich message types, real-time typing indicators, suggestions, load-more history, swiping, and deep styling customization.
Syncfusion .NET MAUI Chat控件(
SfChat
)为构建聊天机器人界面、客户支持界面和多用户消息交互体验提供了现代化的对话式UI。它支持丰富的消息类型、实时输入指示器、建议功能、加载更多历史记录、滑动操作以及深度样式自定义。

When to Use This Skill

何时使用此技能

  • Building a chat UI, chatbot interface, or messaging screen in .NET MAUI
  • Displaying conversations between two or more users
  • Sending/receiving text, images, cards, hyperlinks, or date/time picker messages
  • Implementing typing indicators, message suggestions, or load-more history
  • Customizing message appearance, shapes, delivery states, or themes
  • Adding swipe actions, time-break grouping, or attachment buttons
  • Localizing the chat UI or enabling accessibility features
  • 在.NET MAUI中构建聊天UI、聊天机器人界面或消息界面
  • 展示两个或多个用户之间的对话
  • 发送/接收文本、图片、卡片、超链接或日期/时间选择器消息
  • 实现输入指示器、消息建议或加载更多历史记录功能
  • 自定义消息外观、形状、送达状态或主题
  • 添加滑动操作、时间分段分组或附件按钮
  • 本地化聊天UI或启用无障碍功能

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • NuGet installation (
    Syncfusion.Maui.Chat
    )
  • Handler registration in
    MauiProgram.cs
  • Basic
    SfChat
    initialization in XAML and C#
  • ViewModel setup with
    Messages
    and
    CurrentUser
  • Binding messages to the chat control
  • Running the application
📄 阅读: references/getting-started.md
  • NuGet安装(
    Syncfusion.Maui.Chat
  • MauiProgram.cs
    中注册处理器
  • 在XAML和C#中初始化基础
    SfChat
  • 设置包含
    Messages
    CurrentUser
    的ViewModel
  • 将消息绑定到聊天控件
  • 运行应用

Messages

消息

📄 Read: references/messages.md
  • TextMessage
    ,
    DatePickerMessage
    ,
    TimePickerMessage
    ,
    CalendarMessage
  • HyperlinkMessage
    ,
    ImageMessage
    ,
    CardMessage
  • Delivery states (
    ShowDeliveryState
    ,
    DeliveryState
    enum, custom icons)
  • Pin message (
    AllowPinning
    ,
    PinnedMessages
    , events, template)
  • Message template and
    ChatMessageTemplateSelector
  • Customizable incoming/outgoing views
  • Message spacing, shape, timestamp format, avatar/author visibility
  • Sending messages, keyboard, multiline input, hide input view
📄 阅读: references/messages.md
  • TextMessage
    DatePickerMessage
    TimePickerMessage
    CalendarMessage
  • HyperlinkMessage
    ImageMessage
    CardMessage
  • 送达状态(
    ShowDeliveryState
    DeliveryState
    枚举、自定义图标)
  • 消息固定(
    AllowPinning
    PinnedMessages
    、事件、模板)
  • 消息模板和
    ChatMessageTemplateSelector
  • 可自定义的 incoming/outgoing 视图
  • 消息间距、形状、时间戳格式、头像/发送者可见性
  • 发送消息、键盘、多行输入、隐藏输入视图

Data Binding

数据绑定

📄 Read: references/data-binding.md
  • Binding
    ObservableCollection<object>
    to
    Messages
  • CurrentUser
    differentiation of sender/receiver
  • Custom data models with
    IMessage
    /
    ITextMessage
  • ItemsSourceConverter
    for external model binding
  • Dynamically updating messages at runtime
📄 阅读: references/data-binding.md
  • ObservableCollection<object>
    绑定到
    Messages
  • 通过
    CurrentUser
    区分发送者/接收者
  • 实现
    IMessage
    /
    ITextMessage
    的自定义数据模型
  • 使用
    ItemsSourceConverter
    绑定外部模型
  • 在运行时动态更新消息

Suggestions

建议功能

📄 Read: references/suggestions.md
  • Chat-level suggestions (
    SfChat.Suggestions
    )
  • Message-level suggestions (
    TextMessage.Suggestions
    )
  • SuggestionItemSelected
    event and command
  • Customizing suggestion item templates
📄 阅读: references/suggestions.md
  • 聊天级别的建议(
    SfChat.Suggestions
  • 消息级别的建议(
    TextMessage.Suggestions
  • SuggestionItemSelected
    事件和命令
  • 自定义建议项模板

Typing Indicator

输入指示器

📄 Read: references/typing-indicator.md
  • Enabling the typing indicator (
    ShowTypingIndicator
    )
  • Setting author and message on
    TypingIndicator
  • Customizing appearance
  • Showing/hiding dynamically
📄 阅读: references/typing-indicator.md
  • 启用输入指示器(
    ShowTypingIndicator
  • TypingIndicator
    上设置发送者和消息
  • 自定义外观
  • 动态显示/隐藏

Load More

加载更多

📄 Read: references/load-more.md
  • Enabling load more (
    LoadMoreBehavior
    )
  • LoadMore
    event and
    LoadMoreCommand
  • Loading older messages on scroll
  • IsLazyLoading
    property
  • Disabling after all messages are loaded
📄 阅读: references/load-more.md
  • 启用加载更多功能(
    LoadMoreBehavior
  • LoadMore
    事件和
    LoadMoreCommand
  • 滚动时加载旧消息
  • IsLazyLoading
    属性
  • 所有消息加载完成后禁用该功能

Events & Commands

事件与命令

📄 Read: references/events.md
  • SendMessage
    /
    SendMessageCommand
  • ImageTapped
    /
    ImageTappedCommand
  • CardTapped
    /
    CardCommand
  • SuggestionItemSelected
  • MessagePinned
    /
    MessageUnpinned
  • LoadMore
    /
    LoadMoreCommand
  • Handling and cancelling event args
📄 阅读: references/events.md
  • SendMessage
    /
    SendMessageCommand
  • ImageTapped
    /
    ImageTappedCommand
  • CardTapped
    /
    CardCommand
  • SuggestionItemSelected
  • MessagePinned
    /
    MessageUnpinned
  • LoadMore
    /
    LoadMoreCommand
  • 处理和取消事件参数

Styles & Appearance

样式与外观

📄 Read: references/styles.md
  • Incoming and outgoing message styling
  • Message input view styling
  • Time-break and typing indicator styling
  • Suggestion view styling
  • MessageShape
    options
  • Theme support (Material 3, Fluent)
📄 阅读: references/styles.md
  • 接收和发送消息的样式设置
  • 消息输入视图样式设置
  • 时间分段和输入指示器样式设置
  • 建议视图样式设置
  • MessageShape
    选项
  • 主题支持(Material 3、Fluent)

Accessibility & Localization

无障碍与本地化

📄 Read: references/accessibility-localization.md
  • WCAG 2.0 compliance
  • Keyboard navigation and screen reader support
  • AutomationId
    for UI testing
  • Localization with
    .resx
    resource files
  • Supported localizable strings
  • RTL layout support
📄 阅读: references/accessibility-localization.md
  • 符合WCAG 2.0标准
  • 键盘导航和屏幕阅读器支持
  • 用于UI测试的
    AutomationId
  • 使用
    .resx
    资源文件进行本地化
  • 支持的可本地化字符串
  • RTL布局支持

Scrolling

滚动

📄 Read: references/scrolling.md
  • Programmatic scroll to a specific message (
    ScrollToMessage
    )
  • Auto-scroll to bottom on new message (
    CanAutoScrollToBottom
    )
  • Scroll to bottom floating button (
    ShowScrollToBottomButton
    )
  • Customizing the scroll to bottom button (
    ScrollToBottomButtonTemplate
    )
  • Scrolled
    event and
    ChatScrolledEventArgs
    (
    IsBottomReached
    ,
    IsTopReached
    ,
    ScrollOffset
    )
📄 阅读: references/scrolling.md
  • 编程式滚动到特定消息(
    ScrollToMessage
  • 新消息到来时自动滚动到底部(
    CanAutoScrollToBottom
  • 滚动到底部的浮动按钮(
    ShowScrollToBottomButton
  • 自定义滚动到底部按钮(
    ScrollToBottomButtonTemplate
  • Scrolled
    事件和
    ChatScrolledEventArgs
    IsBottomReached
    IsTopReached
    ScrollOffset

Advanced Features

高级功能

📄 Read: references/advanced-features.md
  • Message swiping (left/right,
    SwipeStarted
    ,
    SwipeEnded
    , swipe templates)
  • Time-break grouping (custom time-break template)
  • Attachment button (adding, customizing,
    AttachmentButtonView
    )
  • Liquid glass effect (enabling, platform support, customization)
  • MessageSpacing
    configuration
  • Hiding the message input view (
    ShowMessageInputView
    )

📄 阅读: references/advanced-features.md
  • 消息滑动(左/右滑动、
    SwipeStarted
    SwipeEnded
    、滑动模板)
  • 时间分段分组(自定义时间分段模板)
  • 附件按钮(添加、自定义、
    AttachmentButtonView
  • 液态玻璃效果(启用、平台支持、自定义)
  • MessageSpacing
    配置
  • 隐藏消息输入视图(
    ShowMessageInputView

Quick Start

快速开始

1. Install the NuGet package:
bash
dotnet add package Syncfusion.Maui.Chat
2. Register the handler in
MauiProgram.cs
:
csharp
using Syncfusion.Maui.Core.Hosting;

builder.ConfigureSyncfusionCore();
3. Add
SfChat
in XAML:
xml
<ContentPage xmlns:sfChat="clr-namespace:Syncfusion.Maui.Chat;assembly=Syncfusion.Maui.Chat"
             xmlns:local="clr-namespace:MyApp">
    <ContentPage.BindingContext>
        <local:ChatViewModel/>
    </ContentPage.BindingContext>
    <sfChat:SfChat Messages="{Binding Messages}"
                   CurrentUser="{Binding CurrentUser}" />
</ContentPage>
4. Define the ViewModel:
csharp
using Syncfusion.Maui.Chat;

public class ChatViewModel : INotifyPropertyChanged
{
    public ObservableCollection<object> Messages { get; set; }
    public Author CurrentUser { get; set; }

    public ChatViewModel()
    {
        CurrentUser = new Author { Name = "Nancy" };
        Messages = new ObservableCollection<object>
        {
            new TextMessage
            {
                Author = CurrentUser,
                Text = "Hello! How can I help you today?"
            },
            new TextMessage
            {
                Author = new Author { Name = "Bot", Avatar = "bot.png" },
                Text = "Hi Nancy! I am here to assist you."
            }
        };
    }

    public event PropertyChangedEventHandler PropertyChanged;
}

1. 安装NuGet包:
bash
dotnet add package Syncfusion.Maui.Chat
2. 在
MauiProgram.cs
中注册处理器:
csharp
using Syncfusion.Maui.Core.Hosting;

builder.ConfigureSyncfusionCore();
3. 在XAML中添加
SfChat
xml
<ContentPage xmlns:sfChat="clr-namespace:Syncfusion.Maui.Chat;assembly=Syncfusion.Maui.Chat"
             xmlns:local="clr-namespace:MyApp">
    <ContentPage.BindingContext>
        <local:ChatViewModel/>
    </ContentPage.BindingContext>
    <sfChat:SfChat Messages="{Binding Messages}"
                   CurrentUser="{Binding CurrentUser}" />
</ContentPage>
4. 定义ViewModel:
csharp
using Syncfusion.Maui.Chat;

public class ChatViewModel : INotifyPropertyChanged
{
    public ObservableCollection<object> Messages { get; set; }
    public Author CurrentUser { get; set; }

    public ChatViewModel()
    {
        CurrentUser = new Author { Name = "Nancy" };
        Messages = new ObservableCollection<object>
        {
            new TextMessage
            {
                Author = CurrentUser,
                Text = "Hello! How can I help you today?"
            },
            new TextMessage
            {
                Author = new Author { Name = "Bot", Avatar = "bot.png" },
                Text = "Hi Nancy! I am here to assist you."
            }
        };
    }

    public event PropertyChangedEventHandler PropertyChanged;
}

Common Patterns

常见模式

Sending a message and responding

发送消息并回复

csharp
// In ViewModel
public ICommand SendMessageCommand => new Command<object>(OnSendMessage);

private void OnSendMessage(object args)
{
    var e = args as SendMessageEventArgs;
    
    // ⚠️ IMPORTANT: By default, SfChat automatically adds the user's message to the 
    // Messages collection. Do NOT manually add it unless you set e.Handled = true
    
    // Add bot response after user sends message
    MainThread.BeginInvokeOnMainThread(async () =>
    {
        await Task.Delay(500); // Simulate processing
        Messages.Add(new TextMessage
        {
            Author = new Author { Name = "Bot", Avatar = "bot.png" },
            Text = $"You said: {e.Message.Text}"
        });
    });
}
If you need full control over message addition, set
Handled = true
:
csharp
private void OnSendMessage(object args)
{
    var e = args as SendMessageEventArgs;
    e.Handled = true; // Prevent SfChat from auto-adding the message
    
    // Now you must manually add the message
    if (e.Message is TextMessage textMessage)
    {
        Messages.Add(textMessage); // You add it
        
        // Then handle response...
    }
}
csharp
// 在ViewModel中
public ICommand SendMessageCommand => new Command<object>(OnSendMessage);

private void OnSendMessage(object args)
{
    var e = args as SendMessageEventArgs;
    
    // ⚠️ 重要提示:默认情况下,SfChat会自动将用户消息添加到
    // Messages集合中。除非设置e.Handled = true,否则请勿手动添加
    
    // 用户发送消息后添加机器人回复
    MainThread.BeginInvokeOnMainThread(async () =>
    {
        await Task.Delay(500); // 模拟处理过程
        Messages.Add(new TextMessage
        {
            Author = new Author { Name = "Bot", Avatar = "bot.png" },
            Text = $"You said: {e.Message.Text}"
        });
    });
}
如果需要完全控制消息添加,请设置
Handled = true
csharp
private void OnSendMessage(object args)
{
    var e = args as SendMessageEventArgs;
    e.Handled = true; // 阻止SfChat自动添加消息
    
    // 现在必须手动添加消息
    if (e.Message is TextMessage textMessage)
    {
        Messages.Add(textMessage); // 手动添加
        
        // 然后处理回复...
    }
}

Adding quick reply suggestions

添加快速回复建议

csharp
Messages.Add(new TextMessage
{
    Author = new Author { Name = "Bot" },
    Text = "How would you like to proceed?",
    Suggestions = new ObservableCollection<ISuggestion>
    {
        new Suggestion { Text = "Option A" },
        new Suggestion { Text = "Option B" }
    }
});
csharp
Messages.Add(new TextMessage
{
    Author = new Author { Name = "Bot" },
    Text = "How would you like to proceed?",
    Suggestions = new ObservableCollection<ISuggestion>
    {
        new Suggestion { Text = "Option A" },
        new Suggestion { Text = "Option B" }
    }
});

Showing a typing indicator

显示输入指示器

csharp
sfChat.ShowTypingIndicator = true;
sfChat.TypingIndicator = new TypingIndicator
{
    Authors = new ObservableCollection<Author>
    {
        new Author { Name = "Bot", Avatar = "bot.png" }
    },
    Text = "Bot is typing..."
};

csharp
sfChat.ShowTypingIndicator = true;
sfChat.TypingIndicator = new TypingIndicator
{
    Authors = new ObservableCollection<Author>
    {
        new Author { Name = "Bot", Avatar = "bot.png" }
    },
    Text = "Bot is typing..."
};

Key Properties

关键属性

PropertyTypePurpose
Messages
ObservableCollection<object>
Collection of all messages
CurrentUser
Author
Identifies the local user (outgoing messages)
ShowTypingIndicator
bool
Toggle typing indicator
TypingIndicator
TypingIndicator
Set who is typing
ShowDeliveryState
bool
Show sent/delivered/read/failed icons
AllowPinning
bool
Enable message pinning
MessageShape
MessageShape
Message bubble shape
MessageSpacing
double
Vertical gap between messages
ShowMessageInputView
bool
Show/hide the message editor
LoadMoreBehavior
LoadMoreOption
Enable load-more on scroll
AllowMultilineInput
bool
Allow multi-line message entry
ShowKeyboardAlways
bool
Keep keyboard open after send
属性类型用途
Messages
ObservableCollection<object>
所有消息的集合
CurrentUser
Author
标识本地用户(发送的消息)
ShowTypingIndicator
bool
切换输入指示器的显示状态
TypingIndicator
TypingIndicator
设置正在输入的用户
ShowDeliveryState
bool
显示已发送/已送达/已读/发送失败图标
AllowPinning
bool
启用消息固定功能
MessageShape
MessageShape
聊天气泡的形状
MessageSpacing
double
消息之间的垂直间距
ShowMessageInputView
bool
显示/隐藏消息编辑器
LoadMoreBehavior
LoadMoreOption
启用滚动加载更多功能
AllowMultilineInput
bool
允许多行消息输入
ShowKeyboardAlways
bool
发送消息后保持键盘打开状态