TableView

.NET Multi-platform App UI (.NET MAUI) TableView 显示一个可滚动项的表格，这些项可以分组到不同的部分中。 TableView 通常用于显示每行具有不同外观的项，例如显示设置表格。

重要

从 TableView 迁移到 CollectionView

TableView 在 .NET 10 中已弃用。对于大多数方案，应迁移到 CollectionView，后者使用定义 ItemTemplate 项外观而不是单元格。

TextCell/ImageCell/ViewCell →为项目类型定义 DataTemplate
SwitchCell/EntryCell →在项模板中撰写这些控件
分组→与IsGrouped="true"GroupHeaderTemplate / GroupFooterTemplate

Before （TableView with TextCell）：

<TableView Intent="Menu">
    <TableRoot>
        <TableSection Title="Chapters">
            <TextCell Text="1. Introduction" Detail="Overview" />
            <TextCell Text="2. Layouts" Detail="Grids, stacks" />
        </TableSection>
    </TableRoot>
 </TableView>

之后（具有 DataTemplate 的 CollectionView）：

<CollectionView ItemsSource="{Binding Chapters}">
    <CollectionView.ItemTemplate>
        <DataTemplate>
            <Grid ColumnDefinitions="*,Auto" Padding="12,8">
                <VerticalStackLayout>
                    <Label Text="{Binding Title}" FontAttributes="Bold" />
                    <Label Text="{Binding Detail}" FontSize="12" TextColor="Gray" />
                </VerticalStackLayout>
                <Image Grid.Column="1" Source="chevron.png" VerticalOptions="Center" />
            </Grid>
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

Before （带 SwitchCell 的 TableView）：

<TableView Intent="Settings">
    <TableRoot>
        <TableSection>
            <SwitchCell Text="Airplane Mode" On="False" />
        </TableSection>
    </TableRoot>
</TableView>

之后（包含组合控件的 CollectionView）：

<CollectionView ItemsSource="{Binding Settings}">
    <CollectionView.ItemTemplate>
        <DataTemplate x:DataType="local:SettingItem">
            <Grid ColumnDefinitions="*,Auto" Padding="12,8">
                <Label Text="{Binding Name}" VerticalOptions="Center" />
                <Switch Grid.Column="1"
                        IsToggled="{Binding IsOn, Mode=TwoWay}" />
            </Grid>
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

有关生成列表的指南，请参阅：

当 TableView 管理表的外观时，表中每个项的外观由 Cell 定义。 .NET MAUI 包含五种单元格类型，用于显示不同的数据组合，还可以定义自定义单元格来显示所需的任何内容。

TableView 定义以下属性：

Intent，类型为 TableIntent，用于定义 iOS 上表的用途。
HasUnevenRows，类型为 bool，指示表中的项是否可以具有不同行高。此属性的默认值为 false。
Root，类型为 TableRoot，定义 TableView 的子项。
RowHeight，类型为 int，确定当 HasUnevenRows 为 false 时每行的高度。

HasUnevenRows 和 RowHeight 属性由 BindableProperty 对象提供支持，这意味着它们可以是数据绑定的目标，并能进行样式设置。

在 iOS 上，Intent 属性的值仅用于定义 TableView 的外观。此属性应设置为 TableIntent 枚举的值，该枚举定义了以下成员：

Menu 用于显示可选菜单。
Settings 用于显示配置设置表。
Form 用于显示数据输入表单。
Data 用于显示数据。

注意

TableView 并非设计为支持绑定到一组项目。

创建表格视图

若要创建表，请创建一个 TableView 对象并将其 Intent 属性设置为 TableIntent 成员。 TableView 的子对象必须是 TableRoot 对象，该对象是一个或多个 TableSection 对象的父对象。每个 TableSection 都由一个可选标题（也可以设置其颜色）和一个或多个 Cell 对象组成。

下面的示例演示如何创建一个 TableView：

<TableView Intent="Menu">
    <TableRoot>
        <TableSection Title="Chapters">
            <TextCell Text="1. Introduction to .NET MAUI"
                      Detail="Learn about .NET MAUI and what it provides." />
            <TextCell Text="2. Anatomy of an app"
                      Detail="Learn about the visual elements in .NET MAUI" />
            <TextCell Text="3. Text"
                      Detail="Learn about the .NET MAUI controls that display text." />
            <TextCell Text="4. Dealing with sizes"
                      Detail="Learn how to size .NET MAUI controls on screen." />
            <TextCell Text="5. XAML vs code"
                      Detail="Learn more about creating your UI in XAML." />
        </TableSection>
    </TableRoot>
</TableView>

在此示例中，TableView 使用 TextCell 对象定义菜单：

注意

如果 TextCell 属性设置为有效的 Command 实现，则每个 ICommand 都可以在点击时执行命令。

定义单元格外观

TableView 中的每个项都由 Cell 对象定义，所使用的 Cell 类型将定义单元格数据的外观。 .NET MAUI 包含以下内置单元格：

TextCell 用于在单独的行上显示主文本和辅助文本。
ImageCell 用于在单独的行上显示带有主文本和辅助文本的图像。
SwitchCell 显示文本和一个可以打开或关闭的开关。
EntryCell 显示可编辑的标签和文本。
ViewCell 是一个自定义单元格，其外观由 View 定义。当想要完全定义 TableView 中每个项的外观时，应使用此单元格类型。

文本单元格

TextCell 在单独的行上显示主文本和辅助文本。 TextCell 定义以下属性：

Text，类型为 string，定义要显示的主文本。
TextColor，类型为 Color，表示主文本的颜色。
Detail，类型为 string，定义要显示的辅助文本。
DetailColor，类型为 Color，表示辅助文本的颜色。
Command，类型为 ICommand，定义点击单元格时执行的命令。
CommandParameter，类型为 object，表示传递给命令的参数。

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

以下示例显示如何使用 TextCell 来定义 TableView 中项的外观：

<TableView Intent="Menu">
    <TableRoot>
        <TableSection Title="Chapters">
            <TextCell Text="1. Introduction to .NET MAUI"
                      Detail="Learn about .NET MAUI and what it provides." />
            <TextCell Text="2. Anatomy of an app"
                      Detail="Learn about the visual elements in .NET MAUI" />
            <TextCell Text="3. Text"
                      Detail="Learn about the .NET MAUI controls that display text." />
            <TextCell Text="4. Dealing with sizes"
                      Detail="Learn how to size .NET MAUI controls on screen." />
            <TextCell Text="5. XAML vs code"
                      Detail="Learn more about creating your UI in XAML." />
        </TableSection>
    </TableRoot>
</TableView>

以下屏幕截图展示了生成的单元格外观：

图像单元格

ImageCell 在单独的行上显示包含主文本和辅助文本的图像。 ImageCell 继承来自 TextCell 的属性，并定义类型为 ImageSource 的 ImageSource 属性，该属性指定要在单元格中显示的图像。此属性由 BindableProperty 对象提供支持，这意味着它可以作为数据绑定的目标，并能进行样式设置。

以下示例展示了如何使用 ImageCell 定义 TableView 中项的外观：

<TableView Intent="Menu">
    <TableRoot>
        <TableSection Title="Learn how to use your XBox">
            <ImageCell Text="1. Introduction"
                       Detail="Learn about your XBox and its capabilities."
                       ImageSource="xbox.png" />
            <ImageCell Text="2. Turn it on"
                       Detail="Learn how to turn on your XBox."
                       ImageSource="xbox.png" />
            <ImageCell Text="3. Connect your controller"
                       Detail="Learn how to connect your wireless controller."
                       ImageSource="xbox.png" />
            <ImageCell Text="4. Launch a game"
                       Detail="Learn how to launch a game."
                       ImageSource="xbox.png" />
        </TableSection>
    </TableRoot>
</TableView>

以下屏幕截图展示了生成的单元格外观：

TableView 的屏幕截图，其中每个项都是 ImageCell。

切换单元格

SwitchCell 显示文本和可打开或关闭的开关。 SwitchCell 定义以下属性：

Text，类型为 string，定义要在开关旁边显示的文本。
On，类型为 bool，表示开关是打开还是关闭。
OnColor，类型为 Color，表示开关处于打开位置时的颜色。

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

SwitchCell 还定义在开关更改状态时引发的 OnChanged 事件。伴随此事件的 ToggledEventArgs 对象定义了一个 Value 属性，它指示开关是打开还是关闭。

以下示例显示如何使用 SwitchCell 来定义 TableView 中项的外观：

<TableView Intent="Settings">
    <TableRoot>
        <TableSection>
            <SwitchCell Text="Airplane Mode"
                        On="False" />
            <SwitchCell Text="Notifications"
                        On="True" />
        </TableSection>
    </TableRoot>
</TableView>

以下屏幕截图展示了生成的单元格外观：

TableView 的屏幕截图，其中每个项都是 SwitchCell。

输入单元格

EntryCell 显示可编辑的标签和文本数据。 EntryCell 定义以下属性：

HorizontalTextAlignment，类型为 TextAlignment，表示文本的水平对齐方式。
Keyboard，其类型为 Keyboard，决定输入文本时显示的键盘。
Label，类型为 string，表示要显示在可编辑文本左侧的文本。
LabelColor，类型为 Color，定义标签文本的颜色。
Placeholder，类型为 string，表示当 Text 属性为空时显示的文本。
Text，类型为 string，定义可编辑的文本。
VerticalTextAlignment，类型为 TextAlignment，表示文本的垂直对齐方式。

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

EntryCell 还定义在用户按下返回键时引发的 Completed 事件，以指示编辑已完成。

以下示例展示了如何使用 EntryCell 定义 TableView 中项的外观：

<TableView Intent="Settings">
    <TableRoot>
        <TableSection>
            <EntryCell Label="Login"
                       Placeholder="username" />
            <EntryCell Label="Password"
                       Placeholder="password" />
        </TableSection>
    </TableRoot>
</TableView>

以下屏幕截图展示了生成的单元格外观：

TableView 的屏幕截图，其中每个项都是一个 EntryCell。

视图单元格

ViewCell 是自定义单元格，其外观由 View 定义。 ViewCell 定义类型为 View 的 View 属性，该属性定义用于表示单元格内容的视图。此属性由 BindableProperty 对象提供支持，这意味着它可以作为数据绑定的目标，并能进行样式设置。

注意

由于 View 属性是 ViewCell 类的内容属性，因此不需要通过 XAML 显式设置。

以下示例展示了如何使用 ViewCell 定义 TableView 中项的外观：

<TableView Intent="Settings">
    <TableRoot>
        <TableSection Title="Silent">
            <ViewCell>
                <Grid RowDefinitions="Auto,Auto"
                      ColumnDefinitions="0.5*,0.5*">
                    <Label Text="Vibrate"
                           Margin="10,10,0,0"/>
                    <Switch Grid.Column="1"
                            HorizontalOptions="End" />
                    <Slider Grid.Row="1"
                            Grid.ColumnSpan="2"
                            Margin="10"
                            Minimum="0"
                            Maximum="10"
                            Value="3" />
                </Grid>
            </ViewCell>
        </TableSection>
    </TableRoot>
</TableView>

在 ViewCell 中，可以通过任何 .NET MAUI 布局来管理布局。以下屏幕截图展示了生成的单元格外观：

TableView 的屏幕截图，其中项是 ViewCell。

项目定尺寸

默认情况下，TableView 中相同类型的所有单元格都具有相同的高度。但是，可以使用 HasUnevenRows 和 RowHeight 属性更改此行为。默认情况下，HasUnevenRows 属性为 false。

RowHeight 属性可以设置为 int，表示 TableView 中每个项的高度，前提是 HasUnevenRows 为 false。当 HasUnevenRows 设置为 true 时，TableView 中的每个项可以具有不同的高度。每个项的高度将派生自每个单元格的内容，因此可根据每个项的内容设置其大小。

如果 HasUnevenRows 属性为 true，则可以通过更改单元格中元素的布局相关属性，在运行时以编程方式调整单个单元格的大小。下面的示例在点击单元格时更改单元格的高度：

void OnViewCellTapped(object sender, EventArgs e)
{
    label.IsVisible = !label.IsVisible;
    viewCell.ForceUpdateSize();
}

在此示例中，将执行 OnViewCellTapped 事件处理程序来响应点击单元格。事件处理程序更新 Label 对象的可见性，Cell.ForceUpdateSize 方法更新单元格的大小。如果 Label 已变为可见，则单元格的高度将增加。如果 Label 已设置为不可见，则单元格的高度将减小。

警告

过度使用动态项大小调整可能会导致 TableView 性能下降。

从右到左布局

TableView 可按从右到左的流方向布局其内容，方法是将其 FlowDirection 属性设置为 RightToLeft。但是，最好在页面或根布局上设置 FlowDirection 属性，以便页面或根布局中的所有元素都响应流方向：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="TableViewDemos.RightToLeftTablePage"
             Title="Right to left TableView"
             FlowDirection="RightToLeft">
    <TableView Intent="Settings">
        ...
    </TableView>
</ContentPage>

具有父元素的元素的默认 FlowDirection 是 MatchParent。因此，TableView 从 FlowDirection 继承 ContentPage 属性值。

反馈

此页面是否有帮助？

Last updated on 2025-08-28

通过

TableView

从 TableView 迁移到 CollectionView

创建表格视图

定义单元格外观

文本单元格

图像单元格

切换单元格

输入单元格

视图单元格

项目定尺寸

从右到左布局

反馈

其他资源