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

Creación de PDF con la Core API

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

La Core API de Docotic.Pdf proporciona 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.

Usted controla cada coordenada y cada operación de dibujo, y esto le da el máximo control sobre la distribución de las páginas PDF. Para documentos con mucho contenido gráfico o con diseño personalizado donde la precisión importa, este nivel de control es indispensable.

Con la Core API, también puede 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 proporciona Docotic.Pdf.

Ilustración de las capacidades de Core API para la creación de 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 PDF si desea una visión más amplia de todos los enfoques disponibles en Docotic.Pdf, incluidos los que van más allá de la Core API.

Antes de empezar

Antes de comenzar a trabajar con la Core API, prepare su entorno instalando Docotic.Pdf y solicitando una clave de licencia.

Instalar Docotic.Pdf

Para crear documentos PDF en C# o VB.NET, comience instalando 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 a BitMiracle.Docotic.Pdf.dll.

Obtener una clave de licencia

Se requiere una clave de licencia para usar la biblioteca. Para probar la biblioteca, solicite una clave de licencia gratuita con límite de tiempo rellenando el formulario en la página de descarga de Docotic.Pdf.

Ejemplos básicos de creación de PDF

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

Cómo crear PDF en C#

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

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 agrega una clave de licencia. Sin una licencia, obtendrá una excepción en la línea que instancia un PdfDocument. La última línea guarda el documento en un archivo PDF.

La estructura interna del archivo creado depende de las opciones de guardado. En este ejemplo, el código usa la sobrecarga del método Save que guarda con las opciones predeterminadas. Para entender qué hacen estos valores predeterminados y cuándo puede querer ajustarlos, vea la sección sobre opciones de guardado.

Para respetar la tradición de programación, el segundo ejemplo muestra un Hello, world! creado con la Core API.

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 explícitamente. La línea usa la fuente predeterminada y el tamaño de fuente predeterminado. Continúe leyendo para obtener información adicional sobre el trabajo con el lienzo de PDF.

Usar VB.NET para crear PDF

El código VB.NET para crear un PDF se ve 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 el lienzo de PDF

Para cambiar un lienzo en un documento PDF, use la Canvas API. Es un subconjunto de la Core API.

La Canvas API usa un modelo de posicionamiento absoluto. Usted elige las coordenadas y el lienzo dibuja exactamente donde se lo indica. El sistema de coordenadas coloca el origen en la esquina superior izquierda de la página. Las coordenadas aumentan hacia la derecha a lo largo del eje X y hacia abajo a lo largo del eje Y.

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

Dibujo de texto

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

Uso de DrawString

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

Ya vio un ejemplo simple de DrawString en el fragmento Hello, world!. Aquí hay otro ejemplo que usa 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");

Uso de DrawText

DrawText puede renderizar varias líneas de texto dentro de un rectángulo especificado. El método maneja 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 y otros aspectos de cómo se posiciona y renderiza el texto.

Así es como se dibuja 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
  • escala del texto
  • desplazamiento del texto (cambio de línea base)
  • modo de renderizado (relleno, trazo, relleno y trazo, y otros)

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

Agregar y usar fuentes

A menos que le baste con la fuente Helvetica predeterminada, debe agregar al PDF las fuentes que necesite para garantizar que su texto aparezca exactamente como pretende.

Docotic.Pdf puede agregar 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, puede usar las 14 fuentes Type1 integradas, disponibles en cualquier visor de PDF.

Para usar una fuente en su PDF, cree un objeto PdfFont usando el método CreateFont o CreateFontFromFile del objeto PdfDocument correspondiente. Luego asigne la fuente al lienzo antes de dibujar texto. También es buena idea establecer el tamaño de 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, obtendrá una CannotShowTextException. Use PdfFont.ContainsGlyphsForText para verificar que la fuente contenga todos los glifos requeridos.

La compatibilidad con Unicode depende del tipo de fuente. Las fuentes Type 1 solo admiten el conjunto de caracteres latino y su codificación, 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 admitir Unicode, pero pueden no incluir glifos para todos los caracteres Unicode.

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

Calcular las dimensiones del texto

Como la Canvas API usa posicionamiento absoluto, a menudo es necesario saber cuánto espacio ocupará un fragmento de texto antes de dibujarlo. Esto es especialmente importante cuando la salida del texto se hace en varias etapas, como al dividir cadenas largas, alinear texto con precisión o evitar solapamientos con otro contenido. La clase PdfCanvas proporciona varios métodos que ayudan a medir texto usando la fuente y el tamaño de fuente seleccionados actualmente.

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

  • determinar si el texto cabe en un área dada
  • calcular saltos de línea manualmente
  • posicionar bloques de texto en relación unos con otros

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

Dibujar imágenes

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

Así es como se agrega 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 usando el método CreateImage del objeto PdfDocument correspondiente y dibuja la imagen en el lienzo de la primera página.

Lea sobre crear PDF a partir de imágenes para obtener detalles sobre los formatos de imagen admitidos y técnicas más avanzadas de imagen a PDF.

Usar gráficos vectoriales

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

Las líneas y las curvas se renderizan usando la pluma actual, definida mediante PdfCanvas.Pen, que especifica el color del trazo, el ancho y otras propiedades de dibujo. Según el modo de dibujo, las formas pueden trazarse, rellenarse o trazarse y luego rellenarse. La brocha actual, accesible mediante PdfCanvas.Brush, se usa 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 la pluma, la brocha, la fuente y las posiciones actuales. Use SaveState para preservar el estado actual y RestoreState para volver a 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 trayectorias gráficas le permiten construir formas complejas a partir de líneas, curvas y formas más simples sin dibujarlas inmediatamente. Use métodos Append, como AppendLineTo o AppendRectangle, para agregar segmentos a la trayectoria actual. Las trayectorias no producen salida visible hasta que las rellena o traza explícitamente.

Puede usar cualquier trayectoria gráfica construida como región de recorte para restringir operaciones de dibujo posteriores. El recorte permanece activo hasta que se restaura el estado gráfico.

Hay ejemplos prácticos y ejecutables de trabajo con gráficos vectoriales disponibles en la sección Graphics del repositorio de ejemplos.

Establecer colores y transparencia

Puede cambiar los colores de trazo y relleno mediante la pluma y la brocha de un lienzo PDF. Para ello, use PdfPen.Color y PdfBrush.Color.

Ilustración de formas coloridas que gotean, algunas lisas y otras con patrones, que muestran las capacidades de Core API para colores y transparencia.

Los espacios de color dependientes del dispositivo admitidos 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 basados en CIE e independientes del dispositivo, incluidos colores L*a*b* y colores calibrados basados en ICC. La Core API también admite colores directos y espacios de color de separación para flujos de trabajo que requieren tintas personalizadas o salida específica por canal.

El código de ejemplo siguiente demuestra cómo crear colores Lab, colores basados en perfil 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 puede trazar y rellenar formas usando patrones de mosaico. Un patrón se define mediante una celda de patrón dibujada en su propio lienzo. Existen dos tipos:

  • Patrones con color. Sus celdas definen sus propios colores.
  • Patrones sin color. Sus celdas se tiñen con el color de la pluma/brocha en el momento de uso.

Para usar un patrón, cree uno mediante CreateColoredPattern o CreateUncoloredPattern del objeto PdfDocument correspondiente. Luego aplique el patrón mediante PdfPen.Pattern y/o PdfBrush.Pattern. Consulte el código de ejemplo para crear y usar patrones en el repositorio de ejemplos.

Los colores semitransparentes le permiten dibujar formas, texto e imágenes con distinta opacidad. Use 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 hay debajo. Para cambiar el modo de fusión de un lienzo, use PdfCanvas.BlendMode.

Agregar y personalizar páginas

Docotic.Pdf expone la colección PdfDocument.Pages, que puede usar para administrar todas las páginas de un documento. En la clase PdfDocument, hay dos métodos principales que permiten agregar nuevas páginas: AddPage e InsertPage.

Use AddPage() para anexar una nueva página al final del documento. Para insertar una página en cualquier posición, use InsertPage(index). Ambos métodos devuelven la instancia PdfPage recién creada.

Toda página nueva tiene el tamaño predeterminado de 595 x 842 unidades de espacio de usuario. Es el tamaño de una hoja A4. En la mayoría de los casos, la unidad de espacio de usuario en PDF es 1/72 de pulgada. O, 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 usar 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 rotar una página 90°, 180° o 270° en sentido horario.

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

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

Reutilizar contenido con XObjects

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

Los XObjects son similares a las imágenes vectoriales. Puede reutilizar el mismo objeto en varias páginas sin recrear el contenido ni aumentar el tamaño del documento. Puede escalar y rotar estos objetos sin introducir artefactos visuales. Debido a estas cualidades, los XObjects son ideales para elementos repetidos como logotipos, ilustraciones, fondos, marcas de agua y otros gráficos recurrentes.

Crear y usar XObjects

Para crear un XObject, use el método PdfDocument.CreateXObject. Cambie el ancho y el alto del objeto si es necesario. Luego rellene el lienzo con texto, imágenes y gráficos de la misma manera que un lienzo de página normal.

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

Aquí hay código C# que crea un XObject con una ilustración y dibuja la ilustración 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");

Transformar páginas con XObjects

Los XObjects también habilitan 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 origen en un XObject, puede dibujarlas una al lado de la otra en un nuevo lienzo, creando de forma efectiva un pliego de dos páginas combinado. Este enfoque le da control total sobre la posición, el espaciado y la escala, lo que facilita crear maquetaciones comparativas, pliegos de libro o vistas previas multipágina.

La misma técnica puede aplicarse cuando necesita 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 las pequeñas o normalizar un documento con tamaños mixtos con el mínimo esfuerzo.

Alcance y limitaciones de la Core API

La Core API ofrece un control preciso y de bajo nivel sobre la creación de PDF, pero no proporciona funciones automáticas de diseño. No hay márgenes, encabezados, pies de página ni lógica de salto de página integrados, y todo el contenido debe posicionarse manualmente. La medición de texto y la división entre páginas son responsabilidades que recaen por completo en su código, lo que convierte este enfoque en el más manual para crear PDF.

La distribución automática, incluido el soporte para tablas, párrafos y saltos de página, está disponible a través de la Layout API de nivel superior.

Conclusión

La Core API de Docotic.Pdf proporciona 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 control preciso y de bajo nivel: usted posiciona explícitamente cada elemento, gestiona por sí mismo la medición de texto y la división de páginas, y manipula directamente el estado gráfico, los colores y la transparencia.

En general, la Core API es la herramienta más flexible para construir PDF cuando la precisión y el control son la prioridad.

Pruebe la biblioteca con una clave gratuita