Skip to content

Snippets and Templates

Jump to bottom
zhangxh edited this page Aug 17, 2026 · 4 revisions

片段与模板

TeXLeaf 0.8.11 的“片段”部分包括：

  • 当前 VS Code Profile 内的 212 条默认 Snippet；
  • 四个可编辑的整篇 TeX 模板；
  • 自动分数、括号放大、括号高亮和跳出；
  • matrix/align 的 Tab、Enter、Shift+Enter 操作；
  • 安全的 \left...\right... 跨行 Enter；
  • 结构化 Snippet/模板管理器；
  • 可选项目附加 JSON/JSONC 与 Settings Sync。

本页说明日常使用和存储行为。字段、选项、正则与占位符的完整语法见 Snippet 格式。

运行范围

片段编辑功能只在以下条件同时满足时运行：

  1. 文件已经保存；
  2. 后缀是 .tex 或 .bib，不区分大小写；
  3. 当前 language ID 位于 texleaf.languageIds 中；
  4. texleaf.enabled 已开启；
  5. 当前环境、文本/数学模式满足对应规则的限制。

因此，Untitled、无后缀、.md、.tex.md 或 .bib.json 不会自动展开。texleaf.languageIds 只能在 .tex/.bib 范围内进一步收窄，不能把 TeXLeaf 扩大到任意文件类型。

管理器、导入、导出和恢复命令不需要先打开 TeX 文件，可以从任意编辑器运行。

常用默认片段

数学模式

Trigger 作用 条件
lm \(@0\) 文本模式，自动
dm \[、换行、@0、换行、\] 文本模式、词边界、自动
// \frac{@0}{@1}@2 数学模式，自动
sq \sqrt{ @0 }@1 数学模式，自动
sr ^{2} 数学模式，自动
;a \alpha 数学模式，自动
;G \Gamma 数学模式，自动

dm 的多行正文和结尾 \] 会继承插入位置的缩进，无论它来自自动展开、精确 Tab 兜底还是原生 Suggest。

原生 Suggest 与 Tabout

TeXLeaf 只把与光标前输入具有非空 trigger 前缀匹配的普通片段加入原生 Suggest。例如输入 + 时可以看到 +-，继续输入成 +1 后，该候选会在刷新时移除；完全无关的片段不会以零宽候选留在列表里。需要不先输入 trigger 就浏览当前上下文可直接插入的普通片段时，使用 Ctrl+Alt+L（macOS 为 Cmd+Alt+L）。

Suggest 可见时，Tab 会先遵守精确 TeXLeaf trigger 的既有兜底。没有精确 trigger 时，只有当前位置实际能越过右括号、\rangle 或数学结束分隔符才执行 Tabout；规划不到目标就交还给 VS Code 接受当前选中的原生补全。数学区域的活动 Snippet Session 若仍有下一 tabstop，会由专用路由先关闭 Suggest、再前往该占位符；普通 Suggest-aware Tabout 路径不在活动 Snippet Session、Inline Suggest、Rename 输入框或 Matrix action 中触发，因此不会改写这些上下文原来的 Tab 优先级。

自动放大括号后的光标与 Tabout

0.8.11 对没有显式 tabstop 的普通片段保留“在括号内继续输入”的意图：如果 (sum) 的 sum 展开为 \sum 并触发整对括号自动放大，结果是 \left(\sum|\right)，而不是把光标放到 \right) 之后。可以继续输入 +、上下标或被求和项；当当前位置没有精确手动片段 trigger 时，按一次 Tab 即可执行 Tabout。片段已声明 tabstop 时不会额外合成 $0，仍按原片段占位符顺序导航。注意，刚好停在 \sum 后直接按 Tab 时，既有的精确 sum-limits 手动片段优先展开，这是原有设计，不属于 Tabout 失败。

定理类环境

为避免和普通英文单词、VS Code word suggestion 竞争，13 个出厂 trigger 都显式带反斜杠，并使用文本模式、词边界、自动展开：

Trigger Environment Trigger Environment
\axm axiom \dfn definition
\lem lemma \prp proposition
\thm theorem \cor corollary
\clm claim \asm assumption
\exm example \exr exercise
\cnj conjecture \hyp hypothesis
\rmk remark

完整输入后会立即展开。若输入事件被输入法、其他扩展或 Suggest 状态打断，直接按 Tab 会优先走与当前输入完全一致的 TeXLeaf 规则，而不是接受相近普通单词。

标签和编号参数保护

数学环境中的下列参数被视为片段抑制区：

\label{...}
\tag{...}
\tag*{...}

例如 \begin{equation}\label{;a} 中的 ;a 会保持字面文本，不会展开为 \alpha。最外层参数闭合后，外层数学环境中的自动片段立即恢复。

四个整篇模板

模板保存在当前 VS Code Profile 的 TeXLeaf 内部模板库中，不依赖用户维护的外部 .tex 文件：

默认 Trigger 类型 文档类
tmpa-cn 中文论文 ctexart
tmpa-en 英文论文 article
beamer-cn 中文演示 ctexbeamer
beamer-en 英文演示 beamer

模板展开要求：

  • 当前文件是已保存的 .tex；
  • 只有一个光标；
  • 除空白和完整 trigger 外，文档没有其他正文；
  • texleaf.autoSnippets 开启时，完整输入 trigger 自动展开；关闭时可按 Tab 手动展开。

出厂模板已经删除姓名、邮箱、学校、单位和导师等个人信息。两个 article 模板使用：

\bibliographystyle{alpha}
\bibliography{reference}

Beamer 模板没有擅自添加 bibliography；其中的 \theoremstyle{plain} 是定理排版样式，与参考文献样式无关。

结构化管理器

运行：

  • TeXLeaf: 管理 Snippet 与模板：打开管理器；
  • TeXLeaf: 管理 TeX 模板：打开同一管理器并直接切到模板页。

Snippets 页

左栏负责搜索和选择，右栏负责编辑当前条目。表单按照统一字段网格对齐；长说明放在字段下方，不再把相邻输入框顶到不同高度。

可以编辑：

  • Trigger；
  • Replacement；
  • 说明；
  • Options；
  • 正则 flags；
  • priority；
  • category；
  • syntaxVersion；
  • enabled 状态。

工具栏支持：

  • 按 trigger、replacement、说明或分类搜索；
  • 按分类和启用状态筛选；
  • 添加、复制、删除；
  • 恢复出厂 Snippet；
  • 导入、导出和显式打开高级 JSONC；
  • Ctrl+S / Cmd+S 保存。

Templates 页

每个模板都可修改：

  • 名称；
  • Trigger；
  • 说明；
  • 完整 TeX 正文。

也可以添加、复制、删除或单独恢复模板。保存后新 trigger 和正文立即用于后续展开，不要求重启窗口。

批量查找替换

管理器的“查找替换…”可用于 Snippet 或模板：

  • Snippet 可选择 trigger、replacement、说明、分类等字段；
  • 模板可选择名称、trigger、说明、正文；
  • 可区分大小写；
  • 可使用正则表达式；
  • 应用前显示变更条目、字段和替换数量；
  • 应用只修改当前草稿，确认保存前可以撤销；
  • 草稿最多保留 40 个撤销快照。

正则替换是管理器中的数据变换，不会让 Snippet replacement 获得 JavaScript 执行能力。

保存、并发和恢复

管理器不会用“最后一次保存无条件获胜”的方式覆盖其他窗口：

  • Snippet 主库以当前文件精确字节的 SHA-256 作为 revision；
  • 保存前比较载入时 revision；
  • 写入前创建原字节备份；
  • 使用临时文件和原子替换；
  • 替换后回读并验证目标哈希；
  • 另一个窗口、高级 JSONC 或同步进程已修改文件时，本次保存会拒绝并保留草稿。

模板内部目录也使用 revision 检查和结构验证。未保存草稿会阻止“恢复默认”静默覆盖。

安全上限包括：

  • 结构化 Snippet 库最多约 10 MB、100,000 条；
  • 单个 replacement 最多 1,000,000 个字符；
  • 模板最多 128 个；
  • 单模板正文最多 192 KiB；
  • 模板目录序列化后最多 256 KiB。

这些是异常输入防护，不是建议把库扩展到接近上限。

存储模型

Profile 内部库

日常使用不需要定位任何外部文件：

  • Snippet 由 TeXLeaf 在当前 Profile 的扩展私有 globalStorageUri 中保存；
  • 模板由当前 Profile 的插件内部模板目录保存；
  • Profile、Stable/Insiders、本地/Remote 扩展宿主可能各有独立副本。

TeXLeaf: 打开高级 Snippet JSONC 只用于原始审阅、高级修复或借助 VS Code JSONC 工具，不是日常入口。不要手工猜测不同平台、Profile 或 Remote 的物理路径。

项目附加文件

texleaf.snippetFiles 默认是空数组。需要团队或项目专属规则时，可以显式配置工作区相对 JSON/JSONC 文件：

{
  "texleaf.snippetFiles": [
    ".vscode/project-snippets.jsonc"
  ]
}

项目附加来源优先于全局库中的同等规则；显式更高的数字 priority 仍然优先。未信任工作区会忽略项目附加文件。

旧项目中的 .vscode/texleaf-snippets.jsonc 不会因为名字相同就被自动读取、复制或删除；请使用 TeXLeaf: 导入片段 明确迁移。

Settings Sync

TeXLeaf 会把有效、已保存且序列化 envelope 不超过 256 KiB 的内部库镜像注册给 VS Code Settings Sync。需要注意：

  • 用户必须自己开启 VS Code Settings Sync，并选择同步扩展相关数据；
  • Settings Sync 不会自动安装手工分发的 VSIX；
  • 同步不是实时共同编辑；接收侧通过窗口聚焦、存储事件和约 15 秒轮询发现变化；
  • 初次云端水合有保守宽限，避免新设备的工厂默认覆盖云端用户库；
  • 本地与远端都相对共同基线改变时会提示冲突，不会静默覆盖；
  • dirty、无效或超限内容暂停同步，但本地运行仍可继续使用上次有效内容；
  • 应用远端内容前也会创建本机备份。

Matrix、Align 与跨行 Enter

在 texleaf.matrixEnvironments 中的环境：

  • Tab：先处理活动 snippet tabstop；之后插入下一列 &；
  • Enter：块级环境插入 \\、换行并保持缩进；行内 matrix 使用不换行形式；
  • Shift+Enter：跳到当前数学环境之后。

texleaf.matrixShortcuts 还控制安全的 \left...\right... 跨行 Enter。在 equation、align、aligned、gather、multline、flalign、split 等可换行环境中，若光标位于唯一、顶层、可确定配对内：

\left(a+b\right)

按 Enter 可以改写成概念上类似：

\left(a+\right.\\
\left.b\right)

遇到跨光标嵌套 pair、花括号参数、命令 token、&、已有行终止、注释、verb 或嵌套环境时不会猜测，而是回到普通 Enter 行为。

迁移与恢复默认

工厂库当前有 212 条规则、defaultsRevision: 3：

  • revision 2 把未修改的 mode.inline 从 mk 窄迁移为 lm，并补齐定理环境；
  • revision 3 只把仍与旧出厂记录一致的 13 个定理规则改为带反斜杠的自动 trigger，例如 thm → \thm、def → \dfn；
  • 已修改、禁用或删除的用户选择不会被后续启动重新覆盖。

从旧 Publisher 身份升级

Marketplace 首发把扩展身份从 local-lab.texleaf 调整为 zhangxh-math.texleaf，因此 VS Code 会把它们视为两个扩展。为避免旧版未保存内容、命令重复注册和跨身份存储丢失，建议按以下顺序迁移：

  1. 在旧版保存所有修改，并运行 TeXLeaf: 导出片段 留一个人工备份；
  2. 如果修改过模板，在旧版管理器逐项保留名称、trigger、说明和完整正文；
  3. 安装新版；检测到旧版仍启用时，新版会暂停完整激活；
  4. 禁用但暂时不要卸载 local-lab.texleaf，然后执行 Developer: Reload Window；
  5. 新版只在 globalStorage/zhangxh-math.texleaf/texleaf-snippets.jsonc 尚不存在、旧 JSONC 严格校验通过且复制期间没有变化时，尝试从同一 Profile 的旧目录逐字节复制；
  6. 旧文件不会被移动、修改或删除。检查新管理器中的自定义 Snippet，并按需重建旧身份下的自定义模板；
  7. 全部确认无误后再卸载旧版，让新身份重新建立自己的 Settings Sync 基线。

旧模板 catalog 与旧 Snippet Sync 元数据属于旧扩展身份的私有 globalState，VS Code 公共 API 不允许新版直接读取。未修改的四个工厂模板会由新版创建；自定义模板需要在上述流程中手工保留和重建。不同 Profile、Stable/Insiders、SSH、WSL 与 Dev Container 可能有各自的扩展宿主和存储，需要分别检查。

TeXLeaf: 恢复默认片段 会先要求确认、检查未保存内容、创建备份，再恢复当前版本完整工厂库。模板页有独立恢复入口。

下一步

TeXLeaf 0.8.11

开始

片段

AI 写作

文献

预览

贡献与发布

Clone this wiki locally