# 编辑器

用源码编辑和可视化编辑编写 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 隐藏时，每次编译都在编辑器旁边打开它。这个键本身可以在**设置 → 键盘快捷键**中更改。

## 主题、颜色和字体

应用为浅色时，编辑器使用一个主题；为深色时，使用另一个。在[设置 → 外观 → 编辑器](/docs/settings/appearance/#editor-themes)下，你可以选择这两个主题，更改源码任何部分的颜色，并选择编辑器的字体、字号、行高、字间距和光标。单独的[中日韩字体](/docs/settings/appearance/#cjk-font)用来设置中文、日文和韩文字符的字体，所以拉丁字母文本可以继续使用编程字体。颜色遵循在 LaTeX、Typst 和 Markdown 中含义相同的角色。在 LaTeX 中，章节命令及其标题都使用标题颜色，引用键和环境名称沿用它们所属命令的颜色，公式是一种颜色。`[@key]` 和 `@key` 这样的 Markdown 引用会作为引用而不是链接来高亮。

## 查找和替换

按 ⌘F，会在编辑器右上角出现一个 VSCode 风格的小部件：

- **区分大小写**（`Aa`）、**全字匹配**（`ab`）和**正则表达式**（`.*`）开关
- 实时的匹配计数器（`3/41`），带有 `无结果` 和 `无效` 状态，对超大文档上限为 `2000+`
- Enter 跳到下一个匹配项，Shift+Enter 跳到上一个，Esc 关闭
- **选择所有匹配项**会把每个匹配项变成一个光标，以便同时编辑
- 展开箭头会展开**替换**行：替换下一个、替换**全部**，以及一个**保留大小写**开关，它会把原词的大小写映射到替换词上（所以把 `figure` 替换成 `image` 时，`Figure` 也会变成 `Image`）

⌘A 会选中整个文件，包括滚动到视野之外的行，所以之后的复制或删除会作用于全部内容。

## 代码折叠

点击行号栏中的箭头即可折叠。

- 在 LaTeX 中，`\begin…\end` 环境作为一个块折叠（能识别嵌套），章节会一直折叠到下一个同级或更高级的章节。
- 在 Typst 中，标题会一直折叠到下一个同级或更高级的标题。`{…}` 中的代码块、`[…]` 中的内容块、参数列表、公式、原始文本块和块注释也都可以折叠。

编辑后面的章节时，可以把前面的一章折叠起来。

## 注释掉行

按 ⌘/ 可以注释或取消注释当前行或所选的行。LaTeX 的行会加上 `%`，Typst 的行会加上 `//`。在编辑器之外，同一个键会打开快捷键参考。

## 多光标和块选择

编辑器支持多重选择：**Alt 拖动**进行矩形（列）选择，以及查找小部件中的**选择所有匹配项**，为每个匹配项生成一个光标。所有光标会一起输入、删除和粘贴。

## 缩进和括号

编辑器会在你输入时缩进，每级四个空格，除非你在**设置 → 外观 → 编辑器**中更改**制表符宽度**。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 导言区以同样的方式折叠。

可视化模式适合通读一遍。需要处理结构或自定义命令时，请切换到代码模式。可视化模式画不出来的内容，会以可编辑的源码留在屏幕上。

## 公式预览

当光标位于公式内时，渲染结果会出现在它的正上方。LaTeX 公式由 KaTeX 绘制，Typst 公式由 Typst 绘制。预览的菜单可以在你离开公式之前隐藏它，或者把它关掉。**设置 → 外观 → 编辑器**中的**公式预览**可以把它重新打开。

把 LaTeX 公式粘贴到 Typst 文件中，比如 `$\frac{a}{b}$` 或 `equation` 环境，它的下方会出现一个**粘贴为 Typst 公式**按钮。点击它，就把你粘贴的内容换成 Typst 公式，或按 Esc 保留 LaTeX。对于文件中已有的公式，请选中它，然后在右键菜单中选择**将 LaTeX 公式转换为 Typst**。

## 源码中的编译错误

编译失败后，每个错误都会在它所属的文件中加下划线。对于 Typst，下划线覆盖 Typst 报告的确切范围，在宏包内部引发的错误会指向你文件中调用它的那一行。把鼠标悬停在下划线上可以阅读消息。常见的 Typst 错误，比如未知名称、缺少文件或宏包、括号未闭合，都附有通俗的说明，解释哪里出了问题以及该检查什么。

[日志窗格](/docs/compiling/#reading-the-logs)会列出每个错误，附带它的源码行和 Typst 的提示。

## 内置的 LaTeX Linter

编辑器会在你输入时、任何编译之前，检查 LaTeX 文件的结构问题：

- 没有匹配 `\begin` 的 `\end{itemize}`，或不匹配的成对命令（`expected \end{figure}, got \end{table}`）
- 未闭合的环境
- 重复的 `\label{}` 键
- 一行中 `$` 的数量为奇数（几乎总是忘了数学分隔符）

错误用红色波浪线，警告用琥珀色，行号栏中还有标记。这个 Linter 只读取 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 并描述更改
