TableView

Esplorare l'esempio

L'interfaccia utente dell'app multipiattaforma .NET (.NET MAUI) TableView visualizza una tabella di elementi scorrevoli che possono essere raggruppati in sezioni. Un TableView oggetto viene in genere utilizzato per la visualizzazione di elementi in cui ogni riga ha un aspetto diverso, ad esempio la presentazione di una tabella di impostazioni.

Mentre TableView gestisce l'aspetto della tabella, l'aspetto di ogni elemento nella tabella è definito da un oggetto Cell. .NET MAUI include cinque tipi di cella usati per visualizzare diverse combinazioni di dati ed è anche possibile definire celle personalizzate che visualizzano qualsiasi contenuto desiderato.

TableView definisce le proprietà seguenti:

• Intent, di tipo TableIntent, definisce lo scopo della tabella in iOS.
• HasUnevenRows, di tipo bool, indica se gli elementi della tabella possono avere righe di altezze diverse. Il valore predefinito di questa proprietà è false.
• Root, di tipo TableRoot, definisce l'elemento figlio dell'oggetto TableView.
• RowHeight, di tipo int, determina l'altezza di ogni riga quando HasUnevenRows è false.

Le HasUnevenRows proprietà e RowHeight sono supportate da BindableProperty oggetti , il che significa che possono essere destinazioni di data binding e stili.

Il valore della Intent proprietà consente di definire l'aspetto TableView solo in iOS. Questa proprietà deve essere impostata su un valore dell'enumerazione TableIntent , che definisce i membri seguenti:

• Menu, per la presentazione di un menu selezionabile.
• Settings, per la presentazione di una tabella delle impostazioni di configurazione.
• Form, per la presentazione di un modulo di input dati.
• Data, per la presentazione dei dati.

Nota

TableView non è progettato per supportare l'associazione a una raccolta di elementi.

Creare un oggetto TableView

Per creare una tabella, creare un TableView oggetto e impostarne la Intent proprietà su un TableIntent membro. L'elemento figlio di un TableView oggetto deve essere un TableRoot oggetto padre di uno o più TableSection oggetti. Ognuno TableSection è costituito da un titolo facoltativo il cui colore può essere impostato e uno o più Cell oggetti.

Nell'esempio seguente viene illustrato come creare un oggetto 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>

In questo esempio, definisce TableView un menu usando TextCell oggetti :

Nota

Ogni TextCell oggetto può eseguire un comando quando viene toccato, purché la Command proprietà sia impostata su un'implementazione valida ICommand .

Definire l'aspetto della cella

Ogni elemento di un TableView oggetto è definito da un Cell oggetto e il Cell tipo utilizzato definisce l'aspetto dei dati della cella. .NET MAUI include le celle predefinite seguenti:

• TextCell, che visualizza il testo primario e secondario in righe separate.
• ImageCell, che visualizza un'immagine con testo primario e secondario su righe separate.
• SwitchCell, che visualizza il testo e un interruttore che può essere attivato o disattivato.
• EntryCell, che visualizza un'etichetta e un testo modificabili.
• ViewCell, ovvero una cella personalizzata il cui aspetto è definito da un oggetto View. Questo tipo di cella deve essere usato quando si desidera definire completamente l'aspetto di ogni elemento in un oggetto TableView.

Cella di testo

Un TextCell oggetto visualizza il testo primario e secondario su righe separate. TextCell definisce le proprietà seguenti:

• Text, di tipo string, definisce il testo primario da visualizzare.
• TextColor, di tipo Color, rappresenta il colore del testo primario.
• Detail, di tipo string, definisce il testo secondario da visualizzare.
• DetailColor, di tipo Color, indica il colore del testo secondario.
• Command, di tipo ICommand, definisce il comando eseguito quando viene toccata la cella.
• CommandParameter, di tipo object, rappresenta il parametro passato al comando .

Queste proprietà sono supportate da BindableProperty oggetti, il che significa che possono essere destinazioni di data binding e stili.

Nell'esempio seguente viene illustrato l'uso di per TextCell definire l'aspetto degli elementi in un TableViewoggetto :

<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>

Lo screenshot seguente mostra l'aspetto della cella risultante:

Cella Image

Un ImageCell oggetto visualizza un'immagine con testo primario e secondario su righe separate. ImageCell eredita le proprietà da TextCelle definisce la ImageSource proprietà di tipo ImageSource, che specifica l'immagine da visualizzare nella cella. Questa proprietà è supportata da un BindableProperty oggetto , il che significa che può essere la destinazione dei data binding e essere stilizzato.

Nell'esempio seguente viene illustrato l'uso di un ImageCell oggetto per definire l'aspetto degli elementi in un TableViewoggetto :

<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>

Lo screenshot seguente mostra l'aspetto della cella risultante:

Cambia cella

Un SwitchCell oggetto visualizza testo e un interruttore che può essere acceso o spento. SwitchCell definisce le proprietà seguenti:

• Text, di tipo string, definisce il testo da visualizzare accanto all'opzione.
• On, di tipo bool, indica se l'opzione è attivata o disattivata.
• OnColor, di tipo Color, indica il colore dell'interruttore quando è in posizione.

Queste proprietà sono supportate da BindableProperty oggetti, il che significa che possono essere destinazioni di data binding e stili.

SwitchCell definisce anche un OnChanged evento generato quando lo stato dell'opzione cambia. L'oggetto ToggledEventArgs che accompagna questo evento definisce una Value proprietà che indica se l'opzione è attivata o disattivata.

Nell'esempio seguente viene illustrato l'uso di per SwitchCell definire l'aspetto degli elementi in un TableViewoggetto :

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

Lo screenshot seguente mostra l'aspetto della cella risultante:

Cella entry

Un EntryCell oggetto visualizza un'etichetta e dati di testo modificabili. EntryCell definisce le proprietà seguenti:

• HorizontalTextAlignment, di tipo TextAlignment, rappresenta l'allineamento orizzontale del testo.
• Keyboard, di tipo Keyboard, determina la tastiera da visualizzare quando si immette testo.
• Label, di tipo string, rappresenta il testo da visualizzare a sinistra del testo modificabile.
• LabelColor, di tipo Color, definisce il colore del testo dell'etichetta.
• Placeholder, di tipo string, rappresenta il testo visualizzato quando la Text proprietà è vuota.
• Text, di tipo string, definisce il testo modificabile.
• VerticalTextAlignment, di tipo TextAlignment, rappresenta l'allineamento verticale del testo.

Queste proprietà sono supportate da BindableProperty oggetti, il che significa che possono essere destinazioni di data binding e stili.

EntryCell definisce anche un Completed evento generato quando l'utente raggiunge la chiave restituita per indicare che la modifica è stata completata.

Nell'esempio seguente viene illustrato l'uso di un EntryCell oggetto per definire l'aspetto degli elementi in un TableViewoggetto :

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

Lo screenshot seguente mostra l'aspetto della cella risultante:

Visualizzare la cella

Un ViewCell oggetto è una cella personalizzata il cui aspetto è definito da un oggetto View. ViewCell definisce una View proprietà di tipo View, che definisce la visualizzazione che rappresenta il contenuto della cella. Questa proprietà è supportata da un BindableProperty oggetto , il che significa che può essere la destinazione dei data binding e essere stilizzato.

Nota

La View proprietà è la proprietà content della ViewCell classe e pertanto non deve essere impostata in modo esplicito da XAML.

Nell'esempio seguente viene illustrato l'uso di per ViewCell definire l'aspetto di un elemento in un TableViewoggetto :

<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>

All'interno di , il ViewCelllayout può essere gestito da qualsiasi layout MAUI .NET. Lo screenshot seguente mostra l'aspetto della cella risultante:

Dimensioni elementi

Per impostazione predefinita, tutte le celle dello stesso tipo in un TableView hanno la stessa altezza. Tuttavia, questo comportamento può essere modificato con le HasUnevenRows proprietà e RowHeight . Per impostazione predefinita, la HasUnevenRows proprietà è false.

La RowHeight proprietà può essere impostata su un oggetto int che rappresenta l'altezza di ogni elemento nell'oggetto TableView, a condizione che HasUnevenRows sia false. Quando HasUnevenRows è impostato su true, ogni elemento in TableView può avere un'altezza diversa. L'altezza di ogni elemento verrà derivata dal contenuto di ogni cella e quindi ogni elemento verrà ridimensionato in base al relativo contenuto.

Le singole celle possono essere ridimensionate a livello di codice in fase di esecuzione modificando le proprietà correlate al layout degli elementi all'interno della cella, purché la HasUnevenRows proprietà sia true. L'esempio seguente modifica l'altezza della cella quando viene toccata:

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

In questo esempio il OnViewCellTapped gestore eventi viene eseguito in risposta alla cella toccata. Il gestore eventi aggiorna la visibilità dell'oggetto Label e il Cell.ForceUpdateSize metodo aggiorna le dimensioni della cella. Se l'oggetto Label è stato reso visibile, l'altezza della cella aumenterà. Se l'oggetto Label è stato reso invisibile, l'altezza della cella diminuisce.

Avviso

L'uso eccessivo del dimensionamento di elementi dinamici può causare TableView un peggioramento delle prestazioni.

Layout da destra a sinistra

TableView può eseguire il layout del contenuto in una direzione del flusso da destra a sinistra impostandone la FlowDirection proprietà su RightToLeft. Tuttavia, la FlowDirection proprietà deve essere impostata idealmente in un layout di pagina o radice, causando la risposta di tutti gli elementi all'interno della pagina o del layout radice alla direzione del flusso:

<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>

Il valore predefinito FlowDirection per un elemento con un elemento padre è MatchParent. Pertanto, TableView eredita il valore della FlowDirection proprietà da ContentPage.