Xamarin.Forms 搜索栏

项目
04/25/2024

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

SearchBar 类定义以下属性：

CancelButtonColor 是一个 Color，用于定义取消按钮颜色。
CharacterSpacing，属于 double 类型，是 SearchBar 文本字符之间的间距。
FontAttributes 是一个 FontAttributes 枚举值，用于确定 SearchBar 字体是粗体、斜体还是两者都不是。
FontFamily 是一个 string，用于确定 SearchBar 使用的字体系列。
FontSize 可以是 NamedSize 枚举值，也可以是表示不同平台特定字体大小的 double 值。
HorizontalTextAlignment 是一个 TextAlignment 枚举值，用于定义查询文本的水平对齐方式。
VerticalTextAlignment 是一个 TextAlignment 枚举值，用于定义查询文本的垂直对齐方式。
Placeholder 是一个 string，用于定义占位符文本，例如“搜索...”。
PlaceholderColor 是一个 Color，用于定义占位符文本的颜色。
SearchCommand 是一个 ICommand，允许将用户操作（如手指点击或单击）绑定到 viewmodel 上定义的命令。
SearchCommandParameter 是一个 object，用于指定应传递给 SearchCommand 的参数。
Text 是一个 string，包含 SearchBar 中的查询文本。
TextColor 是一个 Color，用于定义查询文本的颜色。
TextTransform 是一个 TextTransform 值，用于确定 SearchBar 文本的大小写。

这些属性由 BindableProperty 对象提供支持，这意味着 SearchBar 可以自定义并成为数据绑定的目标。在 SearchBar 上指定字体属性的方式与自定义其他 Xamarin.Forms 文本控件上文本的方式一致。有关详细信息，请参阅 Xamarin.Forms 中的字体。

创建 SearchBar

可以在 XAML 中实例化 SearchBar。可以选择设置 Placeholder 属性来定义查询输入框中的提示文本。 Placeholder 的默认值为空字符串，因此如果未对其进行设置，则不会显示任何占位符。以下示例演示如何在 XAML 中实例化已设置可选 Placeholder 属性的 SearchBar：

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

还可以在代码中创建 SearchBar：

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

SearchBar 外观属性

SearchBar 控件定义许多用于自定义控件外观的属性。以下示例演示如何在 XAML 中使用多个指定的属性实例化 SearchBar：

<SearchBar Placeholder="Search items..."
           CancelButtonColor="Orange"
           PlaceholderColor="Orange"
           TextColor="Orange"
           TextTransform="Lowercase"
           HorizontalTextAlignment="Center"
           FontSize="Medium"
           FontAttributes="Italic" />

在代码中创建 SearchBar 对象时也可以指定这些属性：

SearchBar searchBar = new SearchBar
{
    Placeholder = "Search items...",
    PlaceholderColor = Color.Orange,
    TextColor = Color.Orange,
    TextTransform = TextTransform.Lowercase,
    HorizontalTextAlignment = TextAlignment.Center,
    FontSize = Device.GetNamedSize(NamedSize.Medium, typeof(SearchBar)),
    FontAttributes = FontAttributes.Italic
};

以下屏幕截图显示了生成的 SearchBar 控件：

注意

在 iOS 上，SearchBarRenderer 类包含可重写的 UpdateCancelButton 方法。此方法控制取消按钮何时出现，并可在自定义呈现器中重写。有关自定义呈现器的详细信息，请参阅Xamarin.Forms 自定义呈现器。

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

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

当用户单击搜索按钮或按 Enter 键时会调用 SearchButtonPressed。
每当查询框中的文本发生更改时会调用 TextChanged。

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

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

事件处理程序也可以附加到代码中创建的 SearchBar：

SearchBar searchBar = new SearchBar {/*...*/};
searchBar.TextChanged += OnTextChanged;

代码隐藏文件中的 TextChanged 事件处理程序是一样的，无论是通过 XAML 还是代码创建 SearchBar：

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

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

示例应用程序提供可用于测试搜索功能的 DataService 类实现。

使用 viewmodel 执行搜索

通过将 SearchCommand 和 SearchCommandParameter 属性绑定到 ICommand 实现，可以在不使用事件处理程序的情况下执行搜索。示例项目使用 Model-View-ViewModel (MVVM) 模式演示这些实现。有关 MVVM 数据绑定的详细信息，请参阅 MVVM 数据绑定。

示例应用程序中的 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 类。示例应用程序中可使用 DataService 类（包括示例数据）。

以下 XAML 演示如何将 SearchBar 绑定到示例 viewmodel，以及显示搜索结果的 ListView 控件：

<ContentPage ...>
    <ContentPage.BindingContext>
        <viewmodels:SearchViewModel />
    </ContentPage.BindingContext>
    <StackLayout ...>
        <SearchBar x:Name="searchBar"
                   ...
                   SearchCommand="{Binding PerformSearch}"
                   SearchCommandParameter="{Binding Text, Source={x:Reference searchBar}}"/>
        <ListView x:Name="searchResults"
                  ...
                  ItemsSource="{Binding SearchResults}" />
    </StackLayout>
</ContentPage>

此示例设置 BindingContext 作为 SearchViewModel 类的实例。它将 SearchCommand 属性绑定到 viewmodel 中的 PerformSearchICommand，并将 SearchBarText 属性绑定到 SearchCommandParameter 属性。 ListView.ItemsSource 属性绑定到 viewmodel 的 SearchResults 属性。

有关 ICommand 接口和绑定的详细信息，请参阅 Xamarin.Forms 数据绑定和 ICommand 接口。

Xamarin.Forms 搜索栏

创建 SearchBar

SearchBar 外观属性

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

使用 viewmodel 执行搜索

相关链接

其他资源