通过

搜索栏

  • 项目

.NET Multi-platform App UI (.NET MAUI) SearchBar是用于启动搜索的用户输入控件。 SearchBar 控件支持占位符文本、查询输入、搜索执行和取消。 以下 iOS 屏幕截图显示了一个 SearchBar 查询，结果显示在 ListView 中：

搜索栏的屏幕截图。

SearchBar 定义以下属性：

  • CancelButtonColor 是一个 Color，用于定义取消按钮颜色。
  • HorizontalTextAlignment 是一个 TextAlignment 枚举值，用于定义查询文本的水平对齐方式。
  • SearchCommand 是一个 ICommand，允许将用户操作（如用手指点击或单击）绑定到 viewmodel 上定义的命令。
  • SearchCommandParameter 是一个 object，用于指定应传递给 SearchCommand 的参数。
  • VerticalTextAlignment 是一个 TextAlignment 枚举值，用于定义查询文本的垂直对齐方式。
  • CancelButtonColor 是一个 Color，用于定义取消按钮颜色。
  • HorizontalTextAlignment 是一个 TextAlignment 枚举值，用于定义查询文本的水平对齐方式。
  • SearchCommand 是一个 ICommand，允许将用户操作（如用手指点击或单击）绑定到 viewmodel 上定义的命令。
  • SearchCommandParameter 是一个 object，用于指定应传递给 SearchCommand 的参数。
  • SearchIconColor 是定义搜索图标颜色的 Color。
  • VerticalTextAlignment 是一个 TextAlignment 枚举值，用于定义查询文本的垂直对齐方式。

这些属性由 BindableProperty 对象提供支持，表示它们可以是数据绑定的目标，并可以设置样式。

此外，SearchBar 定义了一个 SearchButtonPressed 事件，当单击搜索按钮或按下 Enter 键时会引发该事件。

SearchBar 派生自 InputView 类，并从该类中继承以下属性：

  • CharacterSpacing，类型为 double，设置输入文本中字符之间的间距。
  • CursorPosition，类型为 int，用于定义游标在编辑器中的位置。
  • FontAttributes，类型为 FontAttributes，用于确定文本样式。
  • FontAutoScalingEnabled，类型为 bool，用于定义文本是否反映操作系统中设置的缩放首选项。 此属性的默认值为 true。
  • FontFamily 定义字体系列，类型是 string。
  • FontSize，类型为 double，定义字号。
  • IsReadOnly，类型为 bool，定义是否应阻止用户修改文本。 此属性的默认值为 false。
  • IsSpellCheckEnabled，类型为 bool，控制是否启用拼写检查。
  • IsTextPredictionEnabled，类型为 bool，控制是否启用文本预测和自动文本更正。
  • Keyboard，类型为 Keyboard，指定输入文本时显示的软输入键盘。
  • MaxLength，类型为 int，用于定义最大输入长度。
  • Placeholder，类型为 string，用于定义控件为空时显示的文本。
  • PlaceholderColor，类型为 Color，用于定义占位符文本的颜色。
  • SelectionLength，类型为 int，表示控件中选定文本的长度。
  • Text，类型为 string，用于定义输入控件中的文本。
  • TextColor，类型为 Color，用于定义输入文本的颜色。
  • TextTransform，类型为 TextTransform，用于指定输入文本的大小写。

这些属性由 BindableProperty 对象提供支持，表示它们可以是数据绑定的目标，并可以设置样式。

此外，InputView 定义了 TextChanged 事件，在 Entry 中更改文本时会引发该事件。 附带 TextChangedEventArgs 事件的 TextChanged 对象具有 NewTextValue 和 OldTextValue 属性，分别指定新文本和旧文本。

要创建搜索栏，请创建一个 SearchBar 对象并将其 Placeholder 属性设置为文本，以指示用户输入搜索词。

以下 XAML 示例演示如何创建 SearchBar：

<SearchBar Placeholder="Search items..." />

等效 C# 代码如下：

SearchBar searchBar = new SearchBar { Placeholder = "Search items..." };

注意

在 iOS 上，当字段靠近屏幕底部时，软输入键盘会覆盖文本输入字段，因此很难输入文本。 但是，在 .NET MAUI iOS 应用中，当软输入键盘覆盖文本输入字段时，页面会自动滚动，以便字段位于软输入键盘上方。 可以调用 KeyboardAutoManagerScroll.Disconnect 命名空间中的 Microsoft.Maui.Platform 方法来禁用此默认行为。 在禁用该行为后，可以调用 KeyboardAutoManagerScroll.Connect 方法来重新启用该行为。

使用事件处理程序执行搜索

通过将事件处理程序附加到下列事件之一，可以使用 SearchBar 控件执行搜索：

  • SearchButtonPressed，当用户单击搜索按钮或按 Enter 键时调用。
  • TextChanged，当查询框中的文本发生更改时调用。 此事件继承自 InputView 类。

以下 XAML 示例显示了附加到 TextChanged 事件的事件处理程序，并使用 ListView 显示搜索结果：

<SearchBar TextChanged="OnTextChanged" />
<ListView x:Name="searchResults" >

在此示例中，TextChanged 事件被设置为名为 OnTextChanged 的事件处理程序。 此处理程序位于后台代码文件中：

void OnTextChanged(object sender, EventArgs e)
{
    SearchBar searchBar = (SearchBar)sender;
    searchResults.ItemsSource = DataService.GetSearchResults(searchBar.Text);
}

在此示例中，带有 DataService 方法的 GetSearchResults 类用于返回与查询匹配的项。 系统将 SearchBar 控件的 Text 属性值传递给 GetSearchResults 方法，并将结果用于更新 ListView 控件的 ItemsSource 属性。 总体效果是搜索结果显示在 ListView 中。

使用 viewmodel 执行搜索

通过将 SearchCommand 属性绑定到 ICommand 实现，可在不使用事件处理程序的情况下执行搜索。 有关命令的详细信息，请参阅命令。

以下示例显示了包含名为 ICommand 的 PerformSearch 属性的 viewmodel 类：

public class SearchViewModel : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler PropertyChanged;

    protected virtual void NotifyPropertyChanged([CallerMemberName] string propertyName = "")
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }

    public ICommand PerformSearch => new Command<string>((string query) =>
    {
        SearchResults = DataService.GetSearchResults(query);
    });

    private List<string> searchResults = DataService.Fruits;
    public List<string> SearchResults
    {
        get
        {
            return searchResults;
        }
        set
        {
            searchResults = value;
            NotifyPropertyChanged();
        }
    }
}

注意

viewmodel 假定存在能够执行搜索的 DataService 类。

以下 XAML 示例使用 SearchViewModel 类：

<ContentPage ...
             xmlns:viewmodels="clr-namespace:SearchBarDemos.ViewModels"
             x:DataType="viewmodels:SearchViewModel">
    <ContentPage.BindingContext>
        <viewmodels:SearchViewModel />
    </ContentPage.BindingContext>
    <StackLayout>
        <SearchBar x:Name="searchBar"
                   SearchCommand="{Binding PerformSearch}"
                   SearchCommandParameter="{Binding Text, x:DataType='SearchBar', Source={x:Reference searchBar}}"/>
        <ListView x:Name="searchResults"
                  ItemsSource="{Binding SearchResults}" />
    </StackLayout>
</ContentPage>

在此示例中，BindingContext 被设置为 SearchViewModel 类的实例。 SearchBar.SearchCommand 属性绑定到 PerformSearch viewmodel 属性，SearchCommandParameter 属性绑定到 SearchBar.Text 属性。 同样地，ListView.ItemsSource 属性绑定到 viewmodel 的 SearchResults 属性。

隐藏并显示软输入键盘

SoftInputExtensions 命名空间中的 Microsoft.Maui 类，提供一系列支持在允许文本输入的控件上与软输入键盘交互的扩展方法。 该类定义以下方法：

  • IsSoftInputShowing，检查设备当前是否显示软输入键盘。
  • HideSoftInputAsync，会尝试隐藏软输入键盘（如果当前显示）。
  • ShowSoftInputAsync，会尝试显示软输入键盘（如果当前已隐藏）。

以下示例展示了如何隐藏名为 SearchBar 的 searchBar 上的软输入键盘（如果当前正在显示）：

if (searchBar.IsSoftInputShowing())
   await searchBar.HideSoftInputAsync(System.Threading.CancellationToken.None);