如何在Prawn PDF中使用带:Desc选项的link_annotation实现页面跳转？

我刚好熟悉Prawn的链接注释功能，来给你一步步讲清楚怎么用:Desc选项实现带描述的目录跳转。

首先，:Desc选项的核心作用是为链接添加无障碍描述文本——屏幕阅读器会读取这个内容，部分PDF阅读器也会在鼠标悬停时显示它，让链接的用途更清晰，同时符合无障碍标准。结合:Dest选项，就能实现目录到指定页面的跳转。

下面是完整的可运行代码示例，我会逐段解释：

require 'prawn'

Prawn::Document.generate('linked_toc.pdf') do
  # 第一步：先创建所有内容页面（这样能确定每个目录项对应的页码）
  3.times do |i|
    start_new_page
    text "第#{i+1}章 内容页面", size: 24, align: :center
    text "这是第#{i+1}页的内容...", size: 16, align: :center, valign: :center
  end

  # 第二步：回到文档开头，添加目录页面
  go_to_page(1)
  start_new_page # 目录会成为第1页
  text "目录", size: 28, align: :center, style: :bold
  move_down 20

  # 定义目录项：文本、目标页码、链接描述
  toc_items = [
    { text: "第1章 入门指南", page: 2, desc: "跳转到第1章内容页面" },
    { text: "第2章 进阶技巧", page: 3, desc: "跳转到第2章内容页面" },
    { text: "第3章 高级应用", page: 4, desc: "跳转到第3章内容页面" }
  ]

  # 第三步：遍历目录项，添加带描述的链接
  toc_items.each do |item|
    # 先绘制目录文本，获取它的边界位置
    text_element = text item[:text], size: 18, color: '0000FF'
    text_bounds = text_element.bounds

    # 添加链接注释，精准覆盖文本区域
    link_annotation(
      # 第一个参数是链接的矩形区域：[左, 下, 右, 上]
      [text_bounds.left, text_bounds.bottom, text_bounds.right, text_bounds.top],
      # 指定跳转目标：fit(page) 让目标页面适配阅读器视图
      dest: fit(item[:page]),
      # 设置链接的描述文本
      desc: item[:desc]
    )
    move_down 15
  end
end

关键细节解释： #

1. 先建内容页再做目录：这样能准确知道每个章节对应的页码，避免页码混乱。
2. 链接区域精准匹配文本：通过text_element.bounds获取文本的位置和尺寸，让链接注释刚好覆盖文字，用户点击文字就能跳转。
3. :Dest的跳转方式：示例中用fit(item[:page])让目标页面全屏适配，你还可以用xy(item[:page], x, y)跳转到页面的指定坐标，或者fit_h(item[:page])/fit_v(item[:page])分别适配水平/垂直视图。
4. :Desc的实际作用：这个描述主要服务于无障碍场景，比如屏幕阅读器用户会听到“跳转到第1章内容页面”，部分阅读器（如Adobe Acrobat）也会在鼠标悬停时显示这个提示。

运行代码前，确保你已经安装了Prawn：

gem install prawn

生成的PDF里，目录的蓝色文字点击后会跳转到对应章节，同时带有清晰的描述信息。

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