# 用 Typst 写作

在代码或可视化模式下写 Typst 论文、报告或简历，工具栏会替你写出 Typst。

选择一个 Typst 模板，在编译出的 PDF 旁边编辑它的 `.typ` 源码。工具栏会替你写出 Typst 语法，所以每一处改动都留在源码里，你可以阅读和编辑。如果你不想看到标记，可以把文件切换到可视化模式。

![带有格式工具栏、源码和编译后报告的 Typst 示例。](https://cdn.oleafly.com/images/screenshots/desktop/docs/typst-writing-dark-window-v2.png)

## 编译一份小报告

1. 选择 **新建项目 → 使用模板 → Blank Typst document**。
2. 把它命名为 **测量笔记**，然后打开 `main.typ`。
3. 粘贴下面的示例，然后选择 **重新编译**，或按 **⌘Enter / Ctrl+Enter**。

```typst title="main.typ"
#set document(title: "Measurement note", author: "Alex Chen")
#set page(paper: "a4", margin: 25mm)
#set heading(numbering: "1.")

= Measurement note
A short report on repeated measurements.

== Method <method>
We collect three observations and compare their mean.

$ overline(x) = (1 + 2 + 3) / 3 = 2 $

== Results
See @method for the procedure.

#table(
  columns: 2,
  [Run], [Value],
  [1], [1],
  [2], [2],
  [3], [3],
)
```

PDF 中应该显示带编号的标题、一个行间公式、一个指向方法一节的引用和一个两列表格。

想在输入时看到 PDF 随之变化，请打开 **重新编译** 旁边的箭头，把 **自动编译** 设为 **开启**。在 Typst 项目中，这就是实时预览。参见[用自动编译实时预览](/docs/typst/#live-preview-with-auto-compile)。

[下载示例源码](/examples/writing-example.typ)

## 每一个工具栏工具

使用格式工具之前先选中文字，该工具就会包裹这段文字。没有选区时，工具栏会插入一个可以直接覆盖输入的占位符。当编辑器太窄、放不下所有按钮时，放不下的按钮会移入 **更多格式选项**（`…`）。这些工具大多数也出现在编辑器的右键菜单中。

### 代码 / 可视化

工具栏开头的切换开关会改变文件的显示方式。**代码** 显示 Typst 源码。**可视化** 会就地渲染标题、强调、列表、公式、图片、表格、引用和脚注，并在光标所在的行恢复显示源码。两种模式下的文件是同一个。详情见 [Typst 中的可视化模式](#visual-mode)。

### 撤销

撤销你最近的一次编辑。⌘Z / Ctrl+Z。没有可撤销的内容时，该按钮显示为灰色。

### 重做

重新应用被撤销的编辑。**⌘Shift+Z / Ctrl+Shift+Z**。

### 标题 → 标题

选中标题并选择 **标题**。`= Title`。

### 标题 → 章节

在文档中添加一个章节。`== Section`。

### 标题 → 小节

添加比章节低一级的标题。`=== Subsection`。

### 标题 → 子小节

添加四级标题。`==== Subsubsection`。

### 标题 → 小标题

添加五级标题。`===== Minor heading`。

### 标题 → 段落标题

添加六级标题。`====== Paragraph heading`。

### 加粗

选中“three observations”。`*three observations*`；⌘B / Ctrl+B。

### 斜体

选中要强调的术语。`_term_`；⌘I / Ctrl+I。

### 下划线

选中一个短语。`#underline[phrase]`。

### 删除线

标记一个已过时的短语。`#strike[phrase]`。

### 行内代码

选中文件名或变量名。用反引号把它括起来。

### 插入链接

替换 `url`，再替换 `text`。`#link("url")[text]`。

### 从项目引用

按键、作者或标题搜索项目的参考文献，然后选择一个条目。Oleafly 会写入 `@key`。如果文档里还没有 `#bibliography` 调用，Oleafly 会添加一个。列表底部的 **查找并添加新引用…** 会打开对新来源的搜索。参见[添加引用](#add-citations)。

### 插入交叉引用

从项目的标签列表中选一个标签，写出 `@label`。在示例中，选择 `method` 得到 `@method`。**在此处添加标签** 则改为在光标处的项目上放一个新标签。

### 添加标签

把光标放在标题、图片或公式中，然后选择 **添加标签**。在示例中的 Results 标题上，Oleafly 会添加 `<sec:results>`。如果该项目已经有标签，按钮会选中它。

### 插入脚注

把光标放在某个词之后。`#footnote[note text]`。

### 插入引用块

把光标放在新的一行。`#quote(block: true)[quote]`。

### 插入图片

打开图片对话框。从 **项目图片** 中选一张图片，或选择 **从磁盘导入…**，然后设置它的宽度、图注、标签、替代文本和位置。当光标位于已有的 `#figure` 内时，同一个按钮会打开 **编辑图片**，让你修改其中任何一项。参见[添加带图注的图片](#add-a-captioned-figure)。

### 插入表格

打开网格，选择行数和列数。Oleafly 会插入一个 `#figure`，其中的 `table` 带有表头行以及顶线、中线和底线，另外还有 `caption: [Caption]` 和标签 `<tab:label>`。替换表注、标签和空单元格。如果想改为用电子表格生成表格，请参见[来自数据文件的表格](#tables-from-data-files)。

### 插入图像

导入一张图片，然后把选中的文件名替换为它的相对路径。`#image("image-filename")`。你也可以把图片文件粘贴或拖放到编辑器中，Oleafly 会把它保存到项目里，并插入一个使用该图片的图片块。

### 绘制图表

以 Typst 模式打开[图表编排器](/docs/figures-diagrams/)。在画布上绘制，或编辑 fletcher 代码，然后选择 **以 Typst 插入**，把图表放到光标处。第一次预览会从 Typst Universe 下载 fletcher 包，所以需要联网。

### 图片转 Typst

选择公式或文字的截图，它会在光标处被转写成 Typst。它使用工具所用模型（除非你另选，否则是本地的 Ollama 模型）。如果你没有另选，而 Ollama 没有运行或没有能够读图的模型，它会改用助手的模型，图片也会发送给那个提供商。请检查结果并编译。

### 列表 → 无序列表

开始一个观察项列表。`- Item`。

### 列表 → 有序列表

开始一系列步骤。`+ Item`。

### 公式

选中 `x` 并点击公式图标。`$x$`。

### 行间公式

独占一行的公式。`$ x $`，每个 `$` 内侧各有一个空格。

### 编号公式

带标签的行间公式，例如 `$ x $ <eq:label>`。只有文档设置了编号规则，Typst 才会给公式编号。如果你的文档没有，提示中会出现 **添加规则**，它会在文件靠近顶部的位置添加 `#set math.equation(numbering: "(1)")`。

### 多行对齐公式

多个公式在 `&` 处对齐，行与行之间用 `\` 分隔。`$ a &= b \ c &= d $`。

### 分式

插入 `frac(a, b)`；如果光标不在公式中，会用 `$` 包起来。选中文字时，所选内容会成为分子。

### 符号

打开符号选择器，搜索符号并选中它。Oleafly 会用它的 Typst 名称写出：公式内是 `arrow.r`，正文中是 `#sym.arrow.r`。

### 代码块

选中几行代码，或替换占位符。生成由三个反引号包围的代码块。在起始围栏后添加语言名即可获得语法高亮。

### 代码智能 → 转到定义

把光标放在标签、变量或函数上，选择该操作，或按 F12。会打开它的定义处，即使在另一个文件中也一样。

### 代码智能 → 查找引用

列出标签、变量或函数被使用的每一处。⇧F12。

### 代码智能 → 重命名符号

在整个项目中重命名标签、变量或函数。F2。[代码智能](/docs/code-intelligence/#typst-files)介绍了这三项功能。

### Typst 包

栏最右端的包图标会搜索 Typst Universe 并插入 `#import` 行。更多内容见[包、设置和文档分析](#packages-settings-and-insights)。

### 文档分析

列出文档的标题、图片、表格、公式、标签、引用和待办事项，每一项都链接到所在的行。参见[文档分析](/docs/document-insights/)。

### 文档设置

通过编辑文档的 `#set` 规则来更改页面大小、页边距、字体、语言、两端对齐、行距和编号。参见[文档设置](/docs/document-settings/)。

### 项目信息

显示文档及任意选区的字数、图片数和公式数，以及校对结果。

### 查找

在当前文件中搜索某个词。⌘F / Ctrl+F。

### 跳转到 PDF

从光标跳转到编译后 PDF 中的对应位置。该按钮在 Typst 0.13 及更高版本中出现。参见[在源码与 PDF 之间跳转](#jump-between-the-source-and-the-pdf)。

## 可视化模式

在任何 `.typ` 文件中，把工具栏从 **代码** 切换到 **可视化**。可视化模式是同一个编辑器，只是标记会就地渲染：

- 标题、加粗和强调的文字、原始文本、链接和带颜色的文字
- 无序列表、有序列表和术语列表，连同它们的标记
- 行内和行间公式，由 Typst 绘制
- 图片和插图，图注显示为文字
- 表格显示为可以直接输入的网格。选中一个单元格会出现小工具栏，用于设置边框、对齐、行和列。
- 引用和参考文献显示为标签块，脚注显示为小标记

把光标放在某一行上，它的源码就会回来，方便你编辑。移开后，渲染的形式又会恢复。文件顶部的 `#set`、`#show`、`#import` 和 `#let` 行会折叠成一个 **显示文档设置** 栏，点击即可展开。可视化模式画不出来的内容会以源码形式保留在屏幕上。每个工具栏按钮在两种模式下写出的 Typst 相同，行号、查找、拼写和编译错误也都照常工作。

新项目默认以代码模式打开，每个项目会记住你离开时所处的模式。[可视化编辑](/docs/editor/#visual-editing)介绍了适用于这三种语言的切换。

## 输入时的辅助

Typst 文件获得与 LaTeX 文件相同的辅助功能，只是针对 Typst 语法而写：

- 点击行号槽中的箭头，可以把一个标题折叠到下一个同级标题之前。代码块、内容块、公式和较长的参数列表也可以折叠。参见[代码折叠](/docs/editor/#code-folding)。
- 滚动时，光标上方的标题会固定在编辑器顶部。文件上方的面包屑栏会标出你所在的章节，点击其中一项会跳转到对应的标题。
- 输入 `$` 会自动补上结尾的 `$`，在空的一对中键入空格会把它变成行间公式。在列表项上按 Enter 会开始下一项。[Typst 输入辅助](/docs/editor/#typst-typing-aids)列出了其余功能。
- Typst 语言服务器可补全函数、文件路径、标签、引用键、包和参考文献样式。参见 [Typst 补全](/docs/autocomplete/#typst-completion)。
- 在行首或空格之后输入 `/`，可使用代码片段：标题、图片、表格、公式、脚注、目录、参考文献等等。
- ⌘/ / Ctrl+/ 用 `//` 注释或取消注释所选的行。

### 公式预览

光标位于公式内时，Typst 会在公式正上方绘制结果。预览的菜单可以将其隐藏到你离开该公式为止，也可以将其关闭。

把 `$\frac{a}{b}$` 这样的 LaTeX 公式粘贴到 Typst 文件中，下方会出现一个 **粘贴为 Typst 公式** 按钮。点击它，就能把粘贴的内容替换为 Typst 公式；按 Esc 则保留 LaTeX。对于文件中已有的 LaTeX 公式，选中它，并从右键菜单中选择 **将 LaTeX 公式转换为 Typst**。如果只是一次性转换，[公式转 Typst](/docs/tools/equation-to-typst/) 工具可以在项目之外完成同样的事。

## 添加带图注的图片

1. 选择工具栏上的 **插入图片**。
2. 在 **项目图片** 下选中 `plot.png`，或选择 **从磁盘导入…** 把它复制到项目中。
3. 选择 **四分之三宽**，然后开启 **添加图注** 和 **添加标签**。输入图注和标签 `fig:measurements`。
4. 添加 **替代文本**，为屏幕阅读器描述这张图片；如果图片应当浮动到页面顶部或底部，请选择 **位置**。
5. 选择 **插入图片**。

Oleafly 会写出像下面这样的图片：

```typst
#figure(
  image("figures/plot.png", width: 75%),
  caption: [Measurements across three runs.],
) <fig:measurements>

See @fig:measurements for the comparison.
```

之后要修改图片时，把光标放在其中，再次选择 **插入图片**。对话框会以 **编辑图片** 的形式打开，并带有当前的值。

## 来自数据文件的表格

在编辑器中右键点击，选择 **从 CSV/XLSX 导入表格…**。选择 CSV、TSV、Excel 或 JSON 文件，检查预览，如果需要，再添加题注和标签。**在光标处插入** 会写入一个 Typst 表格，其表线与工具栏所生成的表格相同。Typst 会当作标记来读取的单元格文字会被转义。

开启 **保持与数据文件的链接**，让表格与它的数据保持关联。Oleafly 会把数据复制到项目的 `data` 文件夹，表格每次在文档编译时都会读取该文件。编辑这个文件，表格就会在下次编译时更新。[从数据文件导入表格](/docs/writing/tables-equations/#import-a-table-from-a-data-file)完整介绍了这个对话框。

## 添加引用

用 **从项目引用** 添加引用，或输入 `@` 并从补全列表中选一个键。在 Typst 中，引用键和文档标签都使用 `@`；目标由参考文献或标签提供。

把参考文献放在你希望参考文献列表出现的位置：

```typst
#bibliography("references.bib")
```

该文件可以是 BibTeX（`.bib`）或 Hayagriva（`.yml`），调用中也可以写出文件列表。你从[参考文献与引用](/docs/citations/)添加的引用会进入文档所声明的文件，在该文件需要时会转换为 Hayagriva。要更改参考文献样式，请使用参考文献面板底部的 **引用样式** 菜单，它会替你写出 `style:` 参数。参见[选择 Typst 引用样式](/docs/citations/#choose-a-typst-citation-style)。

## 包、设置和文档分析

工具栏最右端的三个按钮作用于整个文档：

- **Typst 包** 搜索 Typst Universe 并写入 `#import` 行。当某个 import 指定的是较旧的版本时，编辑器会提示更新。项目也可以保存自己的包副本，以便离线编译。参见[宏包与包](/docs/packages/#typst-packages)和[来自 Typst Universe 的包](/docs/typst/#packages-from-typst-universe)。
- **文档分析** 列出标题、图片、表格、公式、标签、引用和待办事项，并可复制标题、作者、关键词和摘要用于投稿表单。对话框打开时 Typst 会读取文档，所以编号和页码是最新的。参见[文档分析](/docs/document-insights/)。
- **文档设置** 更改页面大小、页边距、分栏、正文字体、字号、语言、两端对齐、行距，以及标题和公式的编号。Oleafly 会把你的选择写入主文件的 `#set` 规则。项目的构建变体也在其中。参见[文档设置](/docs/document-settings/)。

## 错误与检查

编译失败时，每个错误都会在所在文件中加下划线，范围正是 Typst 报告的那一段。把鼠标悬停在下划线上，可以阅读消息和 Typst 的提示。常见的错误，例如未知的名称、缺失的文件或包，或未闭合的括号，都附有通俗的解释。参见[源码中的编译错误](/docs/editor/#compile-errors-in-the-source)。

[拼写与语法](/docs/spellcheck-grammar/)会检查 Typst 文件中的正文，包括图注、表格单元格和 `abstract:` 这样的模板字段，并跳过代码。[预检](/docs/preflight/#typst-projects)会检查 Typst 源码中未解析的引用和参考文献、缺失的替代文本、缺失的图片、文档元数据以及盲审方面的问题。

## 在源码与 PDF 之间跳转

选择工具栏上的 **跳转到 PDF**，或按 ⌘⇧J / Ctrl+Shift+J，从光标跳转到对应的页面。在 PDF 中按住 ⌘ 或 Ctrl 并点击某个词，就能跳回它所在的行，即使它位于用 `#include` 引入的文件中。同步需要 Typst 0.13 或更高版本。参见[源码与 PDF 同步](/docs/synctex/#typst-projects)。

## 格式化文件

**格式化文档** 用 typstyle 整理整个文件。按 ⇧⌥F / Shift+Alt+F，或从右键菜单中选择它。**格式化所选内容** 只格式化选中的行。如果想在每次按 ⌘S / Ctrl+S 时都格式化，请在 **设置 → 外观 → 编辑器** 的 **Typst** 下开启 **保存时格式化**。参见[格式化 Typst 文件](/docs/code-intelligence/#format-a-typst-file)。

## Typst 版本

Oleafly 自带 Typst 0.15.1，**设置 → 引擎 → Typst** 中列出了可供下载的 Typst 0.11 到 0.15。新项目会固定默认版本，所以当 Oleafly 之后提供更新的 Typst 时，它的换行和页数仍保持不变。要更改某个项目的版本，请打开 **重新编译** 旁边的箭头，在 **Typst 版本（本项目）** 下选择。语言服务器跟随项目的版本。[Typst 版本](/docs/typst/#typst-versions)介绍了固定版本、缺失的版本，以及如何在切换前测试较新的版本。

## 组织与导出

把较长的报告拆分成多个文件，并用 `#include "sections/method.typ"` 引入它们。把图片、数据、字体和参考文献文件都放在项目内，这样源码 ZIP 就会带上文档所需的一切。

编译并检查结果，然后打开 **导出**。其中有 **导出为 PDF**、**导出源码 (.zip)**、**将页面导出为 PNG** 和 **图片和 HTML**；最后一项会用 Typst 本身写出 PNG 或 SVG 页面，或一个 HTML 文件。在 Typst 0.13 及更高版本中，Word、HTML、Markdown、LaTeX 和纯文本的导出会经由 Typst 自己的 HTML 输出，因此公式和引用得以保留。参见[导出与转换项目](/docs/export/#typst-images-and-html)。[编译](/docs/compiling/)介绍日志和编译选项，[文件与文件夹](/docs/files/)介绍项目的组织方式。

要把现有的 LaTeX 项目迁移到 Typst，请参见[把 LaTeX 项目转换为 Typst](/docs/typst/#convert-a-latex-project-to-typst)。