PDF 与 SyncTeX

概览

TeX64 提供集成的 PDF 预览以及 SyncTeX 双向导航功能。PDF 预览会在工具栏构建成功后刷新，SyncTeX 用于连接源码与 PDF 的导航。

通过 SyncTeX，您可以即时看到源代码中的光标位置对应于 PDF 中的何处，反之亦然——点击 PDF 即可直接跳转到对应源码。可从多种视图模式中选择，匹配您的工作流。

平台说明：TeX64 目前面向 macOS（Apple Silicon 与 Intel）发布。Windows 与 Linux 版本仍在计划中、尚未提供，因此下文的快捷键以 macOS 按键为准。文中出现的 Windows/Linux 对应按键，将在相应版本发布后生效。

PDF 预览模式

TeX64 会在工具栏手动构建成功后刷新 PDF。选择最适合您项目规模与显示器配置的查看模式。

集成查看器（同一窗口）

工具栏手动构建成功后刷新 PDF。编辑器与 PDF 集成显示在同一窗口中。该模式适合单显示器环境或紧凑布局。PDF 预览可置于编辑器下方或旁侧，便于频繁切换。

分屏视图（垂直/水平）

将编辑器与 PDF 并排显示（垂直分屏）或上下显示（水平分屏）。在 macOS 上使用 Cmd+\ 切换（Windows/Linux 版本发布后为 Ctrl+\）。

在宽屏显示器上，将编辑器置于左侧、PDF 预览置于右侧，可同时查看源与输出，工作更高效。当使用较大字号或缩放级别时，水平分屏模式更具可读性。

分离模式（独立窗口）

将 PDF 查看器分离为独立窗口，在另一空间打开。此模式在多显示器布局下尤为强大。可在主显示器显示 TeX64，同时在副显示器全屏显示 PDF，进行演示级审阅与更宽视角的查看。

构建失败时的行为

若构建失败，TeX64 会保留上次成功生成的 PDF。绝不会显示损坏或部分渲染的 PDF 文件。这样您可以在修复错误时以最后一次成功的版本作为参考。

PDF 查看器操作

TeX64 的 PDF 查看器支持标准导航操作。

缩放控制

  • 放大：使用 Cmd+=（Mac）或 Ctrl+=（Windows/Linux）放大。
  • 缩小：使用 Cmd+-（Mac）或 Ctrl+-（Windows/Linux）缩小。
  • 重置缩放：使用 Cmd+0（Mac）或 Ctrl+0（Windows/Linux）将缩放重置为默认。
  • 还可以使用鼠标滚轮、触控板或捏合手势进行缩放。

滚动导航

  • 滚动 PDF 浏览任意内容。可使用方向键、滚轮或触控板进行导航。
  • 按空格或 PageDown 前往下一页，按 Shift+空格 或 PageUp 返回上一页。

页面导航

  • Home/End：跳转至文档的首页或末页。
  • 点击 PDF 查看器顶部的页码指示器，可直接跳到指定页面。

PDF 刷新行为

当前版本的 TeX64 不会在输入时自动编译。请使用工具栏构建按钮手动构建；成功后 PDF 会刷新。

构建成功时

当构建成功完成后，TeX64 会自动重新加载 PDF 以显示最新内容。默认情况下，滚动位置会回到文档顶部。

滚动位置保持

TeX64 会尽可能在 PDF 更新时保持您的滚动位置。对于小幅修改，您将继续查看相同的区段。对于改变文档结构的大幅修改，滚动位置可能会被重置。

构建失败时的保持

如果构建失败，将继续显示上次成功的 PDF。您可以查看错误信息，并在再次构建前进行修复。

正向 SyncTeX（源 → PDF）

正向 SyncTeX 会在使用 Jump，或启用 SyncTeX at Build Time 且构建成功时，显示当前源码光标对应的 PDF 位置。

光标位置高亮

执行 Jump 后，TeX64 会高亮或在 PDF 中显示对应区域的视觉指示器。您可以查看文本、段落、章节和插图在最新构建输出中的位置。

显式 Jump 更新

点击 Jump 可从当前光标位置运行正向 SyncTeX。若启用 SyncTeX at Build Time，TeX64 也会在构建成功后跳转。仅移动光标不会重新构建或刷新 PDF。

视觉指示器

PDF 上会出现视觉标记——如矩形、背景色或图标——指示当前光标位置所对应的区域。这让您即使在复杂文档中也能清楚地知道源代码的哪一部分对应 PDF 中的哪个位置。

反向 SyncTeX（PDF → 源）

反向 SyncTeX 让您可以点击 PDF 直接跳到源代码中的对应行。在阅读 PDF 时，当发现需要修改的地方，可立即前往源代码进行编辑。

Cmd+点击 跳转

  • Mac：按住 Cmd 并点击 PDF 内的文字或元素。
  • Windows/Linux（计划中）：相应版本发布后，按住 Ctrl 并点击 PDF 内的文字或元素。

即时导航

点击后，TeX64 将编辑器置于前台，并自动将光标跳转到对应的源代码行。行号会被高亮，光标会定位到该行开头。对于跨多行的块（如段落或 figure 环境），将跳转到块的起始行。

多文件项目中的行为

反向 SyncTeX 在多文件项目中尤其强大。在通过 \input 或 \include 拆分的文件中，点击元素后，正确的外部文件会自动打开并跳转到对应行。无论项目结构如何，都能实现精准导航。

精确定位

跳转精度取决于 TeX64 从 SyncTeX 文件读取的信息粒度。通常可按段落级精度跳转到正确的行，但某些 LaTeX 宏包可能导致更粗的精度（如页级）。

多文件项目支持

SyncTeX 在通过 \input 与 \include 命令拆分的多文件 LaTeX 项目中完全可用。正确配置主文件与精准的路径至关重要。

理解 \input 与 \include

  • \input：在当前位置直接引入指定文件，不会分页。
  • \include：在新页面开始处引入指定文件。可用 \excludeonly 单独排除。

两种方式均被 SyncTeX 完整支持，可在文件间准确追踪对应关系，实现双向导航。

主文件的重要性

TeX64 会自动尝试检测项目的主文件（含 \begin{document} 的主文件）。在存在多个 LaTeX 文件时，您可能需要明确指定哪一个应被视为主文件。

若未正确设置主文件，SyncTeX 将无法工作。请通过菜单「设置主文件」进行设置，或在项目设置中指定。

跨文件跳转

正向与反向 SyncTeX 在多文件之间均可无缝工作。无论编辑器中哪个文件处于活动状态，光标位置都能准确反映到 PDF 的对应位置。同样地，从 PDF 跳转时，正确的相关文件会自动打开。

SyncTeX 所需条件

SyncTeX 要正常工作需要若干组件。

synctex 二进制

  • 必须安装 synctex 命令行工具。
  • 如已安装 MacTeX，则 synctex 会自动包含其中。
  • TeX Live 安装中也包含 synctex。
  • 验证安装：在终端运行「which synctex」。若显示路径，则表示已安装。

.synctex.gz 文件生成

  • latexmk 必须在编译时自动生成 .synctex.gz 文件。
  • TeX64 的构建过程默认启用 .synctex.gz 生成。
  • 构建成功后，请确认项目目录中存在 .synctex.gz 文件。

latexmk 配置

  • 在 .latexmkrc 或 latexmkrc 文件中配置 SyncTeX 生成选项。
  • 推荐：$pdf_mode = 1;（pdflatex）或 $pdf_mode = 4;（lualatex/xelatex）

TeX64 环境验证

在 TeX64 的「设置 > 环境」菜单中可验证可用的 TeX 环境。绿色对勾（✓）表示 synctex 已正确安装。

PDF 文字搜索

您可在 PDF 查看器内搜索文字。使用 Cmd+F（Mac）或 Ctrl+F（Windows/Linux）打开搜索框。

搜索功能

  • 输入搜索词后自动高亮 PDF 中的所有匹配项。
  • 在结果间导航：使用上下箭头按钮或 Enter 键移动到下一个/上一个匹配项。
  • 匹配计数：搜索框会显示找到的匹配项总数。

PDF 注释与编辑

TeX64 的 PDF 查看器为只读预览，不支持在 PDF 中直接添加注释、标记或手写编辑。

若需要为 PDF 添加注释，请使用其他 PDF 编辑应用（如 Preview.app、Adobe Acrobat、PDFExpert 等）。TeX64 的 PDF 查看器专注于面向审阅、参考与导航的快速预览。

手动预览工作流

当前版本的 TeX64 不提供实时 Auto-build。请从工具栏手动编译；构建成功后 PDF 预览会刷新。

手动预览工作流

  1. 在 TeX64 中打开 LaTeX 文件，在编辑器中编辑代码。
  2. 保存文件（Cmd+S / Ctrl+S）。
  3. 点击工具栏中的构建按钮运行 latexmk。
  4. 构建成功后，PDF 预览会重新加载最新输出。
  5. 使用 Jump 进行源码到 PDF 的 SyncTeX，或在 PDF 中 Cmd+Click 进行 PDF 到源码的 SyncTeX。

关于 Auto-build

当前 TeX64 构建菜单中没有 Auto-build 设置。Cmd+B 保留用于 \textbf{} 输入；手动构建请使用工具栏构建按钮。

疑难解答

SyncTeX 与 PDF 预览的常见问题及其解决方法。

SyncTeX 不工作

  • 检查 1：synctex 安装：在终端运行「which synctex」以确认 synctex 已安装。若无输出，请重新安装您的 TeX 环境。
  • 检查 2：TeX64 环境检查：在 TeX64 的 设置 > 环境 中确认是否显示绿色对勾。
  • 检查 3：主文件设置：对于多文件项目，请确认主文件是否设置正确。

找不到 .synctex.gz

  • 点击工具栏中的构建按钮重新构建项目。
  • 构建成功后，请确认项目目录中存在 .synctex.gz 文件。
  • 如未生成该文件，请检查您的 latexmk 配置。

跳转不精确

  • 某些 LaTeX 宏包（tikz、pgfplot 等）可能干扰源映射。
  • 大量使用宏命令会使源到输出的映射复杂化，降低跳转精度。
  • 在此情况下，可同时使用正向与反向 SyncTeX 交互以确定大致位置。

多文件项目的问题

  • 未设置主文件：在 TeX64 菜单中使用「设置主文件」，并选择包含 \begin{document} 的主文件。
  • 路径指定错误：确认 \input 与 \include 中指定的路径准确。若使用相对路径，请确认其相对于主文件正确无误。
  • 若外部文件无法打开，请检查路径分隔符（Mac 上为正斜杠，Windows 上为反斜杠）。

PDF 不更新

  • 请查看构建输出面板是否存在错误。若构建失败，PDF 不会更新。
  • 保存源码后，请使用工具栏构建按钮执行手动构建。
  • 若构建成功但 PDF 未更新，请尝试重启 TeX64。

通用修复方法

  • 重新构建项目：从菜单执行「清理构建」或「重建」。
  • 重启 TeX64：关闭后重新打开应用程序。
  • 检查 TeX 环境：在 设置 > 环境 中确认 TeX/LaTeX 的安装状态。

性能优化

对于大型 PDF 文档或资源密集的 LaTeX 文件，可优化 TeX64 的性能。

处理大型 PDF

  • TeX64 采用逐页渲染策略，以高效处理大型 PDF。
  • 仅渲染可见区域：屏幕外的页面不会加载到内存。
  • 延迟加载：渲染随页面滚动逐步进行。

渲染优化

  • GPU 加速：在受支持的系统上使用 GPU 加速渲染。
  • 缓存：先前已渲染的页面会被缓存，加快导航速度。
  • 自适应质量：根据缩放级别与内存使用情况自动调整渲染质量。

减少编译时间

  • 增量编译：latexmk 仅重新编译必要部分。
  • 草稿模式：在 \documentclass 选项中使用 draft 模式，可简化图像处理。
  • 移除未用宏包：删除未使用的 \usepackage 命令可缩短编译时间。

如有疑问或需要支持，请访问支持页面。