如何使用Java iText为已有PDF内的图片设置点击跳转浏览器链接

核心逻辑很简单：不需要修改已经插入到PDF里的图片本身，只要在图片所在的坐标区域叠一层URI类型的链接注释，用户点击这个区域的时候，PDF阅读器就会自动调用系统默认浏览器打开绑定的地址，和网页里给图片加超链接的逻辑差不多。

以下分目前常用的iText 7、老版本iText 5两种场景给出可直接运行的实现方案： #

iText 7 实现（当前官方维护版本） #

实现流程 #

• 加载已经插入好图片的源PDF文件，绑定输出文档路径
• 定位到图片所在的页码（注意iText页码从1开始计数，不是从0开始）
• 遍历页面渲染内容，匹配到目标图片后获取它在页面上的精确坐标、宽高范围
• 基于图片的坐标范围创建等大的链接注释，绑定要跳转的目标URL
• 把注释添加到对应页面，关闭文档输出处理后的PDF即可

完整参考代码：

import com.itextpdf.kernel.geom.Rectangle;
import com.itextpdf.kernel.pdf.*;
import com.itextpdf.kernel.pdf.action.PdfAction;
import com.itextpdf.kernel.pdf.annot.PdfLinkAnnotation;
import com.itextpdf.kernel.pdf.canvas.parser.EventType;
import com.itextpdf.kernel.pdf.canvas.parser.PdfCanvasProcessor;
import com.itextpdf.kernel.pdf.canvas.parser.data.IEventData;
import com.itextpdf.kernel.pdf.canvas.parser.data.ImageRenderInfo;
import com.itextpdf.kernel.pdf.canvas.parser.listener.IEventListener;
import java.util.Set;

public class PdfImageLink {
    public static void main(String[] args) throws Exception {
        // 替换成你的实际文件路径、跳转地址、图片所在页码
        String inputPdf = "你的源文件路径.pdf";
        String outputPdf = "处理后输出的文件路径.pdf";
        String jumpUrl = "你要跳转的目标地址";
        int imagePageNum = 1;

        // 初始化PDF读写实例
        PdfDocument pdfDoc = new PdfDocument(new PdfReader(inputPdf), new PdfWriter(outputPdf));
        PdfPage targetPage = pdfDoc.getPage(imagePageNum);

        // 注册事件监听器，遍历页面内容定位目标图片
        IEventListener imageLocator = new IEventListener() {
            @Override
            public void eventOccurred(IEventData data, EventType type) {
                if (type == EventType.RENDER_IMAGE) {
                    ImageRenderInfo imageInfo = (ImageRenderInfo) data;
                    // 多图场景下在这里加匹配规则：比如判断图片的资源哈希、宽高、固定位置，避免给错图片加链接
                    // 示例中直接给当前页遍历到的第一张图片加链接，实际使用请替换匹配逻辑
                    Rectangle imagePosition = imageInfo.getImageCtm().toRectangle();
                    
                    // 创建跳转动作、链接注释
                    PdfLinkAnnotation link = new PdfLinkAnnotation(imagePosition)
                            .setAction(PdfAction.createURI(jumpUrl))
                            // 隐藏注释边框，避免图片周围出现可见的矩形线
                            .setBorder(new PdfArray(new float[]{0, 0, 0}));
                    
                    targetPage.addAnnotation(link);
                }
            }

            @Override
            public Set<EventType> getSupportedEvents() {
                return Set.of(EventType.RENDER_IMAGE);
            }
        };

        new PdfCanvasProcessor(imageLocator).processPageContent(targetPage);
        pdfDoc.close();
    }
}

iText 5 实现（老项目兼容版本） #

iText5的API逻辑和7版本差异较大，核心思路一致：确定图片位置、叠加等大的链接注释。如果已经提前手动测量好了图片在页面的坐标和尺寸，可以不用遍历识别图片，直接创建注释区域，稳定性更高。
完整参考代码：

import com.itextpdf.text.Rectangle;
import com.itextpdf.text.pdf.*;
import java.io.FileInputStream;
import java.io.FileOutputStream;

public class PdfImageLinkItext5 {
    public static void main(String[] args) throws Exception {
        String inputPdf = "你的源文件路径.pdf";
        String outputPdf = "处理后输出的文件路径.pdf";
        String jumpUrl = "你要跳转的目标地址";
        int imagePageNum = 1;

        PdfReader reader = new PdfReader(new FileInputStream(inputPdf));
        PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(outputPdf));

        // 这里替换成你实际图片的坐标和宽高：注意iText5坐标原点在页面左下角，不是左上角
        float imgLeftX = 90f;
        float imgBottomY = 480f;
        float imgWidth = 220f;
        float imgHeight = 120f;
        Rectangle linkArea = new Rectangle(imgLeftX, imgBottomY, imgLeftX + imgWidth, imgBottomY + imgHeight);

        // 创建链接注释，设置无点击高亮、无边框
        PdfAnnotation link = PdfAnnotation.createLink(
                stamper.getWriter(),
                linkArea,
                PdfAnnotation.HIGHLIGHT_NONE,
                new PdfAction(jumpUrl)
        );
        link.setBorder(new PdfBorderArray(0,0,0));
        stamper.addAnnotation(link, imagePageNum);

        stamper.close();
        reader.close();
    }
}

踩坑提示 #

• 坐标计算是最容易出问题的环节：iText的PDF坐标原点固定在页面左下角，如果你是用PDF编辑工具从左上角开始测量的位置，需要用页面总高度减去测量的Y值做转换，不然链接区域会偏移到其他位置，点击没反应
• 如果页面图片不多，手动测量坐标直接写死比自动遍历识别更稳定，不用写图片匹配逻辑，也不会出现识别错图片的问题
• 这种方式生成的超链接兼容所有主流PDF阅读器，包括Adobe Acrobat、WPS、Chrome/Edge内置的PDF阅读器，打开后点击图片都会正常唤起浏览器跳转，不需要用户做额外设置

内容的提问来源于stack exchange，提问作者shubham mahadik