Avalonia AutoCompleteBox使用教程

Avalonia 的 AutoCompleteBox 是原生智能输入控件，需配置 ItemsSource、Text、Watermark 及 FilterMode；设 MinimumPrefixLength=0 并手动触发 IsDropDownOpen 可实现点击展开；支持 Custom 过滤与高亮；推荐 Ursa/Semi 主题优化样式。

Avalonia 中的 AutoCompleteBox 是一个开箱即用的智能输入控件，用于在用户输入时动态提供匹配建议。它不依赖第三方库，原生支持，但需注意几个关键配置点才能真正好用。

基础用法与数据绑定

最简方式是在 XAML 中声明控件并绑定数据源：

• ItemsSource 提供候选列表（如字符串数组、ObservableCollection）
• Text 双向绑定到 ViewModel 中的字符串属性，控制当前输入值
• Watermark 设置占位提示文字，提升可读性
• 推荐搭配 FilterMode="StartsWith" 或 "Contains"，按需选择匹配逻辑

示例（.axaml）：

让下拉列表及时响应点击

默认行为是：必须输入至少一个字符才弹出建议列表。若想点击控件就展开全部选项（类似 ComboBox），需两步调整：

• 将 MinimumPrefixLength 设为 0
• 监听 PointerPressed 或点击右侧箭头事件，在代码中设 IsDropDownOpen = true

若使用 Ursa.Avalonia 的增强版，它已内置点击展开逻辑，无需手动处理。

自定义过滤与高亮显示

当标准 FilterMode 不够用（比如要按用户对象的多个字段模糊匹配），可启用自定义过滤：

• 设置 FilterMode="Custom"
• 在代码中赋值 ItemFilter 委托，接收关键词和单个数据项，返回 true 表示匹配
• 配合 ItemTemplate 可高亮关键词（需自行实现文本分段+Span样式）

例如匹配 User.Name 和 User.Email：

this.FindControl("box").ItemFilter = (kw, item) => {
  var u = item as User;
  return u?.Name?.Contains(kw, StringComparison.OrdinalIgnoreCase) == true ||
         u?.Email?.Contains(kw, StringComparison.OrdinalIgnoreCase) == true;
};

样式与主题适配

Avalonia 原生控件样式较简朴，Ursa.Avalonia 或 Semi.Avalonia 提供了更现代的视觉方案：

• 引入命名空间：xmlns:u="https://irihi.tech/ursa"
• 确保已安装 Irihi.Ursa 和对应主题包（如 Irihi.Ursa.Themes.Semi）
• 通过 Styles 集成主题，并用 Classes 控制尺寸（如 Small、Bordered）

弹出层高度建议显式设置 MaxDropDownHeight，避免列表过长遮挡界面。