# 編輯器

用原始碼與視覺化編輯來撰寫 LaTeX、Typst 和 Markdown，使用文件工具，並讓 PDF 與草稿並排顯示。

Oleafly 把原始碼編輯、文件導覽和 PDF 預覽整合在同一個工作區。它的 CodeMirror 編輯器支援 LaTeX、Typst 和 Markdown。行號、括號配對和目前行醒目提示一律開啟。除非你在 **設定 → 外觀 → 編輯器** 中關閉 **長行自動換行**，否則長行會自動換行。

以下的快捷鍵先列出 macOS 的按鍵；在 Windows 和 Linux 上，請把 ⌘ 讀作 Ctrl。

![LLaMA 在 Oleafly 中開啟。檔案樹在左側，LaTeX 原始碼在中間，編譯後的論文在右側。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png)

## 選擇你的寫作指南

每個文件引擎都有自己的工具列和原始碼語法。這些指南會說明每個控制項，並附上可以貼上並編譯的稿件：

| 引擎 | 從這裡開始 |
| --- | --- |
| LaTeX | [結構、格式、引用、圖片、表格、數學式與程式碼導覽](/docs/writing/latex/) |
| Typst | [標題、清單、格式、數學式、圖片、引用、標籤與程式碼區塊](/docs/writing/typst/) |
| Markdown | [原始碼與視覺化編輯、Pandoc 格式、連結、影像與表格](/docs/writing/markdown/) |

## 編輯器工具列

三種工具列使用相同的配置：

- **程式碼 / 視覺化** 在最前面，可以在原始碼與[視覺化編輯](#visual-editing)之間切換開啟的檔案。
- 接著是 **復原** 和 **重做**。沒有可復原或重做的內容時，各自會變成灰色。
- 中間是格式與插入按鈕。放不下的按鈕，在任何寬度下都會移進 **更多格式選項**（`…`），所以窄的編輯器也不會失去任何控制項。
- 右端保留文件工具，讓它們一直可見：**LaTeX 套件** 或 **Typst 套件**（請參閱[套件](/docs/packages/)）、[文件分析](/docs/document-insights/)、[文件設定](/docs/document-settings/)、**專案資訊**、**尋找** 和 **前往 PDF**。

Markdown 沒有套件按鈕。你也可以從 ⌘K 面板開啟這些工具：**瀏覽 LaTeX 套件**、**瀏覽 Typst 套件**、**文件分析** 和 **文件設定**。

## 掌握你的位置

固定捲動會在你捲動時，讓所在的章節或環境保持可見。在 Typst 檔案中，游標上方的標題也會以同樣的方式固定在上方。**設定 → 外觀 → 編輯器** 中的 **固定捲動** 可以將它關閉。

`.tex` 和 `.typ` 檔案上方有一條階層導覽列，會指出檔案以及游標所在的章節。按一下其中一項可以跳到該標題。專案大綱幫助你在各章之間移動，而參照和引用導覽會帶你前往符號背後的原始碼。[自動完成](/docs/autocomplete/)包含能辨識套件的 LaTeX 命令、數學輸入和引用詳細資料。

每個側邊欄檢視都會為每個專案記住它的捲動位置、展開的資料夾和開啟的區段，所以你回來時會回到同一個位置。

![應用程式先切換到深色主題，再進入禪模式，只留下原始碼和 PDF。](https://cdn.oleafly.com/images/gifs/desktop/theme-zen.gif?v=2)

## 禪模式

禪模式會隱藏專案工具列、側邊欄、助理、終端機，以及編輯器自己的分頁和格式列。只留下你的寫作內容，編輯器保有完整的寬度。

在 macOS 上按 Ctrl+⌘⇧F，在 Windows 和 Linux 上按 Shift+F11 即可開啟。你也可以在專案工具列的 **版面配置** 選單或 macOS 的 **檢視** 選單中選擇 **禪模式**，或從 ⌘K 面板執行 **切換禪模式**。再按一次同一個鍵，或按兩次 Esc，就能離開。

在禪模式中，**編譯** 按鈕位於右上角，PDF 開啟時就在 PDF 上方，當指標靠近時才會顯示。建置期間，那裡的一個小膠囊會顯示 **正在編譯**。建置失敗後，它會顯示 **編譯失敗**，點選它可以顯示或隱藏編譯記錄檔。⌘↵ 仍然會編譯，而 ⌘⌥P 可以在不離開禪模式的情況下顯示或隱藏 PDF。

有兩個選項位於[設定 → 外觀 → 專案](/docs/settings/appearance/#zen-mode-settings)下。**進入全螢幕** 會在禪模式開啟時填滿螢幕。**編譯時顯示 PDF** 會在 PDF 隱藏時，每次編譯都在編輯器旁邊開啟 PDF。快捷鍵本身可以在 **設定 → 鍵盤快捷鍵** 中變更。

## 主題、顏色與字型

編輯器在應用程式為淺色時使用一個主題，在深色時使用另一個。請在[設定 → 外觀 → 編輯器](/docs/settings/appearance/#editor-themes)下選擇兩者、變更原始碼任何部分的顏色，並選擇編輯器字型、大小、行高、字距和游標。另外有獨立的[中日韓字型](/docs/settings/appearance/#cjk-font)，可設定中文、日文與韓文字元的字型，讓拉丁文字維持使用程式碼字型。顏色依循在 LaTeX、Typst 和 Markdown 中意義相同的角色。在 LaTeX 中，章節命令及其標題都使用標題顏色，引用鍵和環境名稱沿用其命令的顏色，數學式則是同一種顏色。像 `[@key]` 和 `@key` 這樣的 Markdown 引用會被醒目提示為引用，而不是連結。

## 尋找與取代

按 ⌘F 會在編輯器右上角顯示 VS Code 風格的小工具：

- **大小寫須相符**（`Aa`）、**全字拼寫須相符**（`ab`）和**使用規則運算式**（`.*`）開關
- 即時的相符計數器（`3/41`），並有 `沒有結果` 和 `無效` 狀態，在超大文件中最多顯示到 `2000+`
- Enter 跳到下一個相符項目，Shift+Enter 跳到上一個，Esc 關閉
- **選取所有相符項目** 會把每個相符項目變成一個游標，以便同時編輯
- 箭頭會展開 **取代** 列：取代下一個、取代 **全部**，以及 **保留大小寫** 開關，它會把原始文字的大小寫對應到取代文字上（所以把 `figure` 取代為 `image` 時，`Figure` 也會變成 `Image`）

⌘A 會選取整個檔案，包括捲動到畫面外的行，所以接著複製或刪除會處理所有內容。

## 程式碼摺疊

按一下邊欄中的箭頭即可摺疊。

- 在 LaTeX 中，`\begin…\end` 環境會摺疊成一個區塊（能辨識巢狀），而章節會一直摺疊到下一個相同或更高層級的章節。
- 在 Typst 中，標題會一直摺疊到下一個相同或更高層級的標題。`{…}` 中的程式碼區塊、`[…]` 中的內容區塊、引數清單、方程式、原始區塊和區塊註解也能摺疊。

編輯後面的章節時，可以把前面的章摺疊起來。

## 註解掉行

按 ⌘/ 可以註解或取消註解目前這一行或選取的行。LaTeX 的行會加上 `%`，Typst 的行會加上 `//`。在編輯器之外，同一個鍵會開啟快捷鍵參考。

## 多重游標與區塊選取

編輯器支援多重選取：**Alt 拖曳**可以做矩形（直欄）選取，尋找小工具中的 **選取所有相符項目** 則為每個相符項目建立一個游標。每個游標會一起輸入、刪除和貼上。

## 縮排與括號

編輯器會在你輸入時縮排，每一層四個空格，除非你在 **設定 → 外觀 → 編輯器** 中變更 **Tab 寬度**。Tab 會縮排，或接受開啟中的自動完成建議。括號和引號會自動關閉，退格鍵會一起移除成對的符號，游標處配對的括號會醒目提示。

## Typst 輸入輔助

Typst 檔案有一些專屬的輔助功能：

- 輸入 `$`，結尾的 `$` 會跟著出現。在空的成對符號中按 Space，可以把它變成行間公式 `$ … $`。在空的成對符號中按 Backspace 會同時移除兩個符號。
- 選取一些文字並輸入 `*`、`_`、`` ` `` 或 `$`，可以把它包成粗體、強調、原始文字或數學式。
- 在清單項目上，Enter 會以相同的標記（`-`、`+`、`/` 或數字）開始下一個項目。Shift+Enter 在項目內開始新的一行，在空標記之後立即按 Backspace 會移除它。Tab 讓項目再往內縮一層，Shift+Tab 則把它移回外層。
- 在行首或空格之後輸入 `/`，會開啟 Typst 片段：標題、插圖（影像）、插圖（表格）、表格、行間公式、附標籤的編號公式、註腳、引述區塊、程式碼區塊、目錄、參考文獻、換頁、分欄、格線、連結，以及三種清單。
- ⇧⌥F（Shift+Alt+F）會用 typstyle 格式化檔案。在 **設定 → 外觀 → 編輯器** 的 **Typst** 下開啟 **儲存時格式化**，每次按 ⌘S 都會格式化。自動儲存不會重新格式化。

`$` 配對需要 **自動關閉括號** 和 **自動關閉數學符號** 兩者，包住選取文字則需要 **自動關閉括號**。兩個開關都在 **設定 → 外觀 → 編輯器** 中。清單按鍵一律開啟。自動完成、重新命名、前往定義和簽章說明來自 Typst 語言伺服器；請參閱[自動完成](/docs/autocomplete/)和[程式碼智慧](/docs/code-intelligence/)。

## 在 Typst 中插入圖片、表格與參照

Typst 有和 LaTeX 相同的插入工具，每一個都會寫出 Typst。它們位於 Typst 工具列和編輯器的右鍵選單中：

- **插入圖片** 會開啟圖片對話方塊。從專案中挑選影像，或匯入一張，然後設定它的寬度、說明、標籤、替代文字和位置。游標位於現有的 `#figure` 之內時，同一個按鈕會開啟 **編輯圖片**，讓你變更其中任何一項。
- 把影像檔貼到或拖放到編輯器中。如果專案有 `figures/` 資料夾，Oleafly 會把它儲存在那裡，否則儲存在主文件旁邊，並插入使用它的圖片。
- **插入表格** 會加入你所選大小的空表格。右鍵選單中的 **從 CSV/XLSX 匯入表格…** 會匯入 CSV、TSV、Excel 或 JSON 檔案，並可選擇附上說明和標籤。開啟 **保持與資料檔案的連結**，Oleafly 會把資料複製到專案的 `data` 資料夾。表格在每次編譯時都會讀取該檔案，所以當你編輯資料時，表格也會跟著更新。
- **從專案引用** 會為專案參考文獻中的條目寫入 `@key`。如果文件還沒有 `#bibliography`，Oleafly 會加入一個。
- **加入標籤** 會在游標處的標題、圖片或方程式上加上標籤，或選取它已有的標籤。**插入交互參照** 會列出專案的標籤並寫入 `@label`。
- 數學按鈕會插入行內公式、行間公式、附標籤的編號公式，或多行對齊公式。如果文件沒有方程式編號規則，附註會提供 **加入規則**。
- **符號** 會以 Typst 的名稱插入每個符號。

[用 Typst 寫作](/docs/writing/typst/)涵蓋了每個工具列按鈕。

## 視覺化編輯

每個 LaTeX、Typst 和 Markdown 檔案的工具列開頭都有 **程式碼 / 視覺化** 切換。新專案以程式碼模式開啟，每個專案都會記住你離開時的模式。Markdown 還有 **兩者**，它會把原始碼和排版後的文字上下堆疊或並排顯示。

在 LaTeX 和 Typst 中，視覺化模式是同一個編輯器，只是標記會就地繪製出來。把游標放在標題、方程式或命令中，它的原始碼就會在那一行回來。移開之後，繪製後的樣子會再出現。檔案仍是唯一的副本，所以行號、摺疊、尋找與取代、拼字檢查和編譯錯誤都照常運作。每個工具列按鈕寫出的原始碼，都和在程式碼模式中寫出的相同。

在 Typst 檔案中，視覺化模式會顯示：

- 標題、粗體和強調文字、原始文字、連結，以及有顏色的文字
- 項目符號、編號和術語清單，連同它們的標記
- 由 Typst 繪製的行內和行間數學式
- 影像和圖片，說明以純文字顯示
- 可以輸入內容的格線式表格。選取儲存格，會出現一個工具列，可設定框線、對齊、新增或刪除列與欄，以及移除表格。
- 以標籤呈現的參照和引用，以及以小標記呈現的註腳

Typst 檔案頂端的 `#set`、`#show`、`#import` 和 `#let` 行會收合成一條 **顯示文件設定** 列。按一下它即可就地展開。LaTeX 序言區也以同樣的方式收合。

視覺化模式適合用來潤飾文句。需要處理結構或自訂命令時，請切換到程式碼模式。視覺化模式無法繪製的內容，會以可編輯的原始碼留在畫面上。

## 公式預覽

游標位於方程式之內時，繪製出的結果會出現在它的正上方。KaTeX 繪製 LaTeX 數學式，Typst 繪製 Typst 數學式。預覽的選單可以把它隱藏到你離開方程式為止，或將它關閉。**設定 → 外觀 → 編輯器** 中的 **公式預覽** 可以重新開啟它。

把 LaTeX 數學式貼到 Typst 檔案中，例如 `$\frac{a}{b}$` 或 `equation` 環境，下方會出現 **貼上為 Typst 數學式** 按鈕。按一下它，就會把你貼上的內容換成 Typst 數學式，或按 Esc 保留 LaTeX。對於檔案中已有的數學式，請選取它，並從右鍵選單選擇 **將 LaTeX 數學式轉換為 Typst**。

## 原始碼中的編譯錯誤

編譯失敗後，每個錯誤都會在它所屬的檔案中加上底線。對 Typst 而言，底線涵蓋 Typst 回報的確切範圍，而在套件內部引發的錯誤，則會指向你檔案中呼叫它的那一行。把滑鼠移到底線上可以閱讀訊息。常見的 Typst 錯誤，例如未知的名稱、缺少的檔案或套件，或未關閉的括號，都附有簡單的說明，解釋哪裡出了問題以及要檢查什麼。

[記錄檔窗格](/docs/compiling/#reading-the-logs)會列出每個錯誤，連同它的原始碼行和 Typst 的提示。

## 內建的 LaTeX 檢查器

編輯器會在你輸入時，於任何編譯之前檢查 LaTeX 檔案的結構問題：

- 沒有對應 `\begin` 的 `\end{itemize}`，或不相符的成對（`expected \end{figure}, got \end{table}`）
- 未關閉的環境
- 重複的 `\label{}` 鍵
- 一行中 `$` 的數量為奇數（幾乎都是忘了數學分隔符號）

錯誤會以紅色波浪底線標示，警告則是琥珀色，並在邊欄中加上標記。檢查器只讀取 LaTeX，所以它絕不會中止 Typst 或 Markdown 的編譯。實際 LaTeX 執行所產生的編譯錯誤，會另外出現在[記錄檔窗格](/docs/compiling/#reading-the-logs)中，而[預檢](/docs/preflight/)會在行內加上它自己的原始碼層級檢查。

## 字數統計

從 ⌘K 面板執行 **字數統計**，可以取得使用中檔案的字數、字元數和行數。Typst 檔案依 Typst 的規則計算，所以程式碼和註解不會計入總數。

## Vim 與 Emacs 按鍵

在 **設定 → 外觀 → 編輯器** 的 **按鍵組合** 下選擇 **Vim** 或 **Emacs**，或從 ⌘K 面板執行 **啟用 vim 模式**。Vim 提供 `hjkl`、運算子和文字物件（`dd`、`ciw`）、`:w` 和視覺模式。變更會立即生效，而本頁的 Oleafly 快捷鍵會在旁邊繼續運作。

## 不只是 .tex

檔案開啟時，會依副檔名套用對應的醒目提示：BibTeX、Markdown、JSON、YAML、TOML、CSS、shell 指令碼等等。影像和 PDF 會以繪製後的檢視開啟，而不是文字，二進位格式也受到保護，不會被意外損毀；請參閱[檔案與資料夾](/docs/files/#how-different-file-types-open)。

如果檔案在磁碟上變更，而你在其中有尚未儲存的編輯，橫幅會指出檔案名稱，並提供 **比較**、**保留我的版本** 和 **重新載入**。LaTeX、Typst 和 Markdown 檔案都有這項功能。

## 相關頁面

- [自動完成與斜線命令](/docs/autocomplete/)：命令、參照、引用以及 `/` 插入選單的完成功能
- [程式碼智慧](/docs/code-intelligence/)：跳到定義、重新命名、懸停卡片、公式預覽
- [拼字與文法](/docs/spellcheck-grammar/)：能理解 LaTeX 的離線 Hunspell 和 Harper 檢查
- [套件](/docs/packages/)、[文件分析](/docs/document-insights/)和[文件設定](/docs/document-settings/)：工具列右側的文件工具
- [鍵盤快捷鍵](/docs/keyboard-shortcuts/)：完整參考
- [行內 AI 編輯](/docs/ai-inline-edit/)：在選取範圍上按 ⌘L 並描述變更
