Cómo añadir fondo y superponer primer plano en PDF en Java
IronPDF for Java proporciona los métodos addBackgroundPdf y addForegroundPdf que colocan contenido PDF adicional ya sea detrás o sobre las páginas existentes. Estos métodos cubren toda la gama de escenarios prácticos de superposición: membretes, rellenos de color, marcas de agua, sellos de aprobación e indicadores de revisión. La biblioteca representa HTML a PDF internamente, por lo que cualquier expresión CSS válida (degradados, imágenes, tipografías) puede convertirse en una capa de fondo o primer plano sin manipulación manual del flujo PDF.
Añade IronPDF a tu proyecto declarando la dependencia en pom.xml a través de Maven Central, luego activa tu clave de licencia antes de realizar cualquier llamada a la API.
Inicio rápido: Agregar fondo y primer plano a archivos PDF
```java :title=Inicio rápido //:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/quickstart.java importar IronPDF.*; importar IronPDF; importar java.nio.file.Paths;
// Carga el PDF objetivo PdfDocument pdf = PdfDocument.fromFile(Paths.get("documento.pdf"));
// Renderiza un fondo a partir de HTML y aplícalo a todas las páginas PdfDocument background = PdfDocument.renderHtmlAsPdf("
"); pdf.addBackgroundPdf(fondo);// Renderiza una superposición de fondo y aplícalo a todas las páginas PdfDocument foreground = PdfDocument.renderHtmlAsPdf(""); pdf.addForegroundPdf(primer plano);
pdf.saveAs(Paths.get("salida.pdf"));
<div class="hsg-featured-snippet">
<h3>Flujo de trabajo mínimo (5 pasos)</h3>
<ol>
<li><a class="js-modal-open" data-modal-id="download-modal" href="#download-modal">Instale la biblioteca IronPDF for Java a través de Maven</a></li>
<li>Cargue el PDF objetivo con <code>PdfDocument.fromFile()</code></li>
<li>Renderice o importe el PDF de fondo o primer plano</li>
<li>Llame a <code>addBackgroundPdf</code> para superponer contenido detrás de las páginas existentes</li>
<li>Llame a <code>addForegroundPdf</code> para sobreponer contenido encima de las páginas existentes</li>
</ol>
</div>
## ¿Cómo añado un fondo a un PDF?
Para añadir un fondo a un PDF existente, llama a `addBackgroundPdf` en una instancia de `PdfDocument` y pasa un segundo `PdfDocument` como fuente del fondo. El método compone el fondo debajo de cada página del documento objetivo. Antes de ejecutar el código, [configure IronPDF con su clave de licencia](https://ironpdf.com/java/get-started/license-keys/) para activar la biblioteca.
```java
//:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/add-background.java
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
importar java.nio.file.Paths;
// Activate the license
License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");
// Carga el PDF objetivo
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
// Render a background from an HTML color definition
PdfDocument background = PdfDocument.renderHtmlAsPdf("<body style='background-color: cyan;'></body>");
// Apply the background to all pages
pdf.addBackgroundPdf(fondo);
pdf.saveAs(Paths.get("addBackground.pdf"));La llamada renderHtmlAsPdf convierte cualquier HTML y CSS válido en una página PDF que IronPDF compone detrás de tu contenido existente. Puede usar estilos CSS personalizados en el tutorial de HTML a PDF para producir rellenos degradados, patrones repetitivos o fondos basados en imágenes. El motor de renderizado HTML procesa propiedades CSS modernas, por lo que los diseños que funcionan en un navegador se traducen directamente en la capa de fondo.
<body style='margin:0; padding:0;'> en su plantilla de fondo HTML para eliminar los márgenes predeterminados del navegador y asegurar que el color o la imagen llenen toda la página.¿Cómo se ve el PDF de salida de fondo?
¿Por qué usar HTML para crear fondos en PDF?
Agregar un fondo superpone una imagen o página de documento detrás del contenido existente, permitiendo membretes, rellenos de color, marcas de agua y elementos decorativos de diseño. Superponer un primer plano coloca contenido encima, haciéndolo útil para anotaciones, sellos e indicadores de aprobación.
El enfoque basado en HTML ofrece varias ventajas concretas sobre la importación de imágenes:
- Control CSS preciso: Use cualquier color CSS, degradado, imagen o diseño para definir el diseño del fondo.
- Adaptabilidad al tamaño de la página: Los fondos renderizados desde HTML se escalan automáticamente para coincidir con las dimensiones de la página del PDF objetivo.
- Generación dinámica: Construye fondos programáticamente a partir de datos, preferencias de usuario o lógica de plantillas.
- Salida ligera: Los fondos definidos por CSS son más pequeños que las imágenes rasterizadas con calidad visual equivalente.
Esta funcionalidad se adapta a crear formularios con membretes de la empresa o agregar marcas de agua personalizadas a documentos legales y financieros.
¿Cómo agrego un fondo a páginas específicas?
El método addBackgroundPdf acepta un argumento opcional PageSelection que limita la operación a las páginas que especifiques. Usa PageSelection.firstPage(), PageSelection.lastPage(), PageSelection.singlePage(int index), o PageSelection.pageRange(int start, int end) para apuntar a cualquier subconjunto de páginas. La documentación completa de PageSelection está disponible en la Referencia de la API de IronPDF for Java.
//:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/add-background-specific-page.java
importar IronPDF.*;
importar IronPDF;
importar java.nio.file.Paths;
// Carga el PDF objetivo
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
// Load a background from an existing PDF file
PdfDocument background = PdfDocument.fromFile(Paths.get("background.pdf"));
// Apply only the first page of the background PDF to the first page of the target
pdf.addBackgroundPdf(background, 0, PageSelection.firstPage());
pdf.saveAs(Paths.get("addBackgroundToSpecificPage.pdf"));//:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/add-background-specific-page.java
importar IronPDF.*;
importar IronPDF;
importar java.nio.file.Paths;
// Carga el PDF objetivo
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
// Load a background from an existing PDF file
PdfDocument background = PdfDocument.fromFile(Paths.get("background.pdf"));
// Apply only the first page of the background PDF to the first page of the target
pdf.addBackgroundPdf(background, 0, PageSelection.firstPage());
pdf.saveAs(Paths.get("addBackgroundToSpecificPage.pdf"));El segundo argumento (0) es el backgroundPdfPageIndex, un índice basado en cero que selecciona qué página del PDF de fondo usar como fuente. Cuando tu plantilla de fondo contiene diseños de múltiples páginas, este parámetro te permite aplicar diferentes diseños a diferentes secciones del documento objetivo. Combina fondos selectivos con ejemplos de división y fusión de PDF para construir flujos de trabajo de ensamblaje de documentos en varias etapas.
¿Cuándo deberías aplicar fondos a páginas específicas?
La aplicación selectiva de fondos cubre una gama de escenarios comunes de documentos:
- Páginas de cubierta: Marca la primera página con un diseño a sangre completa mientras mantienes limpias las páginas del cuerpo.
- Divisores de capítulo: Aplica fondos de sección a la primera página de cada capítulo.
- Autenticación legal: Agrega un membrete oficial solo a las páginas que requieren certificación formal.
- Secciones confidenciales: Tinte o marca páginas específicas para indicar contenido restringido.
- Diseños listos para imprimir: Aplica fondos seguros para sangrías a las páginas destinadas a la impresión física.
Después de aplicar imágenes de fondo de alta resolución, considera comprimir el PDF de salida para mantener los tamaños de archivo manejables para distribución o archivo.
¿Cómo agrego una superposición de primer plano a un PDF?
El método addForegroundPdf compone una capa PDF sobre el contenido de la página existente. El primer plano renderizado aparece por encima de todo texto, imágenes y gráficos existentes en cada página objetivo. Este método es el enfoque estándar para marcas de agua, sellos de aprobación e indicadores de revisión que deben permanecer visibles independientemente del contenido subyacente. Para ver ejemplos de código funcional, consulta los ejemplos de Java de fondos y primeros planos.
//:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/add-foreground.java
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
importar java.nio.file.Paths;
// Activate the license
License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");
// Carga el PDF objetivo
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
// Render a diagonal text stamp as the foreground layer
PdfDocument foreground = PdfDocument.renderHtmlAsPdf(
"<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Foreground Example</h1>"
);
// Apply the foreground to all pages
pdf.addForegroundPdf(primer plano);
pdf.saveAs(Paths.get("overlayForeground.pdf"));//:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/add-foreground.java
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
importar java.nio.file.Paths;
// Activate the license
License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");
// Carga el PDF objetivo
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
// Render a diagonal text stamp as the foreground layer
PdfDocument foreground = PdfDocument.renderHtmlAsPdf(
"<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Foreground Example</h1>"
);
// Apply the foreground to all pages
pdf.addForegroundPdf(primer plano);
pdf.saveAs(Paths.get("overlayForeground.pdf"));La propiedad CSS opacity controla la transparencia para que el sello de primer plano no oscurezca completamente el contenido subyacente. La propiedad transform: rotate() aplica orientación diagonal, que es estándar para marcas de agua de borrador y confidenciales. La biblioteca maneja toda la composición internamente; no se requiere manipulación manual del flujo PDF.
renderHtmlAsPdf. Cualquier CSS que funcione en un navegador moderno (incluyendo @font-face, flexbox y variables CSS) producirá una salida idéntica en la capa de primer plano.¿Qué aspecto tiene la salida en primer plano?
¿Por qué utilizar superposiciones de primer plano en lugar de fondos?
Las superposiciones de primer plano cumplen un rol diferente a los fondos y son la elección correcta cuando el contenido añadido debe aparecer sobre el material existente de la página:
- Sellos de borrador y confidenciales: Coloca texto prominente pero transparente en todas las páginas sin eliminar el contenido existente.
- Anotaciones de aprobación y revisión: Superpone indicadores de aprobación o notas del revisor en documentos finalizados.
- Identificadores de seguridad: Agrega códigos de seguimiento o identificadores únicos de documentos que se sitúan por encima de todo el contenido de la página.
- Indicadores de vencimiento: Marca documentos sensibles al tiempo con avisos visibles que aparecen sobre tablas de datos o gráficos.
- Marcas de certificación: Aplica logotipos o sellos sobre contenido finalizado de manera que no puedan ser cubiertos por elementos existentes de la página.
Las superposiciones de primer plano funcionan bien con relleno de formularios PDF en Java cuando necesitas colocar indicadores de estado o sellos de aprobación sobre datos de formularios completados.
¿Cómo agrego un primer plano a páginas específicas?
El método addForegroundPdf acepta un argumento PageSelection de la misma manera que addBackgroundPdf. Usa PageSelection.pageRange(int start, int end) para limitar el primer plano a un rango contiguo, o pasa un List<Integer> para apuntar a páginas no secuenciales.
//:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/add-foreground-page-range.java
importar IronPDF.*;
importar IronPDF;
importar java.nio.file.Paths;
// Carga el PDF objetivo
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
// Render the foreground overlay
PdfDocument foreground = PdfDocument.renderHtmlAsPdf(
"<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Foreground Example</h1>"
);
// Apply the foreground to pages 2 through 8 (zero-based index: 1 to 7)
pdf.addForegroundPdf(foreground, PageSelection.pageRange(2, 8));
pdf.saveAs(Paths.get("overlayForeground.pdf"));//:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/add-foreground-page-range.java
importar IronPDF.*;
importar IronPDF;
importar java.nio.file.Paths;
// Carga el PDF objetivo
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
// Render the foreground overlay
PdfDocument foreground = PdfDocument.renderHtmlAsPdf(
"<h1 style='transform: rotate(-45deg); opacity: 0.5;'>Foreground Example</h1>"
);
// Apply the foreground to pages 2 through 8 (zero-based index: 1 to 7)
pdf.addForegroundPdf(foreground, PageSelection.pageRange(2, 8));
pdf.saveAs(Paths.get("overlayForeground.pdf"));pageRange es basado en uno en algunas sobrecargas y basado en cero en otras, dependiendo de cuál sobrecarga llames. Consulta la Referencia de API de IronPDF for Java para confirmar la convención de indexación en tu versión.¿Cuándo deberías usar rangos de páginas para primeros planos?
La aplicación de primer plano por página específica es útil en varios escenarios de producción:
- Secciones de documentos: Sella con un superpuesto de "BORRADOR" solo en el apéndice o páginas suplementarias.
- Seguimiento de versiones: Marca las páginas actualizadas con un sello de revisión mientras dejas las páginas sin cambios sin modificar.
- Confidencialidad selectiva: Aplica un superpuesto de "RESTRINGIDO" solo a las páginas que contienen datos financieros o médicos sensibles.
- Documentos multilingües: Coloca avisos específicos del idioma en las páginas relevantes de un documento bilingüe.
- Gestión de contratos: Agrega un superpuesto de "NULO" a páginas de contratos caducados sin modificar el documento completo.
¿Cuáles son los patrones comunes de selección de páginas?
Los siguientes patrones cubren la mayoría de los escenarios de superposición selectiva:
//:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/page-selection-patterns.java
importar IronPDF.*;
importar IronPDF;
import java.util.ArrayList;
import java.util.List;
importar java.nio.file.Paths;
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
PdfDocument foreground = PdfDocument.renderHtmlAsPdf("<h1 style='opacity: 0.4;'>DRAFT</h1>");
PdfDocument background1 = PdfDocument.fromFile(Paths.get("cover-background.pdf"));
PdfDocument background2 = PdfDocument.fromFile(Paths.get("end-background.pdf"));
// Apply foreground to all even-numbered pages (zero-based)
List<Integer> evenPages = new ArrayList<>();
for (int i = 1; i < pdf.getPageCount(); i += 2) {
evenPages.add(i);
}
pdf.addForegroundPdf(foreground, PageSelection.pageRange(evenPages));
// Apply different backgrounds to the first and last pages
pdf.addBackgroundPdf(background1, 0, PageSelection.firstPage());
pdf.addBackgroundPdf(background2, 0, PageSelection.lastPage());
// Apply foreground to all pages except the first and last
if (pdf.getPageCount() > 2) {
pdf.addForegroundPdf(foreground, PageSelection.pageRange(1, pdf.getPageCount() - 2));
}
pdf.saveAs(Paths.get("selective-overlay.pdf"));//:path=/static-assets/ironpdf-java/content-code-examples/how-to/background-foreground/page-selection-patterns.java
importar IronPDF.*;
importar IronPDF;
import java.util.ArrayList;
import java.util.List;
importar java.nio.file.Paths;
PdfDocument pdf = PdfDocument.fromFile(Paths.get("sample.pdf"));
PdfDocument foreground = PdfDocument.renderHtmlAsPdf("<h1 style='opacity: 0.4;'>DRAFT</h1>");
PdfDocument background1 = PdfDocument.fromFile(Paths.get("cover-background.pdf"));
PdfDocument background2 = PdfDocument.fromFile(Paths.get("end-background.pdf"));
// Apply foreground to all even-numbered pages (zero-based)
List<Integer> evenPages = new ArrayList<>();
for (int i = 1; i < pdf.getPageCount(); i += 2) {
evenPages.add(i);
}
pdf.addForegroundPdf(foreground, PageSelection.pageRange(evenPages));
// Apply different backgrounds to the first and last pages
pdf.addBackgroundPdf(background1, 0, PageSelection.firstPage());
pdf.addBackgroundPdf(background2, 0, PageSelection.lastPage());
// Apply foreground to all pages except the first and last
if (pdf.getPageCount() > 2) {
pdf.addForegroundPdf(foreground, PageSelection.pageRange(1, pdf.getPageCount() - 2));
}
pdf.saveAs(Paths.get("selective-overlay.pdf"));addBackgroundPdf y addForegroundPdf en la misma PdfDocument para construir plantillas en capas. Por ejemplo, aplica un relleno de color de marca como fondo, luego agrega un sello de confidencialidad como primer plano en una sola tubería.¿Qué métodos proporciona la clase PageSelection?
La clase PageSelection controla qué páginas reciben la capa de fondo o de primer plano. Todos los métodos de fábrica integrados devuelven un objeto PageSelection aceptado por ambos addBackgroundPdf y addForegroundPdf.
| Método | Descripción |
|---|---|
firstPage() | Apunta a la primera página del PDF |
lastPage() | Apunta a la última página del PDF |
singlePage(int index) | Apunta a una página por índice basado en cero |
pageRange(int start, int end) | Apunta a un rango de páginas contiguo (inclusivo) |
pageRange(List | Apunta a una lista no secuencial de páginas |
allPages() | Apunta a todas las páginas (predeterminado cuando no se pasa selección) |
¿Cómo eliges el método PageSelection correcto?
La elección del método depende de la estructura del documento y el alcance de la superposición:
firstPage(): Páginas de portada, páginas de título y elementos de diseño introductorio.lastPage(): Bloques de firma, avisos de fin de documento y resúmenes de cierre.singlePage(): Certificados, formularios o páginas individuales que requieren tratamiento específico.pageRange(start, end): Capítulos, apéndices o cualquier sección continua del documento.pageRange(List): Selecciones no secuenciales como todas las páginas impares o un conjunto especificado manualmente.
Para documentación completa de parámetros y firmas de sobrecarga de métodos, consulta la Referencia de API de IronPDF for Java.
¿Cuáles son los siguientes pasos para agregar fondos y primeros planos a PDFs?
Los métodos addBackgroundPdf y addForegroundPdf cubren toda la gama de escenarios de superposición de PDF, desde rellenos de color simples y marcas de agua hasta flujos de trabajo de ensamblaje de documentos con múltiples plantillas. Combínalos con PageSelection para aplicar diferentes diseños por sección o encadénalos con otros métodos PdfDocument para construir canalizaciones de documentos listas para producción. Para técnicas adicionales de superposición, como sellos de texto e imagen, explora la guía de sellado de texto e imágenes o ejemplos de anotaciones for Java.
Para usar estas características en tu proyecto, comienza una prueba gratuita de IronPDF for Java o consulta opciones de licencia para implementación comercial. IronPDF está disponible a través de Maven Central y admite Java 8 y posteriores en Windows, Linux y macOS.
¿Listo para ver qué más puede hacer IronPDF? Explora el completo tutorial de HTML a PDF for Java para un recorrido completo de opciones de renderizado, manipulación y exportación.
Preguntas Frecuentes
¿Cómo añado un fondo a un PDF existente en Java?
Cargue el PDF objetivo con PdfDocument.fromFile(), cree un PDF de fondo usando PdfDocument.renderHtmlAsPdf() con su HTML/CSS, luego llame a pdf.addBackgroundPdf(background) para componerlo detrás de todas las páginas. Active primero la biblioteca con License.setLicenseKey().
¿Cuál es la diferencia entre addBackgroundPdf y addForegroundPdf?
addBackgroundPdf coloca la capa de PDF fuente detrás del contenido de página existente, haciéndolo adecuado para membretes, rellenos de color y plantillas de diseño. addForegroundPdf coloca la capa sobre el contenido existente, haciéndola adecuada para marcas de agua, sellos de borrador, indicadores de aprobación y avisos de confidencialidad.
¿Puedo aplicar un fondo o un primer plano solo a páginas específicas?
Sí. Ambos addBackgroundPdf y addForegroundPdf aceptan un argumento opcional PageSelection. Use PageSelection.firstPage(), PageSelection.lastPage(), PageSelection.singlePage(int index) o PageSelection.pageRange(int start, int end) para apuntar a un subconjunto de páginas.
¿Cómo creo un fondo de PDF usando HTML y CSS?
Llame a PdfDocument.renderHtmlAsPdf() y pase su cadena de HTML. IronPDF soporta CSS moderno incluyendo gradientes, imágenes de fondo, fuentes personalizadas y opacidad. La página renderizada se escala para coincidir automáticamente con las dimensiones del documento objetivo.
¿Qué controla el parámetro backgroundPdfPageIndex?
El segundo argumento entero a addBackgroundPdf es el índice de página basado en cero dentro del PDF de fondo a usar como fuente. Cuando su plantilla de fondo tiene múltiples diseños de página, pase diferentes valores de índice para aplicar diferentes diseños a diferentes secciones del documento objetivo.
¿Se requiere una licencia para agregar fondos y primeros planos en Java?
Sí. Configure una clave de licencia válida usando License.setLicenseKey() antes de cualquier llamada a la API. Las licencias de prueba gratuitas están disponibles en ironpdf.com para evaluación. La biblioteca requiere una licencia adecuada para uso en producción.
¿Aún desplazándote?
¿Quieres una prueba rápida?
ejecutar una muestra Mira cómo tu HTML se convierte en PDF.
Comience gratis
Comience gratis
Reserve demostración en vivo gratis
No se requiere tarjeta de crédito ni creación de cuenta
