Esta página puede contener texto traducido automáticamente.

Creación de archivos PDF con la API principal

Logotipo cuadrado de Bit Miracle
Traducido por Bit Miracle. Artículo original de Sergey Bobrovsky
Actualizado el 5 de mayo de 2026

La API principal de Docotic.Pdf ofrece un control total sobre la creación de PDF. Permite dibujar texto, imágenes y gráficos vectoriales en lienzos proporcionados por páginas PDF, XObjects y patrones de mosaico.

Controlas cada coordenada y cada operación de dibujo, lo que te brinda un control máximo sobre el diseño de tus páginas PDF. Para documentos con gran cantidad de gráficos o diseños personalizados donde la precisión es fundamental, este nivel de control es indispensable.

Con la API principal, también puedes agregar anotaciones, campos de formulario, capas, marcadores y más a los PDF creados. La API es la forma más flexible y potente de crear PDF en .NET que ofrece Docotic.Pdf.

Ilustración de las capacidades de la API principal para la creación de archivos PDF, que muestra gráficos vectoriales, colocación de imágenes y dibujo de texto.

Consulte el artículo que describe todos los métodos para crear archivos PDF si desea una visión general más amplia de todos los enfoques disponibles en Docotic.Pdf, incluidos aquellos que van más allá de la API principal.

Antes de comenzar

Antes de empezar a trabajar con la API principal, configure su entorno instalando Docotic.Pdf y solicitando una clave de licencia.

Instalar Docotic.Pdf

Para crear documentos PDF en C# o VB.NET, comience por instalar la biblioteca desde NuGet.

Install-Package BitMiracle.Docotic.Pdf

Si prefiere instalar la biblioteca manualmente, descargue el archivo ZIP con los binarios de la biblioteca, descomprímalo y agregue una referencia desde su proyecto al archivo BitMiracle.Docotic.Pdf.dll.

Obtén una clave de licencia

Se requiere una clave de licencia para usar la biblioteca. Para probarla, solicite una clave de licencia gratuita por tiempo limitado completando el formulario en la página de descarga de Docotic.Pdf.

Ejemplos básicos de creación de PDF

Esta sección proporciona ejemplos básicos que demuestran cómo crear documentos PDF con la API principal, primero en C# y luego en VB.NET.

Cómo crear un PDF en C#

Ahora que ha instalado Docotic.Pdf y obtenido una clave de licencia, es fácil crear un PDF con la API principal.

BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

using var pdf = new PdfDocument();
pdf.Save("empty.pdf");

El código muestra cómo crear un archivo PDF vacío. La primera línea añade una clave de licencia. Sin licencia, se producirá una excepción en la línea que instancia un PdfDocument. La última línea guarda el documento como un archivo PDF.

La estructura interna del archivo creado depende de las opciones de guardado. En este ejemplo, el código utiliza la sobrecarga del método Save, que guarda con las opciones predeterminadas. Para comprender qué hacen estas opciones predeterminadas y cuándo conviene ajustarlas, consulte la sección sobre opciones de guardado.

Para respetar la tradición de la programación, el segundo ejemplo muestra un programa "Hola, mundo" creado con la API Core.

using var pdf = new PdfDocument();

var page = pdf.Pages[0];
page.Canvas.DrawString(50, 50, "Hello, world!");

pdf.Save("hello.pdf");

El código coloca la frase clásica en el lienzo de la primera página del documento, comenzando en la posición especificada. La línea utiliza la fuente y el tamaño de fuente predeterminados. Continúe leyendo para obtener más información sobre cómo trabajar con el lienzo PDF.

Uso de VB.NET para crear archivos PDF

El código VB.NET para crear un PDF es muy similar al código de la sección anterior.

Using pdf As New PdfDocument()
    Dim page = pdf.Pages(0)
    page.Canvas.DrawString(50, 50, "Hello, world!")

    pdf.Save("hello.pdf")
End Using

La sección anterior, que incluye un ejemplo en C#, explica qué hace el código y cómo funciona.

Trabajar con lienzo PDF

Para modificar el lienzo en un documento PDF, utilice la API Canvas. Esta API forma parte de la API Core.

La API Canvas utiliza un modelo de posicionamiento absoluto. Usted define las coordenadas y el lienzo se dibuja exactamente donde usted lo indique. El sistema de coordenadas sitúa el origen en la esquina superior izquierda de la página. Las coordenadas aumentan hacia la derecha en el eje X y hacia abajo en el eje Y.

(0,0) ──► X
  │
  │
  ▼
  Y

Texto de dibujo

En la clase PdfCanvas, Docotic.Pdf proporciona dos métodos principales para renderizar texto: DrawString y DrawText. Ambos métodos utilizan la fuente del lienzo actual, por lo que se recomienda configurar la fuente necesaria antes de dibujar cualquier texto.

Usando DrawString

DrawString siempre dibuja una sola línea de texto. El método comienza a dibujar desde la posición actual del texto en el lienzo, a menos que se utilice una sobrecarga con coordenadas explícitas. Algunas sobrecargas permiten especificar opciones adicionales que controlan cómo se dibuja la línea de texto.

Ya viste un ejemplo sencillo de DrawString en el fragmento de código «¡Hola, mundo!». Aquí tienes otro ejemplo que utiliza opciones de dibujo de cadenas para subrayar texto.

using var pdf = new PdfDocument();

var canvas = pdf.Pages[0].Canvas;
canvas.DrawString(50, 50, "This text is underlined", new PdfStringDrawingOptions
{
    Underline = true,
});

pdf.Save("underlined-text.pdf");

Usando DrawText

La función DrawText permite dibujar varias líneas de texto dentro de un rectángulo específico. Este método gestiona los saltos de línea y recorta el texto que no cabe en el espacio permitido. Las opciones de dibujo de texto definen la alineación horizontal y vertical del texto, así como otros aspectos de su posicionamiento y representación.

A continuación, se muestra cómo dibujar texto en un PDF usando C#:

using var pdf = new PdfDocument();

const string LongString = "Lorem ipsum dolor sit amet, consectetur adipisicing elit";
var multiLineOptions = new PdfTextDrawingOptions(new PdfRectangle(70, 70, 40, 150))
{
    HorizontalAlignment = PdfTextAlign.Left,
    VerticalAlignment = PdfVerticalAlign.Top
};

var canvas = pdf.Pages[0].Canvas;
canvas.DrawText(LongString, multiLineOptions);

pdf.Save("drawtext.pdf");

Para ajustar con precisión la apariencia del texto, puede modificar las siguientes propiedades del lienzo:

  • Espaciado entre caracteres
  • Espaciado entre palabras
  • Escalado del texto
  • Elevación del texto (desplazamiento de la línea base)
  • Modo de representación (relleno, contorno, relleno y contorno, entre otros)

Para ver ejemplos prácticos de métodos y propiedades relacionados con el texto, consulte el Grupo de ejemplos de texto.

Agregar y usar fuentes

A menos que te conformes con la fuente Helvetica predeterminada, deberías añadir las fuentes que necesites al PDF para asegurarte de que el texto se muestre exactamente como deseas.

Docotic.Pdf puede añadir fuentes Type1, TrueType, Compact Font Format (CFF) y OpenType desde:

  • la colección de fuentes instaladas en el sistema
  • archivos y flujos externos

Además, puedes usar las 14 fuentes Type1 integradas, disponibles en cualquier visor de PDF.

Para usar una fuente en tu PDF, crea un objeto PdfFont usando el método CreateFont o CreateFontFromFile del objeto PdfDocument correspondiente. Luego, asigna la fuente al lienzo antes de dibujar el texto. También es recomendable configurar el tamaño de la fuente.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var font = pdf.CreateFont("NSimSun");
canvas.Font = font;
canvas.FontSize = 14;
canvas.DrawString(10, 50, "Olá. 你好. Hello, Unicode!");

font.RemoveUnusedGlyphs();

pdf.Save("unicode-text.pdf");

La fuente debe contener glifos para todos los caracteres del texto que intenta dibujar. De lo contrario, recibirá una excepción CannotShowTextException. Utilice PdfFont.ContainsGlyphsForText para verificar que la fuente contiene todos los glifos necesarios.

La compatibilidad con Unicode depende del tipo de fuente. Las fuentes de tipo 1 solo admiten el conjunto de caracteres y la codificación latinos, con una excepción. Las fuentes integradas Symbol y ZapfDingbats proporcionan símbolos matemáticos, griegos y decorativos.

Las fuentes TrueType, CFF y OpenType suelen ser compatibles con Unicode, pero es posible que no incluyan glifos para todos los caracteres Unicode.

Docotic.Pdf intenta incrustar la menor cantidad posible de bytes de fuente para mantener el PDF resultante pequeño. Sin embargo, cuando un documento utiliza fuentes con muchos glifos, el archivo resultante puede ser relativamente grande. Utilice PdfFont.RemoveUnusedGlyphs para minimizar la cantidad de bytes añadidos por las fuentes incrustadas.

Cálculo de las dimensiones del texto

Dado que la API de Canvas utiliza posicionamiento absoluto, a menudo es necesario saber cuánto espacio ocupará un texto antes de dibujarlo. Esto es especialmente importante al generar texto en varias partes, como al dividir cadenas largas, alinear texto con precisión o evitar superposiciones con otro contenido. La clase PdfCanvas proporciona varios métodos que ayudan a medir el texto utilizando la fuente y el tamaño de fuente seleccionados.

Utilice PdfCanvas.MeasureText para obtener tanto el ancho como la altura de una cadena tal como aparecería en el lienzo. Algunos casos de uso típicos incluyen:

  • determinar si el texto cabe en un área determinada
  • calcular saltos de línea manualmente
  • posicionar bloques de texto entre sí

Para los casos en los que se centra o alinea texto a la derecha y solo se necesita la extensión horizontal, utilice PdfCanvas.GetTextWidth. Para conocer la altura de una línea de texto con la fuente actual, utilice PdfCanvas.GetTextHeight.

Dibujos de imágenes

Para dibujar una imagen en un lienzo PDF, primero crea un objeto PdfImage y luego dibuja ese objeto usando el método PdfCanvas.DrawImage.

A continuación, se muestra cómo agregar una imagen a un PDF en C#:

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var image = pdf.CreateImage("image.png");
canvas.DrawImage(image, 10, 50);

pdf.Save("image.pdf");

El código crea un objeto de imagen mediante el método CreateImage del objeto PdfDocument correspondiente y dibuja la imagen en el lienzo de la primera página.

Para obtener más información sobre los formatos de imagen compatibles y las técnicas avanzadas de conversión de imágenes a PDF, consulte la sección sobre cómo crear archivos PDF a partir de imágenes.

Utilizando gráficos vectoriales

Docotic.Pdf permite dibujar líneas rectas, curvas de Bézier y formas geométricas comunes directamente sobre un lienzo PDF mediante los métodos de la clase PdfCanvas. Utilice los métodos que comienzan con Draw (por ejemplo, DrawLineTo, DrawCircle, DrawRectangle) para colocar marcas visibles en el lienzo.

Las líneas y curvas se dibujan con el lápiz actual, definido mediante PdfCanvas.Pen, que especifica el color, el grosor y otras propiedades del trazo. Según el modo de dibujo, las formas pueden tener trazo, relleno o trazo y relleno. El pincel actual, al que se accede mediante PdfCanvas.Brush, se utiliza para rellenar el interior de las formas.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.DrawCircle(new PdfPoint(60, 100), 40);
canvas.DrawRectangle(
    new PdfRectangle(300, 60, 110, 70),
    PdfDrawMode.Fill);

canvas.CurrentPosition = new PdfPoint(150, 90);
canvas.DrawCurveTo(new PdfPoint(180, 60), new PdfPoint(230, 120), new PdfPoint(250, 90));

pdf.Save("curve-and-shapes.pdf");

Cada lienzo PDF mantiene un estado gráfico que incluye el lápiz, el pincel, la fuente y las posiciones actuales. Utilice SaveState para conservar el estado actual y RestoreState para restaurar un estado anterior. Además de revertir transformaciones temporales y cambios similares, restaurar el estado es la única forma de eliminar el recorte una vez aplicado.

Las rutas gráficas permiten crear formas complejas a partir de líneas, curvas y formas más simples sin dibujarlas inmediatamente. Utilice métodos de Append como AppendLineTo o AppendRectangle para añadir segmentos a la ruta actual. Las rutas no generan resultados visibles hasta que se rellenan o se trazan explícitamente.

Puede utilizar cualquier ruta gráfica creada como región de recorte para restringir las operaciones de dibujo posteriores. El recorte permanece activo hasta que se restaura el estado gráfico.

Encontrará ejemplos prácticos y ejecutables de cómo trabajar con gráficos vectoriales en la sección Gráficos del repositorio de ejemplos.

Configuración de colores y transparencia

Puedes cambiar los colores del trazo y del relleno mediante el lápiz y el pincel de un lienzo PDF. Para ello, utiliza PdfPen.Color y PdfBrush.Color.

Ilustración de formas coloridas que gotean, algunas lisas y otras estampadas, que muestran las capacidades de la API principal para colores y transparencia.

Los espacios de color compatibles, que dependen del dispositivo, incluyen Gray, RGB y CMYK, representados por PdfGrayColor, PdfRgbColor y PdfCmykColor.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.Pen.Color = new PdfRgbColor(30, 60, 160);
canvas.Pen.Width = 3;

canvas.Brush.Color = new PdfCmykColor(0, 20, 5, 0);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

pdf.Save("fill-and-stroke-colors.pdf");

Docotic.Pdf admite espacios de color CIE independientes del dispositivo, incluyendo colores L*a*b* y colores calibrados basados ​​en ICC. La API principal también admite colores directos y espacios de color de separación para flujos de trabajo que requieren tintas personalizadas o salida específica para cada canal.

El código de ejemplo a continuación muestra cómo crear colores Lab, colores basados ​​en perfiles y colores directos. Para ejecutar el ejemplo, primero descargue el perfil ICC que utiliza.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var labColorSpace = new PdfLabColorSpace(pdf, [0.5, 1, 0.5]);
canvas.Pen.Color = new PdfLabColor(labColorSpace, 50, -50, 50);
canvas.Pen.Width = 3;

var rgbProfile = pdf.CreateColorProfile("AdobeCompat-v2.icc");
canvas.Brush.Color = new PdfRgbColor(rgbProfile, 210, 105, 30);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

var tintTransform = new PdfExponentialFunction(
    pdf, 1, [0d, 0, 0, 0], [0, 0.8, 0.73, 0.25], [0d, 1]);
var separationColorSpace = new PdfSeparationColorSpace(
    pdf, "BLOODRED", new PdfCmykColorSpace(), tintTransform);
canvas.Pen.Color = new PdfSpotColor(1.0, separationColorSpace);

canvas.DrawCircle(new PdfPoint(100, 70), 60);

pdf.Save("using-special-colors.pdf");

También puedes trazar y rellenar formas usando patrones de mosaico. Un patrón se define mediante una celda dibujada en su propio lienzo. Existen dos tipos:

  • Patrones de color. Sus celdas definen sus propios colores.
  • Patrones sin color. Sus celdas se tiñen con el color del lápiz o pincel en el momento de su uso.

Para usar un patrón, créalo usando CreateColoredPattern o CreateUncoloredPattern del objeto PdfDocument correspondiente. Luego, aplica el patrón mediante PdfPen.Pattern y/o PdfBrush.Pattern. Consulta el código de ejemplo para crear y usar patrones en el repositorio de ejemplos.

Los colores semitransparentes te permiten dibujar formas, texto e imágenes con opacidad variable. Usa PdfPen.Opacity y PdfBrush.Opacity para producir colores translúcidos.

Además, los modos de fusión controlan cómo interactúa el contenido transparente con lo que se encuentra debajo. Para cambiar el modo de fusión de un lienzo, utilice PdfCanvas.BlendMode.

Agregar y personalizar páginas

Docotic.Pdf expone la colección PdfDocument.Pages, que permite gestionar todas las páginas de un documento. La clase PdfDocument cuenta con dos métodos principales para añadir páginas: AddPage e InsertPage.

Utilice AddPage() para añadir una página al final del documento. Para insertar una página en cualquier posición, utilice InsertPage(index). Ambos métodos devuelven la instancia de PdfPage recién creada.

Cada página nueva tiene un tamaño predeterminado de 595 x 842 unidades de espacio de usuario. Este es el tamaño de una hoja A4. En la mayoría de los casos, la unidad de espacio de usuario en PDF equivale a 1/72 de pulgada. Dicho de otro modo, una unidad de espacio de usuario equivale a un píxel cuando la resolución de la página es de 72 píxeles por pulgada.

Puede cambiar el tamaño de una página en cualquier momento estableciendo su ancho y/o alto en un número específico de unidades de espacio de usuario.

using var pdf = new PdfDocument();
var page = pdf.Pages[0];

page.Width = 600;
page.Height = 800;

Otra opción es utilizar uno de los tamaños predefinidos:

page.Size = PdfPaperSize.Ledger;

También es posible cambiar la orientación de la página de vertical a horizontal, y girarla 90°, 180° o 270° en el sentido de las agujas del reloj.

page.Orientation = PdfPaperOrientation.Landscape;
page.Rotation = PdfRotation.Rotate180;

Además de establecer el ancho, la altura o un tamaño predefinido de la página, también es posible ajustar el tamaño de la página junto con recortar o redimensionar el contenido existente.

Reutilización de contenido con XObjects

Un XObject PDF es un contenedor con gráficos vectoriales, imágenes y texto. Cada XObject tiene su propio lienzo, lo que permite crear XObjects tan complejos como páginas PDF convencionales.

Los XObjects son similares a las imágenes vectoriales. Se puede reutilizar el mismo objeto en varias páginas sin necesidad de recrear el contenido ni aumentar el tamaño del documento. Además, se pueden escalar y rotar sin generar distorsiones visuales. Gracias a estas características, los XObjects son ideales para elementos repetidos como logotipos, ilustraciones, fondos, marcas de agua y otros gráficos recurrentes.

Creación y uso de XObjects

Para crear un XObject, utilice el método PdfDocument.CreateXObject. Modifique el ancho y la altura del objeto, si es necesario. A continuación, rellene el lienzo con texto, imágenes y gráficos del mismo modo que en un lienzo de página normal.

Utilice el método PdfCanvas.DrawXObject en su código C# o VB.NET para añadir el XObject a otros lienzos. Tenga en cuenta que puede dibujar XObjects en lienzos proporcionados tanto por páginas como por otros XObjects.

A continuación, se muestra un código C# que crea un XObject con una ilustración y la dibuja en dos páginas.

using var pdf = new PdfDocument();

var xobj = pdf.CreateXObject();

var options = new PdfTextDrawingOptions(new PdfRectangle(0, 0, 100, 50))
{
    HorizontalAlignment = PdfTextAlign.Center,
    VerticalAlignment = PdfVerticalAlign.Center,
};
xobj.Canvas.FontSize = 16;
xobj.Canvas.DrawText("Company Logo", options);
xobj.Canvas.DrawRectangle(options.Bounds);

var page1 = pdf.Pages[0];
page1.Canvas.DrawXObject(xobj, 100, 100);

var page2 = pdf.AddPage();
page2.Canvas.DrawXObject(xobj, 200, 200);

pdf.Save("using-xobjects.pdf");

Transformación de páginas con XObjects

Los XObjects también permiten escenarios que van más allá de la simple reutilización de gráficos. Un ejemplo común es combinar dos páginas PDF existentes en una sola página más grande. Al convertir cada página de origen en un XObject, puede dibujarlas una al lado de la otra en un nuevo lienzo, creando así una combinación de dos páginas. Este método le brinda control total sobre el posicionamiento, el espaciado y la escala, lo que facilita la creación de diseños comparativos, pliegos de libro o vistas previas de varias páginas.

La misma técnica se puede aplicar cuando necesite cambiar el tamaño de páginas PDF. En lugar de redibujar o reconstruir el contenido, puede crear un XObject a partir de la página original y dibujarlo escalado al nuevo tamaño. Esto le permite reducir páginas demasiado grandes, ampliar páginas pequeñas o normalizar un documento de tamaños mixtos con un mínimo esfuerzo.

Alcance y limitaciones de la API principal

La API Core ofrece un control preciso y de bajo nivel sobre la creación de PDF, pero no proporciona funciones de diseño automático. No incluye márgenes, encabezados, pies de página ni lógica de salto de página, y todo el contenido debe posicionarse manualmente. La medición del texto y su división entre páginas son responsabilidad exclusiva del código, lo que convierte a esta en la forma más manual de crear PDF.

El diseño automático, que incluye compatibilidad con tablas, párrafos y saltos de página, está disponible a través de la API de diseño de nivel superior.

Conclusión

La API principal de Docotic.Pdf ofrece un control total sobre la creación de PDF. Permite dibujar texto, imágenes y gráficos vectoriales en lienzos proporcionados por páginas PDF, XObjects y patrones de mosaico.

La API está diseñada para escenarios que requieren un control preciso y de bajo nivel: se posiciona cada elemento explícitamente, se gestiona la medición del texto y la división de páginas, y se manipulan directamente el estado, los colores y la transparencia de los gráficos.

En resumen, la API principal es la herramienta más flexible para crear PDF cuando la precisión y el control son prioritarios.

Pruebe la biblioteca con una clave gratuita