# 代码智能

面向 LaTeX 和 Typst 的 IDE 级导航：转到定义、查找引用、全项目重命名、悬停卡片、数学预览、文档大纲，以及 Typst 的签名帮助和格式化。

Oleafly 会为整个项目建立索引，包括每个 `\label`、引用键、自定义宏、定理、术语表条目，以及连接各文件的 `\input` 关系图。该索引为跨文件导航提供支持。Typst 文件使用相同的快捷键，由 Typst 的语言服务器响应；请参阅下面的 [Typst 文件](#typst-files)。

快捷键以 macOS 的按键显示。在 Windows 和 Linux 上，请把 ⌘ 理解为 Ctrl。

## 转到定义：F12 或 ⌘ 点击

把光标放在 `\ref`、`\cite` 键、自定义宏、你定义过的环境的 `\begin{env}`，或术语表条目上，然后按 F12（或按住 ⌘ 并点击它）。编辑器会跳到它的定义处；如果定义在项目的其他文件中，会打开该文件。

已经位于某个定义上时再按 F12，会切换为查找它的引用，这与 IDE 的惯例相同。

## 查找引用：⇧F12

Shift+F12 会在左侧栏的**参考文献**面板中列出该符号的每一处使用：每处出现占一行，显示文件、行号和预览，定义本身带有一个“def”标记。点击某一行即可跳转。要回答“我能删掉这个标签吗？”或“我在哪里引用过这篇论文？”，这是最快的办法。

![同时在两个文件中重命名一个公式标签，然后列出它的引用。](https://cdn.oleafly.com/images/gifs/desktop/rename-symbol.gif?v=2)

## 重命名符号：F2

F2 一步就能在整个项目中重命名标签、引用键、宏、定理、术语表条目或环境：打开的文件实时更新，其他文件在磁盘上被重写，索引随之重建。如果新名称已经存在，重命名会在造成冲突之前被阻止，并有一条提示消息报告在多少个文件中落实了多少处编辑。

把 `fig:overview` 重命名为 `fig:architecture`，并让全部六处 `\ref` 随之更新，只需两秒钟。

如果光标放在文件路径上，例如 `\input` 或 `\includegraphics` 的参数，F2 会重命名那个文件，并更新指向它的路径。在 Typst 的 `#include` 和 `image()`，以及 Markdown 的链接和图片上也一样。请参阅[路径随移动的文件而更新](/docs/files/#paths-follow-a-moved-file)。

## 悬停卡片

悬停在任何符号上，会出现一张卡片来解释它：

- 在**交叉引用**上：符号类型、源码预览和位置。成功完成 LaTeX 构建后，受支持的交叉引用还会显示编译后的编号和页码。
- 在**定义**上：它在整个项目中有多少处引用。
- 在任何**未解析**的内容上：一个清晰的“未解析”标签，它是你拼错了 `\ref` 或缺少 `.bib` 条目时最早的警告。

悬停时按住 ⌘（Ctrl），可点击的符号会像链接一样出现下划线，点击即可跳转。

## 悬停时的数学预览

悬停在行内的 `$…$`、`\(…\)`，或行间的 `\[…\]` 数学公式上，会用 KaTeX 渲染它，无需编译。行间公式使用行间样式。出错的表达式会显示它的错误。

## 大纲面板

文件树下方的**大纲**面板显示文档的结构：按层级缩进的章节，以及所有文件中的 `\input` 引入。来自其他文件的条目带有文件名标记。点击任何条目即可直接跳转。对于拆分成十几个章节文件的论文，这就是你用来导航的目录。

章节标题以纯文本显示，所以标题中的颜色命令、字体切换或 `\nameref` 不会以原始 LaTeX 的形式出现。由你自己的宏包装 `\section` 而生成的标题会被列出，而宏定义内部的标题不会。

文件树与大纲之间的面板分隔条可以拖动来调整大小。

## 工具栏和菜单中的位置

这三条导航命令也都在编辑器工具栏的**代码智能**菜单（花括号图标）和右键菜单中，所以在快捷键成为肌肉记忆之前，它们也很容易找到。

## Typst 文件

在 `.typ` 文件中，Typst 的语言服务器 Tinymist 会响应其中大多数命令。Oleafly 运行的 Tinymist 版本与项目的 Typst 版本相匹配（请参阅 [Typst 项目](/docs/typst/#the-language-server-follows-the-version)）。

- F12 或 ⌘ 点击会转到标签、变量或函数的定义，包括位于另一个文件中的定义。
- ⇧F12 会在**参考文献**面板中列出每一处使用。
- F2 会在整个项目中重命名标签、变量或函数。
- 悬停在函数上可以阅读它的文档。悬停在 `@preview` 导入上，会得到该包在 Typst Universe 上的链接。

同样这三条命令也在 Typst 工具栏的**代码智能**菜单、右键菜单和 ⌘K 面板中。Typst 和 LaTeX 文件中的标签彼此独立，所以在两者中都使用的标签不会被重复报告，重命名其中一个也不会影响另一个。

### 签名帮助和参数提示

在函数名后输入 `(`，会出现一张卡片显示它的参数，并高亮你正在输入的那个。Esc 会关闭它。要在函数调用的每个实参前显示参数名称，请在**设置 → 外观 → 编辑器**的 **Typst** 下开启**参数名称提示**。

`rgb("#1f77b4")` 这样的颜色值，旁边会有一个小色块。⌘ 点击源码中的链接或文件路径可以打开它。

### 格式化 Typst 文件

**格式化文档**会用 typstyle 整理整个文件。按 ⇧⌥F（Shift+Alt+F），在编辑器中右键点击，或在 ⌘K 面板中找到它。**格式化所选内容**只格式化选中的行。

**设置 → 外观 → 编辑器**中的 **Typst** 组控制格式化程序：

- **保存时格式化**会在你每次按 ⌘S（Ctrl+S）时格式化 Typst 文件。自动保存不会动该文件。默认关闭。
- **格式化行宽**是 typstyle 折行的长度。默认是 120 个字符。
- **格式化缩进**是每一级的空格数。默认是 2。
- **Typst lint 检查**会在每次保存时查找可能的错误。开启或关闭它会重启语言服务器。

## 一个文件夹中的多个文档

一个文件夹里可以放不止一篇论文，例如 `manuscript.tex` 旁边放着 `manuscript_v1.tex` 或一份 `latexdiff` 的输出。每个带有自己 `\documentclass` 的 LaTeX 文件都算作一个独立的文档，连同它通过 `\input`、`\include` 或 `\subfile` 引入的文件。标签、定理、术语表条目和宏都属于各自的文档，所以同一篇论文的三份副本里的同一个标签，不会显示为被定义了三次。

转到定义、查找引用、重命名、补全、[预检](/docs/preflight/)和 `oleafly check` 都只在你正在编辑的文档内部生效。指向只在另一个文档中定义的标签的 `\ref` 会显示为未定义，编译时报告的也是这样。还没有被任何文档引入的文件仍能看到所有标签，只有一个文档的项目不受影响。

## AI 看到的是同一份索引

[AI 助手](/docs/ai-chat/)有一个建立在同一份索引之上的 `project_map` 工具：大纲、标签、引用、宏、文件关系图，以及任何未解析的引用。当你向它问起“方法部分”时，它真的能找到。
