syncfusion-maui-chat
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSyncfusion .NET MAUI Chat (SfChat)
Syncfusion .NET MAUI Chat(SfChat)
The Syncfusion .NET MAUI Chat control () 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.
SfChatSyncfusion .NET MAUI Chat控件()为构建聊天机器人界面、客户支持界面和多用户消息交互体验提供了现代化的对话式UI。它支持丰富的消息类型、实时输入指示器、建议功能、加载更多历史记录、滑动操作以及深度样式自定义。
SfChatWhen 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 initialization in XAML and C#
SfChat - ViewModel setup with and
MessagesCurrentUser - Binding messages to the chat control
- Running the application
📄 阅读: references/getting-started.md
- NuGet安装()
Syncfusion.Maui.Chat - 在中注册处理器
MauiProgram.cs - 在XAML和C#中初始化基础
SfChat - 设置包含和
Messages的ViewModelCurrentUser - 将消息绑定到聊天控件
- 运行应用
Messages
消息
📄 Read: references/messages.md
- ,
TextMessage,DatePickerMessage,TimePickerMessageCalendarMessage - ,
HyperlinkMessage,ImageMessageCardMessage - Delivery states (,
ShowDeliveryStateenum, custom icons)DeliveryState - Pin message (,
AllowPinning, events, template)PinnedMessages - 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、TimePickerMessageCalendarMessage - 、
HyperlinkMessage、ImageMessageCardMessage - 送达状态(、
ShowDeliveryState枚举、自定义图标)DeliveryState - 消息固定(、
AllowPinning、事件、模板)PinnedMessages - 消息模板和
ChatMessageTemplateSelector - 可自定义的 incoming/outgoing 视图
- 消息间距、形状、时间戳格式、头像/发送者可见性
- 发送消息、键盘、多行输入、隐藏输入视图
Data Binding
数据绑定
📄 Read: references/data-binding.md
- Binding to
ObservableCollection<object>Messages - differentiation of sender/receiver
CurrentUser - Custom data models with /
IMessageITextMessage - for external model binding
ItemsSourceConverter - 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 - event and command
SuggestionItemSelected - 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 - event and
LoadMoreLoadMoreCommand - Loading older messages on scroll
- property
IsLazyLoading - Disabling after all messages are loaded
📄 阅读: references/load-more.md
- 启用加载更多功能()
LoadMoreBehavior - 事件和
LoadMoreLoadMoreCommand - 滚动时加载旧消息
- 属性
IsLazyLoading - 所有消息加载完成后禁用该功能
Events & Commands
事件与命令
📄 Read: references/events.md
- /
SendMessageSendMessageCommand - /
ImageTappedImageTappedCommand - /
CardTappedCardCommand SuggestionItemSelected- /
MessagePinnedMessageUnpinned - /
LoadMoreLoadMoreCommand - Handling and cancelling event args
📄 阅读: references/events.md
- /
SendMessageSendMessageCommand - /
ImageTappedImageTappedCommand - /
CardTappedCardCommand SuggestionItemSelected- /
MessagePinnedMessageUnpinned - /
LoadMoreLoadMoreCommand - 处理和取消事件参数
Styles & Appearance
样式与外观
📄 Read: references/styles.md
- Incoming and outgoing message styling
- Message input view styling
- Time-break and typing indicator styling
- Suggestion view styling
- options
MessageShape - 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
- for UI testing
AutomationId - Localization with resource files
.resx - 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 - event and
Scrolled(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, swipe templates)SwipeEnded - Time-break grouping (custom time-break template)
- Attachment button (adding, customizing, )
AttachmentButtonView - Liquid glass effect (enabling, platform support, customization)
- configuration
MessageSpacing - 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.Chat2. Register the handler in :
MauiProgram.cscsharp
using Syncfusion.Maui.Core.Hosting;
builder.ConfigureSyncfusionCore();3. Add in XAML:
SfChatxml
<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.Chat2. 在中注册处理器:
MauiProgram.cscsharp
using Syncfusion.Maui.Core.Hosting;
builder.ConfigureSyncfusionCore();3. 在XAML中添加:
SfChatxml
<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 = truecsharp
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 = truecsharp
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
关键属性
| Property | Type | Purpose |
|---|---|---|
| | Collection of all messages |
| | Identifies the local user (outgoing messages) |
| | Toggle typing indicator |
| | Set who is typing |
| | Show sent/delivered/read/failed icons |
| | Enable message pinning |
| | Message bubble shape |
| | Vertical gap between messages |
| | Show/hide the message editor |
| | Enable load-more on scroll |
| | Allow multi-line message entry |
| | Keep keyboard open after send |
| 属性 | 类型 | 用途 |
|---|---|---|
| | 所有消息的集合 |
| | 标识本地用户(发送的消息) |
| | 切换输入指示器的显示状态 |
| | 设置正在输入的用户 |
| | 显示已发送/已送达/已读/发送失败图标 |
| | 启用消息固定功能 |
| | 聊天气泡的形状 |
| | 消息之间的垂直间距 |
| | 显示/隐藏消息编辑器 |
| | 启用滚动加载更多功能 |
| | 允许多行消息输入 |
| | 发送消息后保持键盘打开状态 |