syncfusion-maui-autocomplete

实现 .NET MAUI 自动补全

Syncfusion .NET MAUI 自动补全控件（SfAutocomplete）是一款功能强大的文本输入控件，可在用户输入时提供智能建议，支持筛选、多选和可自定义 UI，帮助用户快速录入数据并提升搜索体验。

何时使用此技能

当用户需要以下功能时，请使用此技能：

• 输入即搜索界面 - 在用户输入时筛选并显示建议
• 智能数据录入表单 - 根据预定义列表自动补全用户输入
• 多选输入 - 选择多个项目，并以令牌或标签形式显示
• 筛选下拉列表 - 高效搜索和筛选大型数据集
• AI 驱动的搜索 - 使用 Azure OpenAI 集成实现智能搜索
• 输入联想功能 - 提供预测文本建议
• 可搜索的组合框替代方案 - 提供具备搜索功能的增强型下拉列表
• 标签输入控件 - 支持以可视化令牌形式显示的多选

组件概览

SfAutocomplete 控件提供：

• 智能筛选 - 支持 StartsWith 和 Contains 搜索模式及自定义筛选器
• 灵活选择 - 支持单选或多选，并以令牌或分隔符形式显示
• 数据绑定 - 可绑定到任何数据源，并使用 DisplayMemberPath 和 TextMemberPath
• 自定义搜索逻辑 - 实现 IAutocompleteFilterBehavior，以执行高级筛选
• AI 集成 - 支持 Azure OpenAI，实现智能且能感知上下文的搜索
• 丰富的自定义选项 - 支持模板、样式、页眉、页脚和高亮显示
• 性能 - 支持异步加载、通过 LoadMore 分页以及高效渲染
• 无障碍功能 - 支持 AutomationId、键盘导航，并便于屏幕阅读器使用

文档和导航指南

入门

📄 阅读： references/getting-started.md

实现基本自动补全功能时：

• 安装和设置 NuGet 包（Syncfusion.Maui.Inputs）
• 使用 ConfigureSyncfusionCore 注册处理程序
• 在 XAML 和 C# 中实现基本控件
• 使用 ItemsSource、DisplayMemberPath、TextMemberPath 进行数据绑定
• 配置占位文本和基本属性
• 为 UI 测试设置 AutomationId

搜索和筛选

📄 阅读： references/searching-filtering.md

实现搜索和筛选逻辑时：

• 根据 DisplayMemberPath 和 TextMemberPath 进行搜索
• 配置 TextSearchMode（StartsWith、Contains）
• 设置 MinimumPrefixCharacters，控制搜索延迟
• 使用 IAutocompleteFilterBehavior 自定义筛选
• 使用 IAutocompleteSearchBehavior 自定义搜索高亮显示
• 支持取消的异步项目加载
• ShowSuggestionsOnFocus 行为

选择

📄 阅读： references/selection.md

处理项目选择时：

• 单选与多选模式
• SelectedItem、SelectedItems 属性
• SelectedValue 和 SelectedValuePath
• MultiSelectionDisplayMode（Token、Delimiter）
• 使用 TokensWrapMode（Wrap、None）设置令牌布局
• SelectionChanging 和 SelectionChanged 事件
• 配置清除按钮
• 使用 Clear() 方法以编程方式清除内容

UI 自定义

📄 阅读： references/ui-customization.md

自定义外观和行为时：

• 占位文本样式（文本、颜色）
• 自定义清除按钮（图标、颜色、路径）
• 下拉列表样式（高度、宽度、位置、背景）
• 项目模板和文本样式
• 多选令牌样式
• 边框和笔画自定义
• 文本对齐和光标位置
• ReturnType 和键盘行为
• 事件（Completed、DropDownOpening、ValueChanged 等）

高级功能

📄 阅读： references/advanced-features.md

实现高级功能时：

• 下拉列表中的页眉和页脚视图
• 文本高亮（FirstOccurrence、MultipleOccurrence）
• 自定义无结果提示
• 使用 AutoSizing 动态调整控件高度
• Liquid Glass Effect，打造现代 UI（.NET 10+）

AI 驱动的功能与 LoadMore

📄 阅读： references/ai-powered-loadmore.md

实现智能搜索或分页时：

• 集成 Azure OpenAI，实现智能搜索
• 使用 AI 服务进行自定义筛选
• 优化提示词，获得准确结果
• 使用 Soundex/Levenshtein 实现离线回退
• 使用 MaximumSuggestion 配置 LoadMore 功能
• 自定义 LoadMore（文本、模板、事件）

故障排除

📄 阅读： references/troubleshooting.md

遇到问题时：

• 特定平台的限制及解决方法
• AOT 发布注意事项
• 大型数据集的性能优化
• 常见问题及解决方案