# 程式碼智慧

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 會執行與專案 Typst 版本相符的 Tinymist 版本（請參閱 [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` 工具：大綱、標籤、引用、巨集、檔案圖，以及所有未解析的參照。當你問它「方法論那一節」時，它真的能找到。
