-
Notifications
You must be signed in to change notification settings - Fork 0
User Guide
本页按“第一次安装 → 日常写作 → 高级功能 → 排障”的顺序介绍 TeXLeaf 1.2.2。如果只想快速确认某个设置的默认值，请看 配置参考；如果遇到异常，请看 故障排查。各功能页面会继续提供实现边界、完整配置和验收步骤。
TeXLeaf 是 VS Code 的可视化 LaTeX 写作扩展。它始终编辑原来的 .tex、.bib 和工作区文件，不生成需要再次导出的中间文档。
主要能力包括：
- 在可视化编辑器中显示并编辑公式、章节、定理、证明、列表、表格、交换图、图片、引用和 bibliography；
- 在数学环境中使用可配置的自动/手动/Visual Snippet、分式、括号放大、Tabout 和 matrix/align 键位；
- 预览并跳转跨文件
\ref/\eqref，搜索 bibliography 与 Zotero 文献； - 在源码编辑时显示活动 Math Preview；
- 把可选 AI 语言问题安全地发布到 VS Code 原生 Problems；
- 通过 LaTeX Workshop 兼容桥完成编译、PDF 查看和 SyncTeX。
TeXLeaf 本身不包含 TeX 编译器。要生成 PDF，需要另装本机 TeX 发行版和 LaTeX Workshop。未来的 TeXLeaf-Z 计划提供不桥接 LaTeX Workshop 的集成编译工作流，但当前没有承诺发布时间。
- VS Code
1.98或更高版本； - TeXLeaf 官方 VSIX 或 Marketplace 版本；
- 至少一个已经保存到磁盘的
.tex文件。
再安装：
- TeX Live、MiKTeX 或 MacTeX 等 TeX 发行版；
- LaTeX Workshop；
- 能在 LaTeX Workshop 中独立成功工作的 recipe。
TeXLeaf 只桥接 LaTeX Workshop 的 build、view 和 synctex 公共命令。若 LaTeX Workshop 自己不能编译，TeXLeaf 不会替它修复 TeX 发行版、PATH、recipe 或宏包问题。
准备本机 Zotero。推荐安装 Better BibTeX，以获得稳定 citation key 和本地 JSON-RPC；也可以使用 Zotero 官方 Local API。Zotero 必须运行在扩展宿主能够访问的同一台机器或网络环境中。
准备自己的 DeepSeek API Key 或 OpenAI API Key。ChatGPT Plus/Pro、Codex 套餐或网页登录状态不能替代 API Key 与 API 计费额度。AI 默认关闭，不配置不会影响其他功能。
- 在 VS Code 中打开一个工作区或文件夹；
- 打开已经保存的
.tex文件； - TeXLeaf 默认把
*.tex交给可视化编辑器； - 若仍显示普通文本编辑器，右键标签页，选择 Reopen Editor With... → TeXLeaf Visual Editor；
- 若希望以后默认进入完整源码，把
texleaf.visualEditor.defaultMode设为source。
打开后仍是同一个 VS Code TextDocument：
- 保存状态与普通编辑器一致；
- Undo/Redo 作用于原文件；
- 外部修改会同步；
- 可视化、同标签页源码和“原生”模式不会生成第二份
.tex。
默认模式。未被光标选中的完整公式和结构会显示为可视化组件。适合日常写作、阅读和结构化编辑。
在同一个标签页内显示整篇高亮源码。它仍由 TeXLeaf 的 CodeMirror 编辑器承载，保留 TeXLeaf 的片段、引用、逻辑行和活动公式预览。
打开 VS Code 原生 Monaco 文本编辑器。需要完整的第三方 Hover、Code Action、复杂 Completion Provider 副作用、Inline Suggest 或其他扩展专属键位时使用它。
常见选择：
- 普通写作：可视化；
- 连续检查大量源码：同标签页“源码”；
- 调试其他扩展、复杂补全或原生命令：工具栏“原生”。
工具栏可在标准模式（basic，默认）和增强模式（maximum）之间切换。标准模式用本地 MathJax 显示常规公式，不启动 TeX；需要本地排版的特殊内容提供黄色模式切换提示。增强模式使用本机 TeX 排版复杂公式、公式内 TikZ、TeX 盒子、Young 图和包含 PDF/位图子图的完整组合 figure，先显示可编辑正文，再逐项补齐图形，并提供进度、取消、失败说明及重试。
增强模式需要可信工作区、本机 TeX 和相应宏包。通常使用 latex 与 dvisvgm；中文图形需要 xelatex、ctex 和字体。含外部图片的预览优先用支持 PDF 的 dvisvgm 转换，失败后尝试 pdftocairo。依赖缺失时保留源码和提示，不自动下载工具。可通过 texleaf.visualEditor.texBinPath 指定本机工具目录；完整论文编译仍由 LaTeX Workshop 负责。
图形任务共享并缓存完成结果，切换模式、滚动或普通正文编辑可以复用；图形源码、有效宏、绘图颜色或相关图片内容变化时失效。texleaf.visualEditor.graphCacheLimitMB 控制磁盘缓存，默认 128 MiB、范围 16–2048，超限优先清理较久未使用项；可视化菜单可清理缓存，源码与 PDF 不受影响。
增强图形预览默认 150%。设置 texleaf.visualEditor.previewZoomPercent 可在 50–400% 间调整默认值，修改后立即应用；“缩小 / 重置 / 放大”只改变显示，重置返回设置值，新建预览也使用该值，不重新运行 TeX、不改变源码或 PDF。图形卡片、图注、操作按钮和图形引用悬浮使用不透明浅色纸面；保留原图颜色、透明度、位图像素及空实心节点，主题切换无需重新编译。
1.2.1 保留 1.2.0 的完整改进：标题、作者、单位居中呈现，摘要独立带框并有源码入口；增强模式可整合可确定的分散文首信息。标题编辑按钮独占上方一行，窄窗不遮挡标题；标题、摘要、空样式命令、计数和布局命令均保留准确的源码入口。连续退格遇到折叠命令、表格或图形时先展开，再逐字删除；显式选中的完整命令仍可删除。
支持安全局部宏、脚注及其悬浮、定理样式、图题、目录、附录，以及章节计数器的字面整数赋值、加法和步进。标题与文献悬浮保留 LaTeX 公式，不解释标题中的 HTML；公式失败时保留红色原始公式，长标题和手写文献保留文字回退。可验证的 LaTeX Workshop 成功编译结果仅在相关源码仍一致时补充编号，过期或来源不明的结果不覆盖当前推断。
可视化属于静态近似。动态宏、精确编号、分页、浮动位置和模板最终排版以 LaTeX Workshop 编译的 PDF 为准。
Beamer 保留帧外框、标题与正文，columns / column 按正文顺序纵向展开，便于连续编辑。支持局部分组的字号、粗体、斜体、命名颜色，以及可确定的单参数来源说明宏；样式与分栏包装仍可展开源码。普通文本 \alert 显示为加粗与可确定的高亮色，独立公式中的 \alert 用加粗数学兼容显示。局部作用域与重定义会更新样式，显式换行不再与源码换行叠加成额外空行；真实幻灯片布局仍以 PDF 为准。
Beamer 双向定位复用 LaTeX Workshop 的 SyncTeX 索引与 PDF viewer。普通帧先核验原行的双向记录；无法确认精确位置时，使用本帧结束记录的首个命中，避免跳到上一帧或同帧后续 overlay。显式 fragile/direct 帧，以及可核验的全局 direct 帧，保留准确原行；反向命中普通帧的 \end{frame} 时返回帧头，精确正文命中仍保留原位置。可视化位置通过统一 LF 坐标与原 TextDocument 的 LF/CRLF 坐标转换，避免 Windows 换行导致偏移累积，不改写文件换行格式。缺少可用 Workshop 运行时组件时沿用原同步路径，不猜测更细的位置。
公式内中文 IME 候选替换、删除与取消后恢复正常输入和退格，即使缺少 composition 结束通知也能由普通按键恢复。展开表格源码及混合文字单元格均支持 Math Preview，位置对齐公式起始处；单元格空格不会误触源码展开。工具栏、右键插入及多行片段自动缩进结果同步写入同一 TextDocument，沿用原有保存和撤销历史。
- 点击已渲染的行内或块级公式；
- 该公式原位恢复真实 LaTeX 源码；
- 块级公式同时显示活动 Math Preview；
- 直接输入、选择、删除或使用 Snippet；
- 把光标移动到公式范围以外；
- 源码重新渲染为静态公式。
公式可视化不是图片覆盖层，命中范围来自真实源码与浏览器布局。若点击没有展开，先确认点击的是公式本体或它的逻辑行，而不是透明背景中的其他结构块。
支持 $...$、\(...\) 等完整行内公式。光标在内部、定界符处或选区与公式相交时显示源码；离开后恢复。所有活动 tabstop 完成且结束定界符前只剩安全空白时，Tab 可以越过行内公式结束符。
支持 \[...\]、equation、align、gather、matrix/cases 等常用环境。多行公式作为一个整体展开，但上下方向键仍按其 LaTeX 逻辑行导航。
Tab 和普通 Enter 不用于跳出块级公式。只使用 Shift+Enter 跳出最近的受支持环境。
悬停或打开指向 align 等多行公式的 \ref / \eqref 时：
- 预览显示完整外层公式；
- 当前 label 对应的那一行使用单独背景/描边高亮；
- 同一个公式的其他行保留上下文但不抢占焦点；
- 多个 label 分别按当前鼠标指向的引用决定高亮行。
TeXLeaf 会区分 IME 临时 composition 和最终提交：
- 拼音仍在组合时不提前展开自动片段；
- 选词提交后只匹配一次最终文字；
- 在公式末尾输入临时
s不应删除前面的+y^2； - 删除最后一个临时拼音字符不应把已有公式一并删除；
- 花括号、定界符和相邻源码范围受精确映射保护；
- 中文全角标点只按最终输入提交一次，不应产生双分号。
若遇到输入法问题，请记录：输入法名称、中文/英文模式、原始源码、光标位置、逐键操作和最终结果。仅提供“吞字符”截图通常不足以判断是 composition replacement、Snippet、补全接受还是普通编辑。
在符合上下文时直接输入 trigger，TeXLeaf 自动展开。例如常见数学字母、上下标、分式和定理环境。自动规则会检查文本/数学模式、词边界、注释、命令参数和对齐单元边界。
输入 trigger 后按 Tab，或从补全列表选择。精确 TeXLeaf trigger、活动 Snippet Session、局部 Tabout、matrix/align 行为和普通缩进按固定优先级处理。
按 Ctrl+Alt+L；macOS 使用 Cmd+Alt+L。选择器只显示当前位置可用的片段，可以搜索 trigger、名称和描述。
- 选择一段正文或数学源码；
- 触发带 Visual 占位符的片段；
- 选区被安全放入目标结构；
- 后续 tabstop 继续按顺序导航。
片段展开后，Tab 先移动到下一个活动占位符。嵌套片段会先完成内层占位符，再返回外层会话；不会因为继续输入自动片段而丢失外层位置。
完整格式、正则 replacement、选项和迁移见 Snippet 格式。
在数学环境中输入分式 trigger（默认常见用法为 //）时，TeXLeaf 从光标左侧寻找安全分子。
以下关系符视为边界，不会被收进分子：
-
=； -
<、>； -
\le、\leq； -
\ge、\geq； - 相应的受支持关系命令。
例如在 <1/2 一类输入中，< 应保留在分式外。扫描还会尊重括号、TeX 花括号、命令、注释、文本命令、& 和公式行边界。
在普通括号内插入分式、求和等高结构时，TeXLeaf 可以把合格的祖先括号改为 \left...\right。多层括号会从内到外处理；已有尺寸修饰的中间层不会被重复修改。
当光标确实位于尚未闭合的括号、花括号、命名定界符或 \left...\right 内时，Tab 可以越过最内层完整 closer。
Tabout 不会：
- 把右侧未来命令参数中的任意
}当成目标； - 跨越
align/ matrix 的&、\\、\cr、\crcr或\tabularnewline； - 抢走仍在活动的 Snippet tabstop；
- 用来跳出 theorem、proof、列表或块级数学环境。
优先顺序为：
- 活动 Snippet tabstop；
- 当前单元内的严格 Tabout；
- matrix/align 下一列；
- 补全接受或普通缩进。
没有局部括号目标时，matrix/align 中的 Tab 插入下一列，而不是离开环境。
在 matrix/align 中执行受支持的智能换行；在列表中可以创建下一条 \item。普通 Enter 永远不作为块环境退出键。
在由 enumerate 等列表创建的空 \item 上继续按 Enter，会按列表规则保留或清空空项，而不是误触双分号或直接离开环境。若希望退出，使用 Shift+Enter。
Shift+Enter 跳出最近一层受支持环境：
- 找到最近的安全
\end{...}或 display math 结束位置； - 优先复用结束命令后的安全空白行；
- 必要时插入一行；
- 新行采用 closing line 的外层缩进；
- 嵌套环境只跳出最内层；
- 整次操作可以一次 Undo。
可视化块会隐藏部分源码字符，但光标仍按 LaTeX 逻辑行工作。
-
↑/↓移向上一/下一逻辑行； - 到达普通正文行时展开该行；
- 到达公式内部逻辑行时展开整条公式；
- 不在视觉像素行之间随机跳转。
- 点击行号、空白区域或对应逻辑行；
- 若该行是折叠环境的
\begin{...}或\end{...}，TeXLeaf 成对显示边界； - 光标保持在用户实际点击的逻辑边界，不跳到上一个环境；
-
\end{example}下一行开头不属于该环境，不会被吸附回\begin{example}。
这套规则适用于 theorem/lemma/proof/list 等结构块和 align/equation 等公式替换层。
\title、\author、\date 与 \maketitle 显示标题结构；part/chapter/section/subsection 等显示层级标题。点击标题或“编辑”入口回到准确命令范围。
内置 theorem、lemma、proposition、corollary、definition、remark、example、proof 以及安全识别的 \newtheorem 会显示结构卡。点击 begin/end 逻辑行可看到真实环境名；点击正文直接编辑正文。
支持 itemize、enumerate 和 description。Enter 创建下一项；空项清理不跳出环境；Shift+Enter 才离开列表。嵌套列表只由最内层环境响应。
对可以安全解析的 table/tabular/tabularx/longtable：
- 点击表格卡片中的 可视化编辑表格；
- 选择外层浮动体、数据环境、位置、宽度和整体对齐；
- 设置普通横线或
booktabs三线表； - 编辑 caption、label、列对齐和竖线；
- 增删行列并编辑单元格 LaTeX；
- 在单元格中使用 TeXLeaf Snippet 或
Ctrl+Space； - 点击 应用表格修改；
- TeXLeaf 把结构模型作为一次可撤销文档编辑写回原
.tex。
复杂 \multicolumn、\multirow、动态宏、自定义列类型或无法证明安全的语义会保留源码路径。可视化预览不等于真实 TeX 的最终列宽、分页和字体度量。
点击 可视化编辑交换图 打开内置 quiver 1.7.0 中文编辑器。可选择、拖动节点与箭头，编辑标签、弯曲、颜色、端点和箭头样式，也可放大编辑画布。标准与增强模式均使用浅色交换图卡片，外围文档继续跟随 VS Code 主题。
编辑器直接加载当前 tikzcd，不设独立导入、宏定义或导出栏。点击 应用修改 将结果写回原位置，可一次撤销；未修改就应用或取消均保持原文。源码中的 texleaf-quiver-v1 注释保存 quiver 原生状态，仅在对应图形源码未被外部修改时使用；手动改图后重新解析 TikZ。
quiver 无法无损导入所有手写 TikZ 选项。未识别的选项会列出提示；修改后应用需要勾选转换确认。需要保留原样时使用 编辑 tikzcd 源码。TikZ 无法准确表达的箭头组合会提示调整，不会静默替换样式。
修改主文档图形时按需补充 \usepackage{quiver}，与图形修改共用一次撤销；编辑 \input 子文件时需自行在主文档加载宏包。完整文档编译需要本机 quiver 1.7 及 TikZ 依赖；增强预览使用随扩展提供的 quiver.sty。界面、KaTeX、字体和图标全部本地加载，宏由 TeX 文档管理，不加载远程宏。
这里实际嵌入了 q.uiver.app / varkor/quiver 1.7.0 的代码，上游提交为 2f289ecbae9b7e5a473e04b924750c538ed5c4cf，原作者版权为 Copyright (c) 2018 varkor，使用 MIT License。TeXLeaf 维护本地汉化与集成补丁，并保留 quiver 和 KaTeX 0.18.1 的原许可证；这是实际代码集成，不只是交互参考。
工作区或文档目录内、通过安全静态路径证明的本地栅格图片及 PDF/SVG 可以预览。远程 URL、越出允许根目录的路径、动态宏路径和无法证明安全的文件保持源码。
TikZ、ytableau 等复杂内容是否显示本地预览取决于安全预览能力；TeXLeaf 不用预览结果替代真正编译。
TeXLeaf 按保守证据确定 root：
-
texleaf.project.rootFile； -
% !TEX root = ...； -
subfiles的字面主文件； - 当前文件中的
\documentclass； - 唯一且可证明的反向 include。
它支持常见 \input、\include、\import、\subimport 与 \subfile 静态路径，并优先读取已打开、尚未保存的缓冲区。动态宏路径、歧义、重复 occurrence、越出工作区或无法证明的条件分支会 fail closed。
- 在
\ref{}或\eqref{}中输入； - 补全合并当前项目可证明的 label；
- 选择目标时查看结构或公式详情；
- 接受后只插入 label key，不重写目标。
- 定理、章节等显示目标结构；
- 公式显示 MathJax 预览；
- 多行公式只强调 label 对应行；
- 带跳转箭头的引用 chip 把箭头统一放在右侧。
点击引用 chip 的跳转区域会打开正确物理文件和准确范围。使用 Ctrl+[；macOS 使用 Cmd+[，返回跨文件跳转前的位置。重复 label 或项目图歧义时不猜测目标。
在 \cite{...} 等受支持命令内输入，TeXLeaf 同时搜索：
- 项目 bibliography；
- Zotero/Better BibTeX 本地快照。
可以搜索 citation key、标题、作者、年份、DOI 和 ISBN。多词按 AND 组合，可跨字段命中；结果先在全库本地排序，再把前 100 条交给 VS Code Suggest。
候选左侧保持紧凑，右侧显示标题、作者、年份、来源、DOI/ISBN 和是否已在 bibliography。接受已有条目只插入 key；接受 Zotero 新条目时使用一个版本校验的 WorkspaceEdit，把 Bib(La)TeX 条目写入目标 .bib 并插入 key。
- 点击 citation chip 查看源码；
- 悬停查看文献详情；
- 把光标移出 cite 源码范围；
- citation 恢复可视化；
- 详情卡同时关闭，不残留在页面上。
完整去重、重复 key、DOI/ISBN 身份、Better BibTeX、远程环境和缓存规则见 文献与 Zotero。
- 打开设置中的
texleaf.aiWriting.enabled； - 选择 DeepSeek 或 OpenAI；
- 配置模型与 Base URL；
- 运行设置 API Key 命令，把 Key 存入 SecretStorage；
- 首次向某个规范化目标发送正文前阅读并确认传输提示。
可以使用停止输入后的自动句子检查，也可以手动检查当前段落、选区或整个文档。TeXLeaf 先在本地提取可编辑正文，并遮罩数学、citation、label、URL、代码、注释和不确定结构。
经过校验的问题以 source TeXLeaf AI 发布到 VS Code 原生 Problems：
- 点击条目打开正确物理文档；
- 原生或可视化编辑器定位准确行列；
- 建议卡显示消息、解释和
原文 → 替换； - 选择应用或忽略；
- 应用前重新验证文档版本、问题 ID、范围和 exact 原文；
- 成功应用后 Problems、装饰、Hover、建议卡和本机缓存同步消费。
LaTeX 编译错误也显示在 Problems，但完全由 LaTeX Workshop 发布。TeXLeaf 不复制、不解释或加入 AI 队列。
API Key 不写设置或仓库；AI 问题缓存不保存论文全文；公式源码不会发送。实际正文仍会发送到用户选择并确认的服务商，因此处理保密材料前必须确认机构政策。
详见 AI 写作助手。
活动公式源码可以使用：
-
cursor：编辑器内浮动预览； -
hover：VS Code Hover； -
both：两者同时启用。
位置可选：
-
autoAbove：优先公式上方； -
autoBelow：优先公式下方； -
above/below：固定方向。
连续输入时保留上一张有效卡片，Worker 新结果准备好后原位替换；短暂无效 TeX 有宽限时间。离开公式、关闭预览、按 Esc 或长期无效时清理旧卡。
详见 Math Preview。
- 确认 LaTeX Workshop 已安装且当前项目能独立编译；
- 从 TeXLeaf 工具栏选择编译；
- TeXLeaf 使用已加载的 LaTeX Workshop 运行时模块、配方和执行器；
- 运行时结构不兼容时回退到公开命令，并按需建立原生 TextEditor/selection 上下文；
- 返回可视化面板；
- PDF 按钮调用 LaTeX Workshop viewer；
- SyncTeX 按钮把当前可视化光标连接到 Workshop 索引与 viewer；PDF 反向定位通过兼容桥返回可视化范围。普通 Beamer 帧、精确/direct 帧和 LF/CRLF 坐标规则见上文“Beamer 与输入交互”。
若不希望保存时发生短暂原生上下文切换，关闭 texleaf.visualEditor.latexWorkshopCompatibility，然后进入“原生”模式手动运行 LaTeX Workshop。
TeXLeaf 只在当前视口附近渲染重型组件。快速滚动时旧请求会被新视口替换；停止后最终可见范围优先，不能让已经离开的公式一直占用前排队列。
如果停止后仍看到原始 \begin{equation} 或 \[...\]：
- 等待一个短渲染周期；
- 确认公式完整且工作区受信任；
- 轻微滚动观察是否补齐；
- 运行 Developer: Reload Window；
- 仍可复现时记录停靠位置、可见源码、文档规模和开发者控制台错误。
| 操作 | Windows / Linux | macOS |
|---|---|---|
| 完整片段选择器 | Ctrl+Alt+L |
Cmd+Alt+L |
| 补全 | Ctrl+Space |
Ctrl+Space |
| 跳出块环境 | Shift+Enter |
Shift+Enter |
| 返回引用跳转位置 | Ctrl+[ |
Cmd+[ |
| 关闭当前补全/菜单/预览 | Esc |
Esc |
Tab 的行为取决于 Snippet tabstop、Tabout、matrix/align 和补全状态；它不作为普通块环境退出键。
- 所有结构化编辑最终提交到同一个 VS Code 文档；
- 表格和交换图的“应用”各自是一个可撤销编辑；
- 引用导入使用一个 WorkspaceEdit 同时更新
.bib和.tex； - 文档 revision 或原文不一致时停止应用，不猜测覆盖；
- 外部文件变化与原生编辑器修改会同步到可视化面板；
- 保存仍使用 VS Code 正常保存流程。
一个可执行的问题报告应包含：
- TeXLeaf 版本与 VS Code 版本；
- 操作系统和远程环境；
- 最小
.tex/.bib片段； - 精确逐键或逐点击步骤；
- 预期结果与实际结果；
- 中文输入法名称和模式（如相关）；
- TeXLeaf Output、Extension Host 或 Webview 控制台中的相关错误；
- 是否安装 LaTeX Workshop、Zotero、Better BibTeX 或其他补全/预览扩展；
- 是否能在干净隔离窗口复现。
不要在 Issue 中粘贴 API Key、论文机密正文、支付信息或本机隐私路径。维护者通常优先处理可复现 Bug，但不能承诺新增功能、PR 合并、处理时限或私人支持。
- 所有设置与命令：配置参考
- 可视化交互和结构编辑：可视化编辑器
- Snippet 管理与模板：片段与模板
- Snippet JSONC 格式：Snippet 格式
- Citation 与 Zotero：文献与 Zotero
- AI：AI 写作助手
- Math Preview：Math Preview
- 常见异常：故障排查
- 许可证与署名：许可证、署名与再分发
开始
片段
AI 写作
文献
预览
贡献与发布