Página maestra y de detalles de Xamarin.FormsXamarin.Forms Master-Detail Page

Descargar ejemplo Descargar el ejemploDownload Sample Download the sample

MasterDetailPage de Xamarin.Forms es una página que administra dos páginas relacionadas de información: una página maestra que presenta elementos y una página de detalles que presenta detalles sobre los elementos de la página maestra. En este artículo se explica cómo usar una instancia de MasterDetailPage y cómo navegar entre sus páginas de información.The Xamarin.Forms MasterDetailPage is a page that manages two related pages of information – a master page that presents items, and a detail page that presents details about items on the master page. This article explains how to use a MasterDetailPage and navigate between its pages of information.

Información generalOverview

Normalmente, una página maestra presenta una lista de elementos, como se muestra en las siguientes capturas de pantalla:A master page typically displays a list of items, as shown in the following screenshots:

La ubicación de la lista de elementos es idéntica en cada plataforma; al seleccionar uno de los elementos, se le lleva a la página de detalles correspondiente.The location of the list of items is identical on each platform, and selecting one of the items will navigate to the corresponding detail page. Además, la página maestra también incluye una barra de navegación que contiene un botón que se puede usar para ir a la página de detalles activa:In addition, the master page also features a navigation bar that contains a button that can be used to navigate to the active detail page:

  • En iOS, la barra de navegación se encuentra en la parte superior de la página y tiene un botón que lleva a la página de detalles.On iOS, the navigation bar is present at the top of the page and has a button that navigates to the detail page. Además, se puede ir a la página de detalles activa si se desliza la página maestra hacia la izquierda.In addition, the active detail page can be navigated to by swiping the master page to the left.
  • En Android, la barra de navegación se encuentra en la parte superior de la página y presenta un título, un icono y un botón que lleva a la página de detalles.On Android, the navigation bar is present at the top of the page and displays a title, an icon, and a button that navigates to the detail page. El icono se define en el atributo [Activity] que decora la clase MainActivity en el proyecto específico de la plataforma Android.The icon is defined in the [Activity] attribute that decorates the MainActivity class in the Android platform-specific project. Además, se puede ir a la página de detalles activa si se desliza la página maestra hacia la izquierda, si se puntea en el extremo derecho de la pantalla en la página de detalles y si se pulsa el botón Atrás situado en la parte inferior de la pantalla.In addition, the active detail page can be navigated to by swiping the master page to the left, by tapping the detail page at the far right of the screen, and by tapping the Back button at the bottom of the screen.
  • En Plataforma universal de Windows (UWP), la barra de navegación se encuentra en la parte superior de la página y tiene un botón que lleva a la página de detalles.On the Universal Windows Platform (UWP), the navigation bar is present at the top of the page and has a button that navigates to the detail page.

Una página de detalles presenta datos correspondientes al elemento seleccionado en la página maestra; los componentes principales de la página de detalles se muestran en las capturas de pantalla siguientes:A detail page displays data that corresponds to the item selected on the master page, and the main components of the detail page are shown in the following screenshots:

La página de detalles contiene una barra de navegación cuyo contenido depende de la plataforma:The detail page contains a navigation bar, whose contents are platform-dependent:

  • En iOS, la barra de navegación se encuentra en la parte superior de la página, muestra un título y tiene un botón que devuelve a la página maestra, siempre que la instancia de la página de detalles esté incluida en la instancia de NavigationPage.On iOS, the navigation bar is present at the top of the page and displays a title, and has a button that returns to the master page, provided that the detail page instance is wrapped in the NavigationPage instance. Además, se puede volver a la página maestra si se desliza la página de detalles hacia la derecha.In addition, the master page can be returned to by swiping the detail page to the right.
  • En Android, hay una barra de navegación en la parte superior de la página que muestra un título, un icono y un botón que devuelve a la página maestra.On Android, a navigation bar is present at the top of the page and displays a title, an icon, and a button that returns to the master page. El icono se define en el atributo [Activity] que decora la clase MainActivity en el proyecto específico de la plataforma Android.The icon is defined in the [Activity] attribute that decorates the MainActivity class in the Android platform-specific project.
  • En UWP, la barra de navegación se encuentra en la parte superior de la página, muestra un título y tiene un botón que devuelve a la página maestra.On UWP, the navigation bar is present at the top of the page and displays a title, and has a button that returns to the master page.

El comportamiento de la experiencia de navegación entre las páginas maestra y de detalles depende de la plataforma:The behavior of the navigation experience between master and detail pages is platform dependent:

  • En iOS, la página de detalles se desliza hacia la derecha cuando la página maestra se desliza desde la izquierda, y la parte izquierda de la página de detalles sigue siendo visible.On iOS, the detail page slides to the right as the master page slides from the left, and the left part of the detail page is still visible.
  • En Android, las páginas maestra y de detalles se superponen.On Android, the detail and master pages are overlaid on each other.
  • En UWP, la página maestra se desplaza desde el lateral izquierdo de la página de detalles, siempre que la propiedad MasterBehavior esté establecida en Popover.On UWP, the master page slides from the left over part of the detail page, provided that the MasterBehavior property is set to Popover. Para obtener más información, consulte Control del comportamiento de presentación de la página de detalles.For more information, see Controlling the Detail Page Display Behavior.

En el modo horizontal se observa un comportamiento similar, salvo que la página maestra en iOS y Android tiene un ancho similar al de la página maestra en modo vertical, así que se ve más superficie de la página de detalles.Similar behavior will be observed in landscape mode, except that the master page on iOS and Android has a similar width as the master page in portrait mode, so more of the detail page will be visible.

Para obtener información sobre cómo controlar el comportamiento de navegación, vea Control del comportamiento de presentación de la página de detalles.For information about controlling the navigation behavior, see Controlling the Detail Page Display Behavior.

Creación de MasterDetailPageCreating a MasterDetailPage

Una instancia de MasterDetailPage contiene propiedades Master y Detail que son de tipo Page y se usan para obtener y establecer las páginas maestra y de detalles, respectivamente.A MasterDetailPage contains Master and Detail properties that are both of type Page, which are used to get and set the master and detail pages respectively.

Importante

Una instancia de MasterDetailPage está diseñada para ser una página raíz. Su empleo como página secundaria en otros tipos de páginas podría dar lugar a un comportamiento inesperado e incoherente.A MasterDetailPage is designed to be a root page, and using it as a child page in other page types could result in unexpected and inconsistent behavior. Además, se recomienda que la página maestra de una instancia de MasterDetailPage siempre sea una instancia de ContentPage y que la página de detalles solo se rellene con instancias de TabbedPage, NavigationPage y ContentPage.In addition, it's recommended that the master page of a MasterDetailPage should always be a ContentPage instance, and that the detail page should only be populated with TabbedPage, NavigationPage, and ContentPage instances. Esto ayuda a garantizar una experiencia de usuario coherente en todas las plataformas.This will help to ensure a consistent user experience across all platforms.

El ejemplo de código XAML siguiente muestra una instancia de MasterDetailPage que establece las propiedades Master y Detail:The following XAML code example shows a MasterDetailPage that sets the Master and Detail properties:

<MasterDetailPage xmlns="http://xamarin.com/schemas/2014/forms"
                  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                  xmlns:local="clr-namespace:MasterDetailPageNavigation;assembly=MasterDetailPageNavigation"
                  x:Class="MasterDetailPageNavigation.MainPage">
    <MasterDetailPage.Master>
        <local:MasterPage x:Name="masterPage" />
    </MasterDetailPage.Master>
    <MasterDetailPage.Detail>
        <NavigationPage>
            <x:Arguments>
                <local:ContactsPage />
            </x:Arguments>
        </NavigationPage>
    </MasterDetailPage.Detail>
</MasterDetailPage>

En el ejemplo de código siguiente se muestra la instancia de MasterDetailPage equivalente creada en C#:The following code example shows the equivalent MasterDetailPage created in C#:

public class MainPageCS : MasterDetailPage
{
    MasterPageCS masterPage;

    public MainPageCS ()
    {
        masterPage = new MasterPageCS ();
        Master = masterPage;
        Detail = new NavigationPage (new ContactsPageCS ());
        ...
    }
    ...
}

La propiedad MasterDetailPage.Master está establecida en una instancia de ContentPage.The MasterDetailPage.Master property is set to a ContentPage instance. La propiedad MasterDetailPage.Detail está establecida en una instancia de NavigationPage que contiene una instancia de ContentPage.The MasterDetailPage.Detail property is set to a NavigationPage containing a ContentPage instance.

Creación de la página maestraCreating the Master Page

El ejemplo de código XAML siguiente muestra la declaración del objeto MasterPage, al que se hace referencia mediante la propiedad MasterDetailPage.Master:The following XAML code example shows the declaration of the MasterPage object, which is referenced through the MasterDetailPage.Master property:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="using:MasterDetailPageNavigation"
             x:Class="MasterDetailPageNavigation.MasterPage"
             Padding="0,40,0,0"
             IconImageSource="hamburger.png"
             Title="Personal Organiser">
    <StackLayout>
        <ListView x:Name="listView" x:FieldModifier="public">
           <ListView.ItemsSource>
                <x:Array Type="{x:Type local:MasterPageItem}">
                    <local:MasterPageItem Title="Contacts" IconSource="contacts.png" TargetType="{x:Type local:ContactsPage}" />
                    <local:MasterPageItem Title="TodoList" IconSource="todo.png" TargetType="{x:Type local:TodoListPage}" />
                    <local:MasterPageItem Title="Reminders" IconSource="reminders.png" TargetType="{x:Type local:ReminderPage}" />
                </x:Array>
            </ListView.ItemsSource>
            <ListView.ItemTemplate>
                <DataTemplate>
                    <ViewCell>
                        <Grid Padding="5,10">
                            <Grid.ColumnDefinitions>
                                <ColumnDefinition Width="30"/>
                                <ColumnDefinition Width="*" />
                            </Grid.ColumnDefinitions>
                            <Image Source="{Binding IconSource}" />
                            <Label Grid.Column="1" Text="{Binding Title}" />
                        </Grid>
                    </ViewCell>
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
    </StackLayout>
</ContentPage>

La página consta de un elemento ListView que se rellena con datos de XAML al establecer su propiedad ItemsSource en una matriz de instancias de MasterPageItem.The page consists of a ListView that's populated with data in XAML by setting its ItemsSource property to an array of MasterPageItem instances. Cada MasterPageItem define propiedades Title, IconSource y TargetType.Each MasterPageItem defines Title, IconSource, and TargetType properties.

Se asigna un elemento DataTemplate a la propiedad ListView.ItemTemplate para mostrar cada MasterPageItem.A DataTemplate is assigned to the ListView.ItemTemplate property, to display each MasterPageItem. DataTemplate contiene un elemento ViewCell que consta de un elemento Image y un Label.The DataTemplate contains a ViewCell that consists of an Image and a Label. Image muestra el valor de la propiedad IconSource y Label muestra el valor de la propiedad Title, para cada MasterPageItem.The Image displays the IconSource property value, and the Label displays the Title property value, for each MasterPageItem.

La página tiene establecidas sus propiedades Title y IconImageSource.The page has its Title and IconImageSource properties set. El icono aparece en la página de detalles, siempre que esta tenga una barra de título.The icon will appear on the detail page, provided that the detail page has a title bar. Esta debe habilitarse en iOS al incluir la instancia de la página de detalles en una instancia de NavigationPage.This must be enabled on iOS by wrapping the detail page instance in a NavigationPage instance.

Nota

La página MasterDetailPage.Master debe tener su propiedad Title establecida, o se produce una excepción.The MasterDetailPage.Master page must have its Title property set, or an exception will occur.

En el ejemplo de código siguiente se muestra la página equivalente creada en C#:The following code example shows the equivalent page created in C#:

public class MasterPageCS : ContentPage
{
  public ListView ListView { get { return listView; } }

  ListView listView;

  public MasterPageCS ()
  {
    var masterPageItems = new List<MasterPageItem> ();
    masterPageItems.Add (new MasterPageItem {
      Title = "Contacts",
      IconSource = "contacts.png",
      TargetType = typeof(ContactsPageCS)
    });
    masterPageItems.Add (new MasterPageItem {
      Title = "TodoList",
      IconSource = "todo.png",
      TargetType = typeof(TodoListPageCS)
    });
    masterPageItems.Add (new MasterPageItem {
      Title = "Reminders",
      IconSource = "reminders.png",
      TargetType = typeof(ReminderPageCS)
    });

    listView = new ListView {
      ItemsSource = masterPageItems,
      ItemTemplate = new DataTemplate (() => {
        var grid = new Grid { Padding = new Thickness(5, 10) };
        grid.ColumnDefinitions.Add(new ColumnDefinition { Width = new GridLength(30) });
        grid.ColumnDefinitions.Add(new ColumnDefinition { Width = GridLength.Star });

        var image = new Image();
        image.SetBinding(Image.SourceProperty, "IconSource");
        var label = new Label { VerticalOptions = LayoutOptions.FillAndExpand };
        label.SetBinding(Label.TextProperty, "Title");

        grid.Children.Add(image);
        grid.Children.Add(label, 1, 0);

        return new ViewCell { View = grid };
      }),
      SeparatorVisibility = SeparatorVisibility.None
    };

    IconImageSource = "hamburger.png";
    Title = "Personal Organiser";
    Content = new StackLayout
    {
      Children = { listView }
    };
  }
}

En las capturas de pantalla siguientes se muestra la página maestra en cada plataforma:The following screenshots show the master page on each platform:

Creación y presentación de la página de detallesCreating and Displaying the Detail Page

La instancia de MasterPage contiene una propiedad ListView que expone su instancia de ListView para que el elemento MainPage de la instancia de MasterDetailPage pueda registrar un controlador de eventos para controlar el evento ItemSelected.The MasterPage instance contains a ListView property that exposes its ListView instance so that the MainPage MasterDetailPage instance can register an event-handler to handle the ItemSelected event. Esto permite a la instancia de MainPage establecer la propiedad Detail en la página que representa al elemento seleccionado ListView.This enables the MainPage instance to set the Detail property to the page that represents the selected ListView item. En el ejemplo de código siguiente se muestra el controlador de eventos:The following code example shows the event-handler:

public partial class MainPage : MasterDetailPage
{
    public MainPage ()
    {
        ...
        masterPage.listView.ItemSelected += OnItemSelected;
    }

    void OnItemSelected (object sender, SelectedItemChangedEventArgs e)
    {
        var item = e.SelectedItem as MasterPageItem;
        if (item != null) {
            Detail = new NavigationPage ((Page)Activator.CreateInstance (item.TargetType));
            masterPage.listView.SelectedItem = null;
            IsPresented = false;
        }
    }
}

El método OnItemSelected realiza las siguientes acciones:The OnItemSelected method performs the following actions:

  • Recupera el elemento SelectedItem de la instancia de ListView y, siempre que no sea null, establece la página de detalles en una nueva instancia del tipo de página almacenado en la propiedad TargetType de MasterPageItem.It retrieves the SelectedItem from the ListView instance, and provided that it's not null, sets the detail page to a new instance of the page type stored in the TargetType property of the MasterPageItem. El tipo de página se incluye en una instancia de NavigationPage para asegurarse de que el icono al que se hace referencia mediante la propiedad IconImageSource en MasterPage se muestre en la página de detalles en iOS.The page type is wrapped in a NavigationPage instance to ensure that the icon referenced through the IconImageSource property on the MasterPage is shown on the detail page in iOS.
  • El elemento seleccionado en ListView se estable en null para asegurarse de que ninguno de los elementos ListView se seleccione la próxima vez que el elemento MasterPage esté presente.The selected item in the ListView is set to null to ensure that none of the ListView items will be selected next time the MasterPage is presented.
  • La página de detalles se presenta al usuario al establecer la propiedad MasterDetailPage.IsPresented en false.The detail page is presented to the user by setting the MasterDetailPage.IsPresented property to false. Esta propiedad controla si se presenta la página maestra o de detalles.This property controls whether the master or detail page is presented. Se debe establecer en true para mostrar la página maestra y en false para mostrar la página de detalles.It should be set to true to display the master page, and to false to display the detail page.

Las capturas de pantalla siguientes muestran la página de detalles ContactPage, que se presenta después de haberse seleccionado en la página maestra:The following screenshots show the ContactPage detail page, which is shown after it's been selected on the master page:

Control del comportamiento de presentación de la página de detallesControlling the Detail Page Display Behavior

La forma en que MasterDetailPage administre las páginas maestra y de detalles depende de si la aplicación se ejecuta en un teléfono o tableta, de la orientación del dispositivo y del valor de la propiedad MasterBehavior.How the MasterDetailPage manages the master and detail pages depends on whether the application is running on a phone or tablet, the orientation of the device, and the value of the MasterBehavior property. Esta propiedad determina cómo se muestra la página de detalles.This property determines how the detail page will be displayed. Sus posibles valores son:It's possible values are:

  • Default: las páginas se muestran con el valor predeterminado de la plataforma.Default – The pages are displayed using the platform default.
  • Popover: la página de detalles cubre, o cubre parcialmente, la página maestra.Popover – The detail page covers, or partially covers the master page.
  • Split: la página maestra se muestra a la izquierda y la página de detalles a la derecha.Split – The master page is displayed on the left and the detail page is on the right.
  • SplitOnLandscape: se usa una pantalla dividida cuando el dispositivo está en orientación horizontal.SplitOnLandscape – A split screen is used when the device is in landscape orientation.
  • SplitOnPortrait: se usa una pantalla dividida cuando el dispositivo está en orientación vertical.SplitOnPortrait – A split screen is used when the device is in portrait orientation.

En el siguiente ejemplo de código XAML se muestra cómo establecer la propiedad MasterBehavior en una instancia de MasterDetailPage:The following XAML code example demonstrates how to set the MasterBehavior property on a MasterDetailPage:

<?xml version="1.0" encoding="UTF-8"?>
<MasterDetailPage xmlns="http://xamarin.com/schemas/2014/forms"
                  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                  x:Class="MasterDetailPageNavigation.MainPage"
                  MasterBehavior="Popover">
  ...
</MasterDetailPage>

En el ejemplo de código siguiente se muestra la instancia de MasterDetailPage equivalente creada en C#:The following code example shows the equivalent MasterDetailPage created in C#:

public class MainPageCS : MasterDetailPage
{
    MasterPageCS masterPage;

    public MainPageCS ()
    {
        MasterBehavior = MasterBehavior.Popover;
        ...
    }
}

Pero el valor de la propiedad MasterBehavior solo afecta a las aplicaciones que se ejecutan en el escritorio o en tabletas.However, the value of the MasterBehavior property only affects applications running on tablets or the desktop. Las aplicaciones que se ejecutan en teléfonos siempre tienen el comportamiento Popover.Applications running on phones always have the Popover behavior.

ResumenSummary

En este artículo se ha explicado cómo usar una instancia de MasterDetailPage y cómo navegar entre sus páginas de información.This article demonstrated how to use a MasterDetailPage and navigate between its pages of information. MasterDetailPage de Xamarin.Forms es una página que administra dos páginas de información relacionada: una página maestra que presenta elementos y una página de detalles que muestra detalles sobre elementos de la página maestra.The Xamarin.Forms MasterDetailPage is a page that manages two pages of related information – a master page that presents items, and a detail page that presents details about items on the master page.