Cómo diseñar páginas PDF

El método PdfDocumentBuilder.Generate proporciona un objeto de tipo Document a su delegado. Utilice el método Pages de ese objeto para construir las páginas de su documento. Debe proporcionar un delegado que acepte un parámetro de tipo PageLayout para el método.

Una llamada al método es suficiente si todas las páginas de su documento PDF tienen el mismo diseño. En caso de que tenga diferentes diseños en su documento, utilice más de una llamada al método Pages. Por ejemplo, puede llamar al método una vez para diseñar una portada. Luego llame nuevamente al método para describir el cuerpo del informe.

Cada llamada a Pages crea al menos una página. La página creada puede estar vacía si no se le proporciona ningún contenido.

Este artículo es parte de una serie sobre la API Layout para la generación de PDF. Si es nuevo en la API, lea primero la parte Introducción a la API de Layout.

Espacios de contenido

Para describir el diseño de las páginas, utilice contenedores predefinidos. También los llamo espacios de contenido. Puede acceder a estos contenedores llamando a los métodos de un objeto PageLayout.

Hay tres espacios principales: Content, Header y Footer. Y dos espacios para contenido adicional: Background y Foreground. De forma predeterminada, los cinco contenedores están vacíos y no ocupan espacio en la página. Usted distribuye el contenido de su página entre los espacios según sus requisitos.

Lea el artículo Contenedores y su contenido para saber cómo diseñar sus páginas utilizando contenedores.

Encabezado y pié de página

No le sorprenderá saber que el contenido del encabezado y pie de página va a los espacios Header y Footer, respectivamente. La API repite estos espacios encima y debajo del contenido principal en cada página generada. La API de diseño nunca divide el contenido del encabezado o pie de página entre páginas. Obtendrá una LayoutException si un encabezado o pie de página no cabe en una página.

Contenido principal

El contenido de la página principal, como imágenes, tablas y texto, va al espacio Content. Layout API divide automáticamente ese contenido en páginas.

El siguiente código asigna contenido de texto simple a todos los espacios de contenido principales. El código también establece colores de fondo para las ranuras.

PdfDocumentBuilder.Create().Generate("pages-main-slots.pdf", doc => doc.Pages(pages => {
    pages.Header()
        .Text("This text goes to the header")
        .BackgroundColor(new PdfRgbColor(66, 135, 245));

    pages.Content()
        .Text("The main content goes in this slot")
        .BackgroundColor(new PdfRgbColor(242, 233, 206));

    pages.Footer()
        .Text("This is the footer contents")
        .BackgroundColor(new PdfRgbColor(194, 192, 188));
}));

Verifique el resultado del código en pages-main-slots.pdf.

Como puede ver, cada espacio ocupa solo una parte de la página. El área exacta depende del contenido dentro de la ranura. La ranura Header se sitúa en la parte superior de la página. El espacio Content comienza inmediatamente después del Header. La ranura Footer se pega a la parte inferior.

Contenido adicional

Background y Foreground proporcionan contenedores que se pueden utilizar para marcas de agua, superposiciones y fondos. Todo el contenido en el espacio Background va debajo del encabezado, el pie de página y el contenido principal de una página. El contenido en el espacio Foreground cubre todo lo agregado a la página.

Estos contenedores ocupan toda la página. Ésta es la característica única de estos contenedores. La API repite su contenido en cada página generada. Exactamente lo mismo que ocurre con los contenedores de encabezado y pie de página.

Agregué algunas líneas al código anterior para mostrar cómo usar los contenedores Foreground y Background.

PdfDocumentBuilder.Create().Generate("pages-all-slots.pdf", doc => doc.Pages(pages => {
    // ... 

    pages.Background()
        .Background(new PdfRgbColor(208, 227, 204));

    pages.Foreground()
        .Rotate(45)
        .Text(new string(' ', 30) + "Your watermark could go here, in the foreground");
}));

Para el contenedor Background, no proporciono ningún texto ni nada parecido. Sólo especifico el color de fondo. Todo lo que esté debajo del encabezado, el contenido principal y el pie de página mostrará ese tono de verde.

Giro el contenido en el contenedor Foreground y le agrego algo de texto. Debido a los espacios iniciales, el texto no cubre el contenido del encabezado ni del pie de página. El contenido de todos los contenedores es visible en la página.

Puede ver el resultado del código en pages-all-slots.pdf.

Ajustes

Hasta ahora, todos los fragmentos de código se centraban en los contenedores que componen las páginas. Es hora de ver cómo personalizar las páginas en sí, en lugar de sus espacios de contenido.

Para configurar páginas, utilice métodos de la clase PageLayout. Recuerde que un objeto PageLayout puede describir más de una página. Las llamadas a métodos afectarán a todas las páginas que describas.

Tamaño

Probablemente, la configuración más básica sea el tamaño de la página. Puede utilizar el método Size para especificar uno de los tamaños predefinidos para sus páginas. Hay todos los tamaños habituales, como A4, Ledger o Monarch.

Opcionalmente, puede especificar una orientación para las páginas. Es posible establecer un tamaño de página personalizado proporcionando su ancho y alto en puntos.

Márgenes

Los márgenes de las páginas pueden contribuir a la legibilidad, la estética y la composición general de sus páginas.

Establezca todos los márgenes al mismo valor en puntos usando el método Margin. Utilice los métodos MarginVertical y MarginHorizontal para establecer solo márgenes verticales u horizontales. Utilice los métodos MarginLeft/Top/Right/Bottom para especificar cada margen de forma independiente.

Estilo de texto

Layout API proporciona la clase TextStyle para crear estilos de texto. Usted crea y aplica estilos al texto para lograr la apariencia deseada.

Hay casos en los que gran parte del texto de tus páginas utiliza el mismo estilo. Puede establecer ese estilo como el estilo de texto predeterminado para las páginas. El estilo predeterminado afecta a todo el texto en los espacios de contenido principal. Pero puedes anular el estilo predeterminado para ciertos elementos. Simplemente aplique otro estilo a fragmentos de texto que deberían verse diferentes.

PdfDocumentBuilder.Create().Generate("pages-text-styles.pdf", doc =>
{
    var defaultStyle = TextStyle.Parent.FontSize(30);
    var tightSpacing = TextStyle.Parent.LetterSpacing(-0.1);

    doc.Pages(pages =>
    {
        pages.TextStyle(defaultStyle);

        pages.Content().Text(t =>
        {
            t.Line("This line uses the default text style.");
            t.Line("This line uses a tight letter spacing.").Style(tightSpacing);
            t.Line("This line uses the default text style, again.");
        });
    });
});

Puede ver el resultado del código en pages-text-styles.pdf.

Tenga en cuenta que puede configurar estilos de texto para todo el documento utilizando el método Document.Typography. Cada propiedad de la clase Typography define un estilo para un caso de uso. Estos estilos anulan el estilo especificado por el método PageLayout.TextStyle. Por ejemplo, la propiedad Typography.Body anula el estilo predeterminado para el texto en los contenedores Content.

Dirección de contenido

Hay idiomas escritos de derecha a izquierda. Layout API maneja bien el texto en estos idiomas. Pero necesitarás especificar explícitamente la dirección del texto.

Si la mayor parte del texto de sus páginas está en un idioma RTL, puede establecer de derecha a izquierda como la dirección de contenido predeterminada para las páginas. Podrás especificar una dirección diferente para cualquier contenedor en tus páginas.

PdfDocumentBuilder.Create().Generate("pages-content-direction.pdf", doc =>
{
    var defaultTextStyle = doc.TextStyleWithFont(SystemFont.Family("Calibri"));

    doc.Pages(pages =>
    {
        pages.Size(PdfPaperSize.A6).TextStyle(defaultTextStyle);

        pages.ContentFromRightToLeft();

        pages.Content().Column(column =>
        {
            column.Item()
                .ContentFromLeftToRight()
                .Text("There are languages written from right to left.");

            column.Item()
                .Text("هناك لغات تكتب من اليمين إلى اليسار.");

            column.Item()
                .Text("יש שפות שנכתבות מימין לשמאל.");
        });
    });
});

En el código anterior, configuré de derecha a izquierda como dirección de contenido predeterminada. Para el contenedor con la versión en inglés de la frase, cambio la dirección de izquierda a derecha. Puede ver el resultado del código en pages-content-direction.pdf.

Número de páginas

Al generar PDF, Layout API calcula automáticamente el número de página actual. También calcula el número total de páginas del documento. Puede obtener los números llamando a los métodos CurrentPageNumber y PageCount de cualquier contenedor de texto. No importa si el contenedor está en el encabezado, pie de página o espacio de contenido principal.

PdfDocumentBuilder.Create().Generate("pages-page-numbers.pdf", doc => doc.Pages(pages =>
{
    pages.Content().Text(t =>
    {
        t.Span("This line is on page ");
        t.CurrentPageNumber();
        t.Line();
        t.Line("Check the footer.");
    });

    pages.Footer().Row(r =>
    {
        r.AutoItem().Text("Created with Docotic.Pdf Layout API");

        r.RelativeItem(2).Text(t =>
        {
            t.AlignRight();

            t.Span("Page ");
            t.CurrentPageNumber();
            t.Span(" of ");
            t.PageCount();
        });
    });
}));

El resultado del código está en pages-page-numbers.pdf.

Ambos métodos devuelven TextPageNumber que puedes usar para formatear los números.

El ejemplo Agregar encabezado y pie de página a documentos PDF muestra cómo aplicar un formato personalizado a los números de página.

Código de muestra

Tenemos algunas aplicaciones de muestra que cubren con mayor detalle las funciones antes mencionadas. Dedique algún tiempo a revisarlos.

• Diseño de página en documentos PDF
• Agregar encabezado y pie de página a documentos PDF
• Estilo de texto