用 Typst 写作

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

带有格式工具栏、源码和编译后报告的 Typst 示例。 打开完整截图

编译一份小报告

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

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 项目中，这就是实时预览。参见用自动编译实时预览。

下载示例源码

每一个工具栏工具

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

代码 / 可视化

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

撤销

撤销你最近的一次编辑。⌘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 会添加一个。列表底部的 查找并添加新引用… 会打开对新来源的搜索。参见添加引用。

插入交叉引用

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

添加标签

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

插入脚注

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

插入引用块

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

插入图片

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

插入表格

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

插入图像

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

绘制图表

以 Typst 模式打开图表编排器。在画布上绘制，或编辑 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。代码智能介绍了这三项功能。

Typst 包

栏最右端的包图标会搜索 Typst Universe 并插入 #import 行。更多内容见包、设置和文档分析。

文档分析

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

文档设置

通过编辑文档的 #set 规则来更改页面大小、页边距、字体、语言、两端对齐、行距和编号。参见文档设置。

项目信息

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

查找

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

跳转到 PDF

从光标跳转到编译后 PDF 中的对应位置。该按钮在 Typst 0.13 及更高版本中出现。参见在源码与 PDF 之间跳转。

可视化模式

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

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

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

新项目默认以代码模式打开，每个项目会记住你离开时所处的模式。可视化编辑介绍了适用于这三种语言的切换。

输入时的辅助

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

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

公式预览

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

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

添加带图注的图片

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

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

#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 文件夹，表格每次在文档编译时都会读取该文件。编辑这个文件，表格就会在下次编译时更新。从数据文件导入表格完整介绍了这个对话框。

添加引用

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

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

#bibliography("references.bib")

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

包、设置和文档分析

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

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

错误与检查

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

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

在源码与 PDF 之间跳转

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

格式化文件

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

Typst 版本

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

组织与导出

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

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

要把现有的 LaTeX 项目迁移到 Typst，请参见把 LaTeX 项目转换为 Typst。