Go gofpdf 怎样给PDF添加内部跳转链接

我第一次给 Go 程序生成多页 PDF 时，最先想到的是给目录文字拼一个 URL。这个方向其实不对：文档内部跳转不需要外部地址，而是要先在 gofpdf 里创建一个内部链接标识，再把这个标识绑定到目标页和纵向位置，最后交给文字或单元格承载。

官方文档把这组能力拆成了三个动作：AddLink() 返回内部链接 ID，SetLink() 定义它指向的页和位置，WriteLinkID() 把可点击文字绑定到 ID。官方地址：https://pkg.go.dev/github.com/jung-kurt/gofpdf

最稳妥的写法是“先创建 linkID，后生成目标页，再在目标页调用 SetLink”，目录文字只保存 linkID，不直接保存易漂移的页码。

先分清内部链接、外部链接和 Bookmark

这三个概念很容易混在一起。内部链接只在当前 PDF 内移动，AddLink 返回的整数就是它的句柄；外部链接则是网址或其他外部目标；Bookmark 创建的是 PDF 阅读器侧边栏中的大纲节点，不是正文里某段文字的点击区域。

如果你的需求是“点击目录中的第 3 节，跳到第 5 页顶部”，就应该使用 AddLink 和 SetLink。如果需求是“让阅读器左侧显示章节树”，才额外使用 Bookmark。两者可以指向同一个章节，但职责不要混写。

先把 gofpdf 的内部跳转拆成两个位置

内部跳转有两个位置：入口位置和目标位置。入口是目录文字或单元格，目标是 PDF 中某一页的某个纵坐标。AddLink 只负责生成一个可复用的 ID，不会自动知道目标页；真正的目标由 SetLink 定义。

下面的代码只展示 API 的组织方式，不代表已经在本机执行。关键点是先保存 linkID，写目录文字时使用 WriteLinkID，创建第二页后再把该 ID 绑定到当前页顶部：

package main

import (
    "log"

    "github.com/jung-kurt/gofpdf"
)

func main() {
    pdf := gofpdf.New("P", "mm", "A4", "")
    pdf.AddPage()
    pdf.SetFont("Arial", "", 14)

    // 先创建内部链接标识，入口文字和目标页共同复用它。
    detailsLink := pdf.AddLink()
    pdf.SetFont("", "U", 0)
    pdf.WriteLinkID(8, "跳到详细说明", detailsLink)
    pdf.SetFont("", "", 0)

    pdf.Ln(14)
    pdf.Write(6, "这里是第一页的概览内容。")

    // 目标页创建后，把 linkID 定位到当前页的顶部。
    pdf.AddPage()
    pdf.SetLink(detailsLink, 0, -1)
    pdf.Write(6, "这里是详细说明页。")

    // 输出失败时立即返回，避免把不完整文件当成成功结果。
    if err := pdf.OutputFileAndClose("internal-link.pdf"); err != nil {
        log.Fatal(err)
    }
}

SetLink(detailsLink, 0, -1) 中的 -1 表示当前页；纵坐标为 0 时，落点接近该页顶部。你也可以传入具体页码和纵坐标，但跨页文档更适合在目标页生成后就地绑定，减少页码维护成本。

用 WriteLinkID 让正文文字可以跳转

WriteLinkID 的第一个参数是行高，第二个参数是显示文本，第三个参数就是 AddLink 返回的 ID。它适合“阅读更多”“返回目录”这类连续文字，也适合在段落中插入一个短跳转入口。

我实际更在意的是链接 ID 的生命周期：它应该和一个逻辑章节绑定，而不是和某一个临时页码绑定。章节往前后移动时，只要目标页生成逻辑仍然集中，目录入口不需要逐处改数字。

// 让一段正文中的短文字指向同一个章节目标。
pdf.SetFont("", "U", 0)
pdf.WriteLinkID(7, "查看参数说明", detailsLink)
pdf.SetFont("", "", 0)

目录单元格怎样复用同一个内部链接

如果目录是网格形式，可以使用 CellFormat 的 link 参数。它的参数顺序较长，内部链接所在位置是倒数第二个参数，最后一个参数用于外部链接字符串；内部跳转时给 link 传 ID，外部链接字符串留空。

// 目录单元格复用已创建的内部 linkID，不重复创建目标。
pdf.CellFormat(80, 8, "第二章：详细说明", "1", 0, "L", false, detailsLink, "")

这种写法的好处是目录区域和正文段落共享同一个目标。如果一个章节需要多个入口，重复传同一个 detailsLink 即可；不要为每个文字片段都创建新的 ID，否则后续维护时会出现多个入口指向不同位置的问题。

跨页生成时，SetLink 应该放在哪里

最容易踩坑的是在生成第一页时就把目标页写死。PDF 是顺序写出的，前面的内容一旦因为换行、表格或图片增加而多占一页，后续页码就会变化。内部链接的 ID 不依赖页码，因此推荐把目标绑定放在目标章节开始输出的位置。

如果你确实掌握了目标页码，也可以把页码作为第三个参数传给 SetLink。但页码是“结果”，不是最好的业务主键。更稳定的做法是让导航项记录章节名和 linkID，生成章节时调用一次 SetLink(linkID, y, pdf.PageNo())。

// 章节开始时记录当前页，linkID 仍然是稳定的逻辑标识。
pdf.AddPage()
sectionPage := pdf.PageNo()
pdf.SetLink(detailsLink, 0, sectionPage)
pdf.Write(6, "详细说明正文")

这里的 sectionPage 只用于表达“当前页”，并不是让目录提前猜页码。若章节标题前还有固定内容，纵坐标可以换成标题所在的实际位置，让阅读器落在更自然的阅读点。

Bookmark 什么时候值得一起使用

Bookmark 设置的是阅读器侧边栏大纲。它的 level 参数控制层级，y 参数控制当前页上的垂直位置；它适合给长文档提供整体结构，但不会替代正文中的可点击目录文字。

// Bookmark 服务于阅读器侧边栏，和正文点击链接是两条独立路径。
pdf.Bookmark("第二章：详细说明", 0, -1)

在实际项目中，可以让同一个导航项同时拥有 linkID 和书签标题：正文目录使用 linkID，侧边栏使用 Bookmark。这样读者既能点击页面中的目录，也能从阅读器的导航面板进入章节。

最后用一张表检查导航结构

我自己的判断是：少量页码的简单 PDF 可以直接把 SetLink 放在目标页创建之后；有目录、表格和可变内容的文档，则应该把导航项抽成数据结构，集中保存标题和 linkID。这样修改版式时，导航关系不会跟着每一处坐标散落。

常见问题

为什么 AddLink 创建后点击没有反应？

通常是只创建了 linkID，却没有在目标页调用 SetLink；检查入口和目标是否使用同一个整数 ID。

Bookmark 能不能替代 WriteLinkID？

不能。Bookmark 面向阅读器侧边栏，WriteLinkID 面向页面中的可点击文字；两者可以同时存在。

CellFormat 的 link 和 linkStr 怎么选？

当前 PDF 内部跳转使用 link，外部网址使用 linkStr。两者不要同时填成同一个目标。

怎样让链接落到章节标题而不是页面顶部？

在目标章节输出前后读取当前纵坐标，把它作为 SetLink 的 y 参数；如果标题就在页首，使用 0 或当前页顶部即可。

结论：把链接当作章节关系管理

gofpdf 的内部跳转可以浓缩成一条关系：AddLink 生成稳定标识，SetLink 把标识接到目标页和位置，WriteLinkID 或 CellFormat 提供入口，Bookmark 另负责侧边栏目录。把这四个角色分开，PDF 的目录、返回入口和章节跳转就不会被页码变化牵着走。