超链接和超目标

LaTeX 支持排版超链接，尤其在生成 PDF 格式时，超链接可以被点击访问。它是通过 hyperref 包实现的。

hyperref

hyperref 包为 LaTeX 提供了创建文档内部和外部超链接的功能。它与 pdflatex 一起工作，也可以与使用 dvips 和 ghostscript 或 dvipdfm 的标准 "latex" 配合使用来生成 PDF 文件。如果加载了这个包，你将能够包含互动的外部链接，并且所有内部引用将被转换为超链接。pdflatex 编译器使得直接从 LaTeX 源文件生成 PDF 文件成为可能，且 PDF 支持比 DVI 更多的功能，尤其是支持超链接。此外，PDF 还可以包含关于文档的其他信息，如标题、作者等，这些信息可以通过同一个包进行编辑。

使用方法

使用 hyperref 包的基本方法非常简单。只需要在前导部分加载该包：

\usepackage{hyperref}

这将自动把文档中的所有内部引用转换为超链接。它不会改变你写文档的方式：你只需继续使用标准的 \label-\ref 系统（在《标签与交叉引用》章节中讨论）；使用 hyperref 后，这些“连接”将变成链接，你可以点击它们跳转到正确的页面。此外，目录、图表/表格列表和索引也将变为超链接。如果你在草稿模式下工作，超链接将不会显示。

命令

该包提供了一些有用的命令，用于插入指向文档外部的链接。

  • \hyperref

    使用方法：

    \hyperref[label_name]{'link text'}

    这将与 \ref{label_name} 起到相同作用，但会将文本 link text 完全作为一个链接。二者也可以结合使用。例如，如果标签为 mainlemma，其编号为 4.1.1，以下代码会产生：

    We use \hyperref[mainlemma]{lemma \ref*{mainlemma} }.

    输出结果是：

    We use lemma 4.1.1.

    注意 \ref 后面的星号用于避免嵌套超链接。

  • \url

    使用方法：

    \url{<my_url>}

    它将以等宽字体显示 URL，并且点击后会打开浏览器并指向该链接。

  • \href

    使用方法：

    \href{<my_url>}{<description>}

    它会使用标准文档字体显示描述文本，并且点击后会打开浏览器并指向 my_url。例如：

    \url{https://www.wikibooks.org}
\href{https://www.wikibooks.org}{Wikibooks home}

    两者指向同一页面，但第一种方法会显示 URL，而第二种方法会隐藏 URL。

    注意，如果你打印文档，使用 \href 存储的链接不会显示在文档中。

其他功能

除了链接到网站外，hyperref 还可以用于提供邮件链接、本地文件链接以及指向 PDF 输出文件中的任意位置的链接。

  • 电子邮件地址

    插入电子邮件链接的方式：

    \href{mailto:my_address@wikibooks.org}{my_address@wikibooks.org}

    它会显示你的电子邮件地址（即使文档打印出来，读者也能看到），但如果读者点击它，将能直接发送电子邮件给你。

    如果你希望使用 url 包的格式和换行能力，可以使用：

    \href{mailto:my_address@wikibooks.org}{\nolinkurl{my_address@wikibooks.org}}

    使用这种形式时，注意 \nolinkurl 命令是脆弱的，如果超链接在可变参数中，需要在 \nolinkurl 前加上 \protect。

  • 本地文件

    使用 url 或 href 命令链接文件。只需在链接字符串前添加 run:：

    \url{run:/path/to/my/file.ext}
\href{run:/path/to/my/file.ext}{text displayed}

    参考链接：Link to Local PDF File 使用 url 的版本不总是有效，但 href 是有效的。

    你也可以使用相对路径链接到当前文档附近的文件，使用标准的 Unix 风格表示法（./ 是当前目录，../ 是上级目录，等等）。

    例如：

    \href{run:D:/my_folder/my_subfolder/my_file.txt}{Windows, absolute path}
\href{run:my_subfolder/my_file.txt}{Windows, relative path}
\href{run:./my_subfolder/my_file.txt}{Windows, relative path, variant}
\href{run:/my_folder/my_subfolder/my_file.txt}{Linux, absolute path}
\href{run:./my_subfolder/my_file.txt}{Linux, relative path}

超链接和超目标

你还可以在文档中的任何位置创建锚点（有或没有标题），并将链接到该锚点。要创建锚点，请使用：

\hypertarget{label}{target caption}

要链接到该锚点，请使用：

\hyperlink{label}{link caption}

其中目标标题和链接标题是显示在目标位置和链接位置的文本。

还要注意，如果你放置了一个超目标，当点击链接时，可能会直接跳转到超目标后的那一行，这并不理想。如果发生这种情况，你可以报告此错误并参考解决方案。

在浏览器中查看

您还可以通过在文件的 URL 后附加 #label 来获取超目标的外部 URL，或者右键单击一个指向目标的超链接并复制 URL，或通过查看 PDF 侧边栏中的标题获取链接，或者通过推导得出（例如，子小节 11.5.1 的标签是 subsubsection.11.5.1）。这种方法对于学术和教学目的非常有用。然后，启用兼容 PDF 1.5 的 PDF 查看器（如 Chrome 或 Chromium 浏览器的 PDF Viewer，Firefox 的 No PDF Download，Android 上的 Xodo 应用程序等）可以使 URL 指向目标。Foxit PDF 应用程序也能正确渲染带灰色高亮的链接（而其他应用程序可能会工作，但不进行特殊渲染，例如 Dropbox PDF 查看器应用程序；而一些应用程序无法处理链接，例如 Drive PDF 查看器、PDF Reader 和 Google PDF 查看器）。您可能需要将 URL 打开在新标签页中，否则可能会提示下载（即，如果您点击 URL，右键点击并选择在新标签页中打开它，而不是左键点击）。

自定义

大多数用户可以使用默认设置，但如果需要进行更改，也有可能。可以通过两种方法将变量传递给该包。有两种方式：在加载包时作为参数传递，或使用 \hypersetup 命令，如下所示：

\hypersetup{<option1> [, ...]}

您可以传递尽可能多的选项；用逗号分隔它们。选项必须采用以下格式：

variable_name=new_value

如果您在加载包时传递这些选项，必须以相同的格式，如下所示：

\usepackage[<option1, option2>]{hyperref}

以下是可以更改的变量列表（有关完整列表，请参见官方文档）。默认值以直立字体显示：

变量和默认值

变量 值 说明
bookmarks true,false 显示或隐藏书签栏
unicode false,true 允许在 Acrobat 的书签中使用非拉丁字符
pdfborder {RadiusH RadiusV Width [Dash-Pattern]} 设置链接周围的边框样式。前两个参数（RadiusH, RadiusV）在大多数 PDF 查看器中没有效果。Width 定义边框的厚度。Dash-Pattern 是由空格分隔并用方括号括起来的一系列数字，是一个可选参数，用于指定每条线和空隙的长度。例如，{0 0 0.5 [3 3]} 表示绘制一个没有圆角的宽度为 0.5 的正方形框，并且虚线模式的每条虚线长度为 3，空隙长度为 3。
pdftoolbar true,false 显示或隐藏 Acrobat 的工具栏
pdfmenubar true,false 显示或隐藏 Acrobat 的菜单
pdffitwindow true,false 调整文档窗口大小以适应文档大小
pdfstartview {FitH},{FitV},etc[3] 将页面宽度适应到窗口
pdftitle {text} 定义在 Acrobat 的“文档信息”窗口中显示的标题
pdfauthor {text} PDF 的作者名，作用与 pdftitle 相同
pdfsubject {text} 文档的主题，作用与 pdftitle 相同
pdfcreator {text} 文档的创建者，作用与 pdftitle 相同
pdfproducer {text} 文档的生产者，作用与 pdftitle 相同
pdfkeywords {text} 关键词列表，以逗号分隔
pdfnewwindow true,false 定义是否应在点击链接时打开新 PDF 窗口。请注意：如果链接指向 http/https 地址，此选项将被忽略。
pagebackref false,true 激活参考文献中的回溯引用。必须在 \usepackage{} 声明中指定。
colorlinks false,true false: 以框围绕链接；true: 给链接的文本上色。可以使用以下选项配置这些链接的颜色（默认颜色如下）
hidelinks 隐藏链接（去除颜色和边框）
linkcolor red 内部链接的颜色（章节、页面等）
linktoc none,section,page,all 定义目录条目的哪一部分成为链接
citecolor green 引用链接的颜色（参考文献）
filecolor cyan 文件链接的颜色
urlcolor magenta URL 链接的颜色（邮件、网页）
linkbordercolor {1 0 0} 内部链接的框颜色（如果 colorlinks=false）
citebordercolor {0 1 0} 引用的框颜色
urlbordercolor {0 1 1} URL 链接的框颜色

请注意，显式 RGB 指定仅允许用于边框颜色（如 linkbordercolor 等），而其他颜色仅能使用命名颜色（您可以自定义自己的颜色，参见“颜色”章节）。为了加速您的自定义过程，这里提供了变量的默认值列表。将其复制到您的文档中，并进行相应的更改：

\hypersetup{
    bookmarks=true,         % 显示书签栏？
    unicode=false,          % Acrobat 的书签中是否包含非拉丁字符
    pdftoolbar=true,        % 显示 Acrobat 的工具栏？
    pdfmenubar=true,        % 显示 Acrobat 的菜单？
    pdffitwindow=false,     % 文档窗口是否调整为适应页面大小
    pdfstartview={FitH},    % 将页面宽度适应到窗口
    pdftitle={My title},    % 标题
    pdfauthor={Author},     % 作者
    pdfsubject={Subject},   % 主题
    pdfcreator={Creator},   % 创建者
    pdfproducer={Producer}, % 生产者
    pdfkeywords={keyword1, key2, key3}, % 关键词
    pdfnewwindow=true,      % 链接是否在新 PDF 窗口中打开
    colorlinks=false,       % false: 链接框；true: 链接文本颜色
    linkcolor=red,          % 内部链接的颜色（可通过 `linkbordercolor` 修改框的颜色）
    citecolor=green,        % 引用的颜色
    filecolor=cyan,         % 文件链接的颜色
    urlcolor=magenta        % URL 链接的颜色
}

如果你不需要这么高的自定义，可以使用以下一些较小的但有用的例子。对于打印用的 PDF，彩色链接通常不是一个好选择，因为它们在最终输出时会变成灰色，难以阅读。你可以使用颜色框，而不打印它们：

\usepackage{hyperref}
\hypersetup{colorlinks=false}

或者将链接设为黑色：

\usepackage[hidelinks]{hyperref}

或者使用：

\usepackage{hyperref}
\hypersetup{hidelinks}

当您只想为 PDF 文件的文档信息部分提供信息，并启用参考文献中的回溯引用时：

\usepackage[pdfauthor={作者姓名},%
pdftitle={文档标题},%
pagebackref=true,%
pdftex]{hyperref}

默认情况下，URL 使用等宽字体打印。如果您不喜欢这种效果，并希望它们与文档其余文本的样式一致，可以使用：

\urlstyle{same}

故障排除

问题 1：链接和公式

当您执行类似以下操作时，可能会看到以下消息：

! pdfTeX warning (ext4): destination with the same identifier (name{
equation.1.7.7.30}) has been already used, duplicate ignored

例如，您使用了：

\begin{eqnarray}a=b\nonumber\end{eqnarray}

如果您使用这种形式，错误将消失：

\begin{eqnarray*}a=b\end{eqnarray*}

请注意，显示的行号通常与错误的实际行完全不同。

可能的解决方法：将 amsmath 包放在 hyperref 包之前。

问题 2：链接和公式

当您使用 \label 在 align 环境中时，可能会看到以下消息：

! Runaway argument?
{\@firstoffive }\fi ), Some text from your document here (\ref {re\ETC.
Latex Error: Paragraph ended before \Hy@setref@link was complete.

可能的解决方法：在文档的前言部分添加以下内容：

\AtBeginDocument{\let\textlabel\label}

注意：如果您在标签中使用了冒号 :（例如 \label{lst:program01}），也会出现相同的错误，替换它将有所帮助。

问题 3：链接和页面

当您使用类似以下的命令时，可能会看到以下消息：

! pdfTeX warning (ext4): destination with the same
identifier (name{page.1}) has been already used,
duplicate ignored

这通常发生在计数器被重新初始化时，例如，使用书籍文档类提供的命令 \mainmatter。它会将页面编号计数器重置为 1，放置在书籍的第一章之前。但由于书籍的前言页也有页面 1，因此所有指向“页面 1”的链接将不再是唯一的，因此会出现“重复被忽略”的通知。解决方法是在 hyperref 选项中添加 plainpages=false。这仅能解决页面计数器的问题。如果您希望采用更激进的解决方案，可以使用选项 hypertexnames=false，但这会导致索引中的页面链接失效。

最佳解决方法是使用 \pagenumbering 命令为每一页指定唯一的名称：

\pagenumbering{alph}    % a, b, c, ...
... titlepage, other front matter ...
\pagenumbering{roman}   % i, ii, iii, iv, ...
... table of contents, table of figures, ...
\pagenumbering{arabic}  % 1, 2, 3, 4, ...
... beginning of the main matter (chapter 1) ...

另一种方法是在 \maketitle 命令之前使用 \pagenumbering{alph}，这将使标题页具有标签 page.a。由于页面编号被抑制，它不会影响输出。

通过在计数器重置之前每次更改页面编号，每一页都会获得一个唯一的名称。在这种情况下，页面将按 a, b, c, i, ii, iii, iv, v, 1, 2, 3, 4, 5, ... 排序。

如果您不希望页面编号可见（例如，在前言部分），可以使用：

\pagestyle{empty} ... \pagestyle{plain}

重要的是，尽管数字不可见，但每个页面仍将有一个唯一的名称。

另一种更灵活的方法是将计数器设置为负值：

\setcounter{page}{-100}
... titlepage, other front matter ...
\pagenumbering{roman}   % i, ii, iii, iv, ...
... table of contents, table of figures, ...
\pagenumbering{arabic}  % 1, 2, 3, 4, ...
... beginning of the main matter (chapter 1) ...

这将给前几页赋予唯一的负数编号。

问题也可能发生在 algorithm 包中：因为每个算法使用相同的行号方案，第二个及后续算法的行标识符将与第一个重复。

问题出现在公式标识符中，如果您在 eqnarray 环境的每一行使用 \nonumber。在这种情况下，使用带星号的形式，例如：

\begin{eqnarray*} ... \end{eqnarray*}

并去掉不再需要的 \nonumber 命令。

如果您的 URL 太长并超出了页面，尝试使用 breakurl 包将 URL 分割为多行。在多列环境中，这一点尤为重要，因为行宽大大缩短。

问题：书签

书签显示的文本不总是按预期显示。因为书签“只是文本”，所以可用于书签的字符比 LaTeX 正常文本的字符少。Hyperref 通常会注意到这些问题并发出警告：

Package hyperref Warning:
Token not allowed in a PDFDocEncoded string:

您现在可以通过提供书签的文本字符串来解决这个问题，从而替换掉问题文本：

\texorpdfstring{''TEX text''}{''Bookmark Text''}

数学表达式是这种问题的常见候选：

\section{ \texorpdfstring{$E=mc^2$}{E=mc2} }

这将把 \section{$E=mc^2$} 转换为书签区域中的 E=mc2。颜色变化也不会很好地传递到书签中：

\section{ \textcolor{red}{Red !} }

生成的字符串为 "redRed!"。命令 \textcolor 被忽略了，但它的参数（red）会被打印出来。如果你使用：

\section{ \texorpdfstring{\textcolor{red}{Red !}}{Red\ !} }

结果将更易读。

如果你使用 Unicode 编写文档并且为 hyperref 包使用 Unicode 选项，你可以在书签中使用 Unicode 字符。这样，当你使用 \texorpdfstring 时，可以从更大的字符集中进行选择。

表格和图形的问题

由 hyperref 创建的链接指向在浮动环境中创建的标签，正如之前所描述的，标签必须始终在标题之后设置。由于标题通常位于图形或表格下方，因此在点击链接时，图形或表格本身将不可见。一个解决方法是使用 hypcap 包：

\usepackage[all]{hypcap}

确保在加载 hyperref 后调用此包。

如果你使用了 wrapfig 包，或者其他定义自己环境的类似包，你需要手动在这些环境中包含 \capstart，例如：

\begin{wrapfigure}{R}{0.5\textwidth}
  \capstart
  \begin{center}
    \includegraphics[width=0.48\textwidth]{filename}
  \end{center}  
  \caption{\label{labelname}a figure}
\end{wrapfigure}

长标题与 \listoffigures 的问题

当使用 \listoffigures 和 hyperref 时，长标题或长标题会出现问题。当标题或标题长度超过页面宽度（大约 7-9 个单词，具体取决于设置）时，可能会出现此问题。为了解决这个问题，你需要在第一次声明时使用 breaklinks 选项：

\usepackage[breaklinks]{hyperref}

这将使 \listoffigures 中的链接自动换行。

已存在的 .toc, .lof 等文件的问题

当你包含 hyperref 包时，latex 生成的一些辅助文件格式会发生变化。因此，在首次使用 hyperref 排版文档时，如果这些文件已经存在，你可能会遇到如下错误：

! Argument of \Hy@setref@link has an extra }.

解决方法是删除所有 latex 用来获取引用的文件，并重新排版。

脚注和特殊字符的问题

请参阅相关部分。

Beamer 的问题

使用以下命令时：

\hyperref[some_label]{some text}

如果指向标签，点击链接后会出现问题。用户不会被定向到期望的标签，而是会被送到第一个框架。一个简单的解决方法是：不要使用

\phantomsection\label{some_label}

来标记框架，而是使用

\hypertarget{some_label}{}

并通过

\hyperlink{some_label}{some text}

来引用它。

草稿模式的问题

警告！请注意，如果你在 \documentclass 声明中激活了 "draft" 选项，书签中的超链接将不会显示，包括目录或任何其他地方的链接！！！

可以通过以下方法重新启用超链接：

\usepackage{hyperref}
\hypersetup{final=true}

有关 hyperref 包的更多选项，请访问 [6]。

注释和参考

  • Hyperref 包的网页：CTAN

  • "Email link with hyperref, url packages"。comp.text.tex 用户组。

  • 其他可能的值在 hyperref 手册中定义 Hyperref README

  • Wrapfig 包的网页：CTAN


Last modified: Monday, 21 April 2025, 9:40 AM