选取器

项目
08/30/2024

.NET Multi-platform App UI (.NET MAUI) Picker 显示简短的项列表，用户可从中选择一项。

Picker 定义以下属性：

CharacterSpacing，类型为 double，是 Picker 所显示项的字符之间的间距。
FontAttributes 类型的 FontAttributes，默认为 FontAtributes.None。
FontAutoScalingEnabled，类型为 bool，用于确定文本是否遵循操作系统中设置的缩放首选项。此属性的默认值为 true。
string 类型的 FontFamily，默认为 null。
double 类型的 FontSize，默认为 -1.0。
HorizontalTextAlignment，类型为 TextAlignment，是 Picker 显示的文本的水平对齐方式。
ItemsSource，类型为 IList，要显示的项源列表，默认为 null。
SelectedIndex，类型为 int，即所选项的索引，默认为 -1。
SelectedItem，类型为 object，为所选项，默认为 null。
如果 ItemSource 是复杂对象，则 ItemDisplayBinding（类型为 BindingBase）选择将为项列表中的每个对象显示的属性。有关详细信息，请参阅使用数据绑定为选取器填充数据。
TextColor，类型为 Color，用于显示文本的颜色。
TextTransform，类型为 TextTransform，用于定义是否转换文本的大小写。
Title，类型为 string，默认为 null。
TitleColor 类型为 Color，用于显示 Title 文本的颜色。
VerticalTextAlignment，类型为 TextAlignment，是 Picker 显示的文本的垂直对齐方式。

除 ItemDisplayBinding 之外的所有属性均由 BindableProperty 对象提供支持，这意味着可以对这些属性设置样式，并且这些属性可以是数据绑定的目标。 SelectedIndex 和 SelectedItem 属性的默认绑定模式为 BindingMode.TwoWay，这意味着它们可以成为使用模型-视图-视图模型 (MVVM) 模式的应用程序中数据绑定的目标。有关设置字体属性的信息，请参阅字体。

Picker 首次显示时不会显示任何数据。而是其 Title 属性值会显示为占位符，如下列 iOS 屏幕截图所示：

初始选取器显示的屏幕截图。

Picker 获得焦点时，会显示其数据，用户可选择一个项：

在选取器中选择项的屏幕截图。

用户选择一个项时，Picker 会触发 SelectedIndexChanged 事件。选择后，Picker 将显示所选项：

选择后选取器的屏幕截图。

有两种方法可用于以数据填充 Picker：

将 ItemsSource 属性设置为要显示的数据。这是向 Picker 添加数据的推荐方法。有关更多信息，请参阅设置 ItemsSource 属性。
将要显示的数据添加到 Items 集合中。有关更多信息，请参阅将数据添加到项集合。

设置 ItemsSource 属性

可以向 Picker 填充数据，方法是将其 ItemsSource 属性设置为 IList 集合。集合中的每个项都必须为 object 类型或派生自该类型。可以通过初始化项数组中的 ItemsSource 属性，在 XAML 中添加项：

<Picker x:Name="picker"
        Title="Select a monkey">
  <Picker.ItemsSource>
    <x:Array Type="{x:Type x:String}">
      <x:String>Baboon</x:String>
      <x:String>Capuchin Monkey</x:String>
      <x:String>Blue Monkey</x:String>
      <x:String>Squirrel Monkey</x:String>
      <x:String>Golden Lion Tamarin</x:String>
      <x:String>Howler Monkey</x:String>
      <x:String>Japanese Macaque</x:String>
    </x:Array>
  </Picker.ItemsSource>
</Picker>

注意

x:Array 元素需要用于指示数组中项类型的 Type 特性。

等效 C# 代码如下：

var monkeyList = new List<string>();
monkeyList.Add("Baboon");
monkeyList.Add("Capuchin Monkey");
monkeyList.Add("Blue Monkey");
monkeyList.Add("Squirrel Monkey");
monkeyList.Add("Golden Lion Tamarin");
monkeyList.Add("Howler Monkey");
monkeyList.Add("Japanese Macaque");

Picker picker = new Picker { Title = "Select a monkey" };
picker.ItemsSource = monkeyList;

响应项选择

Picker 支持一次选择一个项。当用户选择某个项时，将触发 SelectedIndexChanged 事件，SelectedIndex 属性将更新为表示列表中选定项的索引的整数，并将 SelectedItem 属性更新为表示所选项的 object。 SelectedIndex 属性是一个从零开始的数字，指示用户选择的项。如果未选择任何项（首次创建和初始化 Picker 时就是这种情况），则 SelectedIndex 将为 -1。

注意

可以在 iOS 上以特定于平台的方式自定义 Picker 中的项选择行为。有关详细信息，请参阅 iOS 上的 Picker 项选择。

以下 XAML 示例演示如何从 Picker 中检索 SelectedItem 属性值：

<Label Text="{Binding Source={x:Reference picker}, Path=SelectedItem}" />

等效 C# 代码如下：

Label monkeyNameLabel = new Label();
monkeyNameLabel.SetBinding(Label.TextProperty, new Binding("SelectedItem", source: picker));

此外，在触发 SelectedIndexChanged 事件时，可以执行事件处理程序：

void OnPickerSelectedIndexChanged(object sender, EventArgs e)
{
  var picker = (Picker)sender;
  int selectedIndex = picker.SelectedIndex;

  if (selectedIndex != -1)
  {
    monkeyNameLabel.Text = (string)picker.ItemsSource[selectedIndex];
  }
}

在此示例中，事件处理程序获取 SelectedIndex 属性值，并使用该值从 ItemsSource 集合中检索所选项。这在功能上等效于从 SelectedItem 属性中检索选定的项。 ItemsSource 集合中的每个项都是 object 类型，因此必须强制转换为 string 才能显示。

注意

通过设置 SelectedIndex 或 SelectedItem 属性，可以将 Picker 初始化为显示特定的项。但是，这些属性必须在初始化 ItemsSource 集合之后设置。

使用数据绑定，用数据填充选取器

还可以用数据填充 Picker，方法是通过使用数据绑定将其 ItemsSource 属性绑定到 IList 集合。在 XAML 中，此操作可通过使用 Binding 标记扩展实现：

<Picker Title="Select a monkey"
        ItemsSource="{Binding Monkeys}"
        ItemDisplayBinding="{Binding Name}" />

等效 C# 代码如下所示：

Picker picker = new Picker { Title = "Select a monkey" };
picker.SetBinding(Picker.ItemsSourceProperty, "Monkeys");
picker.ItemDisplayBinding = new Binding("Name");

在此示例中，ItemsSource 属性数据绑定到绑定上下文的 Monkeys 属性，后者返回 IList<Monkey> 集合。下面的代码示例显示 Monkey 类，它包含四个属性：

public class Monkey
{
  public string Name { get; set; }
  public string Location { get; set; }
  public string Details { get; set; }
  public string ImageUrl { get; set; }
}

绑定到对象列表时，必须告知 Picker 要从每个对象中显示哪个属性。这是通过将每个对象的 ItemDisplayBinding 属性设置为所需的属性来实现的。在上面的代码示例中，Picker 设置为显示每个 Monkey.Name 属性值。

响应项选择

数据绑定可用于在对象更改时将其设置为 SelectedItem 属性值：

<Picker Title="Select a monkey"
        ItemsSource="{Binding Monkeys}"
        ItemDisplayBinding="{Binding Name}"
        SelectedItem="{Binding SelectedMonkey}" />
<Label Text="{Binding SelectedMonkey.Name}" ... />
<Label Text="{Binding SelectedMonkey.Location}" ... />
<Image Source="{Binding SelectedMonkey.ImageUrl}" ... />
<Label Text="{Binding SelectedMonkey.Details}" ... />

等效 C# 代码如下：

Picker picker = new Picker { Title = "Select a monkey" };
picker.SetBinding(Picker.ItemsSourceProperty, "Monkeys");
picker.SetBinding(Picker.SelectedItemProperty, "SelectedMonkey");
picker.ItemDisplayBinding = new Binding("Name");

Label nameLabel = new Label { ... };
nameLabel.SetBinding(Label.TextProperty, "SelectedMonkey.Name");

Label locationLabel = new Label { ... };
locationLabel.SetBinding(Label.TextProperty, "SelectedMonkey.Location");

Image image = new Image { ... };
image.SetBinding(Image.SourceProperty, "SelectedMonkey.ImageUrl");

Label detailsLabel = new Label();
detailsLabel.SetBinding(Label.TextProperty, "SelectedMonkey.Details");

SelectedItem 属性数据绑定到绑定上下文的 SelectedMonkey 属性，其类型为 Monkey。因此，当用户在 Picker 中选择项时，SelectedMonkey 属性将被设置为所选的 Monkey 对象。 SelectedMonkey 对象数据通过 Label 和 Image 视图显示在用户界面中。

注意

默认情况下，SelectedItem 和 SelectedIndex 属性都支持双向绑定。

向项集合添加数据

用数据填充 Picker 的另一个过程是，将要显示的数据添加到只读的 Items 集合中，该集合的类型为 IList<string>。集合中的每个项都必须是 string 类型。通过使用 x:String 项的列表初始化 Items 属性，可以在 XAML 中添加项：

<Picker Title="Select a monkey">
  <Picker.Items>
    <x:String>Baboon</x:String>
    <x:String>Capuchin Monkey</x:String>
    <x:String>Blue Monkey</x:String>
    <x:String>Squirrel Monkey</x:String>
    <x:String>Golden Lion Tamarin</x:String>
    <x:String>Howler Monkey</x:String>
    <x:String>Japanese Macaque</x:String>
  </Picker.Items>
</Picker>

等效 C# 代码如下：

Picker picker = new Picker { Title = "Select a monkey" };
picker.Items.Add("Baboon");
picker.Items.Add("Capuchin Monkey");
picker.Items.Add("Blue Monkey");
picker.Items.Add("Squirrel Monkey");
picker.Items.Add("Golden Lion Tamarin");
picker.Items.Add("Howler Monkey");
picker.Items.Add("Japanese Macaque");

除了使用 Items.Add 方法添加数据外，还可以使用 Items.Insert 方法将数据插入到集合中。

响应项选择

Picker 支持一次选择一个项。当用户选择项时，将触发 SelectedIndexChanged 事件，并且 SelectedIndex 属性将更新为表示列表中所选项的索引的整数。 SelectedIndex 属性是一个从零开始的数字，表示用户选择的项。如果未选择任何项（首次创建和初始化 Picker 时就是这种情况），则 SelectedIndex 将为 -1。

注意

可以在 iOS 上以特定于平台的方式自定义 Picker 中的项选择行为。有关详细信息，请参阅 iOS 上的 Picker 项选择。

以下代码示例展示了 OnPickerSelectedIndexChanged 事件处理程序方法，该方法会在触发 SelectedIndexChanged 事件时执行：

void OnPickerSelectedIndexChanged(object sender, EventArgs e)
{
  var picker = (Picker)sender;
  int selectedIndex = picker.SelectedIndex;

  if (selectedIndex != -1)
  {
    monkeyNameLabel.Text = picker.Items[selectedIndex];
  }
}

此方法获取 SelectedIndex 属性值，并使用该值从 Items 集合中检索选定的项。因为 Items 集合中的每个项都是 string，所以它们可以由 Label 显示，而不需要强制转换。

注意

通过设置 SelectedIndex 属性，可以将 Picker 初始化为显示特定的项。但是，必须在初始化 Items 集合之后设置 SelectedIndex 属性。

通过

选取器

设置 ItemsSource 属性

响应项选择

使用数据绑定，用数据填充选取器

响应项选择

向项集合添加数据

响应项选择

其他资源