iText 在 PDF 中添加圖片、設定背景圖、旋轉與絕對定位完整教學

iText 提供 Image 類別支援 PNG、JPG、GIF 等格式插入 PDF。本文示範：建立文件、載入圖片、設定背景圖鋪滿頁面、一般圖片縮放/旋轉/絕對定位、多圖層疊加。

Maven 依賴

<dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>itextpdf</artifactId>
    <version>5.5.13.3</version>
</dependency>

完整程式碼

import com.itextpdf.text.*;
import com.itextpdf.text.pdf.*;
import java.io.FileOutputStream;
import java.io.IOException;

public class ITextImageDemo {
    public static void main(String[] args) {
        // A4 約 595x842 pt，此處自訂大尺寸示範
        Rectangle pageSize = new Rectangle(4620, 3572);
        Document doc = new Document(pageSize);

        try {
            PdfWriter.getInstance(doc, new FileOutputStream("test_image.pdf"));
            doc.open();

            // 1. 背景圖（鋪滿整頁）
            Image bg = Image.getInstance("bg.png");
            bg.setAlignment(Image.UNDERLYING);  // 置於最底層
            bg.scaleAbsolute(pageSize.getWidth(), pageSize.getHeight());
            bg.setAbsolutePosition(0, 0);       // 左下角對齊
            doc.add(bg);

            // 2. 前景圖（縮放、旋轉、定位）
            Image img = Image.getInstance("1.png");
            img.scaleAbsolute(164.409f, 267.457f);  // 指定寬高
            img.setRotationDegrees(0);              // 旋轉角度（順時針）
            img.setAbsolutePosition(100, 1000);     // 左下角座標 (x, y)
            doc.add(img);

            // 3. 另一張圖片示範相對定位（置中）
            Image img2 = Image.getInstance("logo.png");
            img2.scalePercent(50f);  // 縮放 50%
            img2.setAlignment(Image.MIDDLE | Image.ALIGN_CENTER);
            doc.add(img2);

        } catch (DocumentException | IOException e) {
            e.printStackTrace();
        } finally {
            doc.close();
        }
    }
}

核心方法速查表

座標系統說明

• 原點 (0,0)：頁面左下角。
• X 軸：向右遞增。
• Y 軸：向上遞增（不同於螢幕座標）。
• 1 pt = 1/72 inch。

進階：圖片作為水印（透明度）

PdfContentByte cb = writer.getDirectContentUnder();  // 內容下層
cb.saveState();
PdfGState gs = new PdfGState();
gs.setFillOpacity(0.3f);  // 30% 不透明度
cb.setGState(gs);
Image watermark = Image.getInstance("watermark.png");
watermark.setAbsolutePosition(200, 400);
cb.addImage(watermark);
cb.restoreState();

常見坑

• 圖片不顯示：路徑錯誤、檔案損壞、未呼叫 doc.add()。
• 位置偏移：混用 setAbsolutePosition 與 setAlignment，後者會覆蓋前者。
• 背景圖被覆蓋：確保背景圖最先 doc.add()，並設 UNDERLYING。