跳转到内容
Oleaflyv0.4.12

为每个项目固定 Typst 版本,添加来自 Typst Universe 的包,控制字体、构建变体和可复现的 PDF,并把 LaTeX 项目转换为 Typst。

Oleafly 自带 Typst 0.15.1 和 Tinymist 0.15.8 语言服务器,所以新的 Typst 项目无需安装任何东西就能编译。本页介绍你可以更改的内容:项目使用哪个 Typst,包和字体从哪里来,以及同一份源码如何构建出不止一个 PDF。关于语法和工具栏,请从用 Typst 写作开始。

打开 设置 → 引擎 → Typst。第一张卡片是 Typst(内置),即随应用一起提供的版本。如果你的电脑上已经安装了 typst(在 PATH 中、Homebrew 的文件夹里或 ~/.cargo/bin 中),第二张卡片会把它显示为 这台电脑上的 Typst。固定为这个确切版本的项目可以用它编译。

它们下方的 版本 列出 Typst 0.11 到 0.15,最新的排在最前。每一行给出发布日期、下载大小、这份副本的来源(内置、已下载 或 系统),以及安装后它所使用的 Tinymist 版本。

  • 安装 会下载该版本。Oleafly 先尝试自己的镜像,再尝试 GitHub,并用内置在应用中的 SHA-256 校验值检查压缩包及其中的程序。不匹配的文件会被丢弃,安装失败或被取消也不会留下任何残留。下载的内容保存在 ~/.oleafly/toolchains/typst/。
  • 已安装行左侧的圆形按钮会把该版本设为默认版本。
  • 移除 会删除已下载的版本。默认版本不能被移除,所以请先选择另一个默认版本。

新的 Typst 项目会固定默认版本,由模板创建的项目、导入的项目和已链接的文件夹也一样。固定的版本以版本号而不是路径的形式存储在项目的 project.json 中,所以即使你移动项目或在另一台电脑上打开它,仍然有效。

之后更改默认版本不会影响已有的项目。这是有意为之:当 Oleafly 提供更新的 Typst 时,固定了版本的论文仍会保持相同的换行和页数。

要更改某个项目的版本,请打开 重新编译 旁边的箭头,在 Typst 版本(本项目) 下查看。默认 会跟随设置中选择的版本,并清除固定。其他条目是这台电脑上已安装的版本,在适用时标有 [内置] 或 [系统]。如果要使用未列出的版本,请先在设置中安装它。

如果你打开的项目固定了一个这台电脑上没有的版本,Oleafly 不会悄悄改用另一个 Typst 来构建。编译会停止并提示“Typst 0.13.1 未安装”,预览中会出现两个按钮:

  • 下载 Typst 0.13.1 会安装固定的版本并重新编译。当该版本是 Oleafly 提供的版本时才会出现。
  • 使用 Typst 0.15.1,按你的默认版本命名,会清除固定并用默认版本重新编译。

在你选择其中一个之前,编译菜单会把这个固定的版本标为 [未安装]。

打开 Typst 项目时,只要安装了更新的 Typst,设置中的 Typst 标签页就会显示 试用较新版本。选择 用 Typst 0.15.1 检查(或它所指明的任何版本)。Oleafly 会在临时文件夹中把项目构建两次,一次用项目当前的版本,一次用较新的版本。你的项目不会有任何改动。

报告会显示每次构建是否成功、页数,以及其中的错误和警告。如果页数发生变化,它也会告诉你。Typst 0.15.1 新增 列出只有较新版本才会报告的消息,Typst 0.15.1 不再报告 列出那些消失的消息。点击某条消息,即可在对应的行打开它所在的文件。

如果结果令你满意,切换到 Typst 0.15.1 会把项目固定到较新的版本。重新检查 会在你修复问题之后重新运行两次构建。

Tinymist 为 Typst 文件提供补全、悬停提示、重命名和格式化(参见代码智能)。每个 Typst 次版本都有自己的 Tinymist 版本,项目会与和其 Typst 版本匹配的那个通信。

内置的 Tinymist 覆盖 Typst 0.15。当你打开固定在较旧版本线上的项目时,Oleafly 会在后台下载匹配的 Tinymist,并进行同样的校验,状态显示为“正在下载 Tinymist 0.13.30,以匹配此项目的 Typst 版本。”如果下载失败,Oleafly 稍后会再次尝试。当设置发现已安装的 Typst 都不再需要某些 Tinymist 下载时,会提供 移除未使用的语言服务器下载。

保留较旧的版本,是为了让在这些版本上开始的项目继续以相同的方式构建。有些功能取决于 Typst 版本本身支持什么:

功能0.110.120.130.14 及更高版本
仅项目字体否是是是
可复现构建否是是是
PNG 和 SVG 导出的页面范围否是是是
PDF/A否PDF/A-2bPDF/A-2b、PDF/A-3bTypst 提供的所有 PDF/A 级别
PDF/UA-1否否否是
把包保存在项目文件夹中否是是是
HTML 导出,以及通过 Typst 的 HTML 进行的 Word 或 Markdown 导出否否是是
源码与 PDF 同步否否是是
每次编译都生成带标签的 PDF否否否是

在 Typst 0.15 及更高版本中,字体选择器可以说明每种字体的来源。当某项设置无法应用于项目所用的版本时,编译菜单会把它标为 需要更新版本的 Typst。

选择 Typst 包,即 Typst 工具栏最右端的包图标。按名称、关键词或类别搜索 Typst Universe。每个包都会显示它的最新版本,需要比项目所用版本更新的 Typst 的包会提示:“需要 Typst 0.14.0。此项目使用 Typst 0.13.1。”

插入 import 会在打开的 Typst 文件顶部写入 #import 行。复制 import 则改为把它放到剪贴板。

Typst 会在编译第一次导入某个 @preview 包时下载它,并保存在所有项目共享的缓存中。包列表也会被缓存。离线时,对话框会显示它最后一次获取的列表及其日期。

当某个 import 指定的版本比 Typst Universe 上的版本旧时,它的版本号会带下划线,并给出类似“cetz 0.4.2 已发布。此 import 使用的是 0.3.4。”的提示。提示卡片提供 更新到 0.4.2,它会修改 import 中的版本号。接受之前请先阅读该包的更新日志,因为新版本可能会改变包的调用方式。把鼠标悬停在 import 上,也会出现 在 Typst Universe 中打开。

在同一对话框的 项目包 下,将包复制到项目 会把项目导入的每个包复制到项目顶层的 typst-packages 文件夹中。它还会复制这些包所导入的包,并开启 使用项目文件夹中的包。

从那以后,Typst 会先在 typst-packages 中查找。这样的项目可以离线编译,也能在任何电脑上编译,而且这个文件夹可以连同源码一起放进 Git。没有复制过的包仍然来自共享缓存。这需要 Typst 0.12 或更新版本,在固定为 0.11 的项目中,对话框会请你先切换版本。

如果某个包还不在缓存中,对话框会点出它的名字:“这些包不在包缓存中:…”。请在联网时编译一次,然后再次复制。

在 设置 → 通用 中开启 离线模式 后,Typst 无法下载任何东西。每个包都必须已经在共享缓存或 typst-packages 中。如果有包不在,编译就会失败,并且消息会点出这个包,这样你就知道下次联网时要获取什么。

Typst 在四个地方查找字体:Typst 内置的字体、你电脑上安装的字体、你在 Oleafly 中下载的字体包,以及项目内的字体文件夹。把字体文件放进项目顶层名为 fonts 的文件夹,编译器和语言服务器都会找到它们。其他文件夹可以列在 project.json 的 typst.font_paths 下。项目之外的文件夹会被忽略。

在编译菜单的 字体(本项目) 下,默认是 使用系统字体。仅项目字体 会让 Typst 不再读取这台电脑上安装的字体。这样 PDF 在每台机器上生成的结果都一样;如果文档要求的字体项目里没有,你会在自己的电脑上发现,而不是在合著者的电脑上。

要选择正文字体,请打开 文档设置(Typst 工具栏上的滑块图标),然后点击 正文字体。列表会显示在项目当前字体设置下 Typst 能找到的每个字体族。在 Typst 0.15 及更高版本中,每个字体族都带有 项目、系统、字体包 或 内置 标签。选一个并选择 应用,Oleafly 就会把它写入文档的 #set 规则。

设置 → 下载 → 字体 提供五个免费的 Typst 字体包:中文、日文和韩文、经典正文、现代无衬线和衬线、代码 和 图标和表情符号。字体包下载完成后,每个 Typst 项目都可以按名称使用其中的字体,该标签页上 Lato、PT Sans 和 PT Serif 的下载也是如此。字体包只有在整个下载完成之后才会参与编译,所以下载到一半的字体包不会影响构建。

设置为 仅项目字体 或 可复现构建 的项目不会读取字体包。对这些项目,请把字体文件复制到项目的 fonts 文件夹中。

每次编译之后,Oleafly 会检查有没有可用字体都画不出来的字符。Typst 把这些字符画成方框。发现这样的字符时,编译会得到一条警告,编辑器上方也会出现通知:

  • 空方框 表示 Typst 能用的字体都没有这些字符,警告里会点出其中几个。当某个字体包涵盖它们时(例如中文、日文和韩文字体包涵盖 CJK 文本,图标和表情符号字体包涵盖表情符号),通知会提供带下载大小的 下载字体,日志里则提供 下载并编译。否则,请把包含它们的字体添加到项目的 fonts 文件夹。
  • 带问号的方框 表示 Typst 用占位字体画出了这些字符。请在 文档设置 的 正文字体 下指定一个包含它们的字体,或写在字体列表里,例如 #set text(font: ("Libertinus Serif", "Apple SD Gothic Neo"))。
  • 在设置为 仅项目字体 的项目中,字体包和系统字体都不适用。请把字体添加到 fonts 文件夹,或把项目切换为 使用系统字体 和 标准构建。

通知中的 文档设置 会打开用来选择正文字体的面板。关闭通知,即可针对那条警告把它隐藏。

构建变体是文档通过 sys.inputs 读取的一组命名的值。当同一份源码需要生成不同的 PDF 时,可以使用变体,例如匿名的评审版和定稿版,或带水印的草稿。

每个值的作用由文档决定。值始终以文本形式传入:

#let draft = sys.inputs.at("draft", default: "false") == "true"
#if draft [*Draft. Do not circulate.*]

设置变体的步骤:

  1. 打开 文档设置,滚动到 构建变体。
  2. 选择 添加变体 并为它命名,例如 review。
  3. 选择 添加值,然后在 名称 下输入 draft,在 值 下输入 true。
  4. 选择 应用。
  5. 打开编译菜单。变体(本项目) 现在列出了 review。选中它并编译。

无变体 会在没有任何变体值的情况下构建。你选择的变体只记在这台电脑上,所以合著者可以用同一个项目构建另一个变体。变体本身保存在 project.json 中。导出也会使用所选的变体。

每次构建都应获得的值放在 project.json 的 typst.inputs 下。当变体设置了同名的值时,以变体为准。

在编译菜单的 构建(本项目) 下,可复现构建 能让相同的源码在任何电脑上生成相同的 PDF。它只使用项目字体和 Typst 内置字体,并把 PDF 的日期设为最后一次 Git 提交的日期。不是 Git 仓库的项目会得到固定的日期,即 1970 年 1 月 1 日。

当 PDF 必须与某个校验值一致时,这一点很重要,例如用于档案库存档或 CI 中的比对。它需要 Typst 0.12 或更高版本。开启期间,使用系统字体 不可用。默认是 标准构建。

Typst 边输入边编译:每新增一行,PDF 中就会随之出现。
Typst 边输入边编译:每新增一行,PDF 中就会随之出现。 打开完整截图

在编译菜单中把 自动编译 设为 开启。此后在 Typst 项目中,Oleafly 会保持一个 Typst 进程持续运行。你停止输入片刻后,打开的文件会自动保存,Typst 随即编译,预览会在相同的滚动位置重新加载。没有单独的实时预览设置:自动编译就是实时预览。

Typst 启动期间,菜单会显示“正在启动 Typst”。如果它因反复出错而停止,菜单会如实说明,你的下一次编辑会让它重新启动。停止编译 会结束该进程,下一次编辑同样会让它重新启动。LaTeX 和 Markdown 项目对自动编译的处理方式不同,参见编译。

oleafly 命令无需打开应用就能构建项目。它随 Oleafly 一起提供,命令行工具介绍了如何把它放到你的 PATH 中。

对于 Typst 项目,oleafly build 和 oleafly watch 会读取 project.json,并使用与应用相同的设置:固定的版本、复制进项目的包、字体文件夹、系统字体开关、输入值和可复现构建。

  • --variant review 构建指定的变体。如果名称在项目中没有定义,构建会停止,消息中会列出项目实际拥有的变体。
  • --offline 会阻止下载包,与应用中的离线模式一样。
  • 固定了版本的项目只会用那个确切的 Typst 构建。命令行工具会依次查看 OLEAFLY_TYPST、应用下载的版本、命令行工具旁边的 typst,然后是你的 PATH。如果都没有报告出固定的版本,构建会在 Typst 运行之前停止,并告诉你如何安装。
  • 没有固定版本的项目在设置了 OLEAFLY_TYPST 时使用它。否则使用你在 设置 → 下载 中或通过 oleafly typst default 选择的默认版本;没有选择默认版本时,则使用内置的 Typst 或你的 PATH 中的那个。
  • oleafly doctor 会列出它找到的每个 Typst,以及构建将使用的设置。固定的版本缺失时,它会失败。

如果某项设置无法应用于正在使用的 Typst,构建会打印一条说明,例如 Typst 0.11.1 无法忽略系统字体。终端中的错误包含 Typst 自己的提示。

打开 LaTeX 项目,按 ⌘K(Ctrl+K),然后运行 转换为 Typst 项目。为新项目起个名字并选择 转换。LaTeX 项目保持原样。Oleafly 会据此构建一个独立的 Typst 项目:

  • Pandoc 转换文本、公式、图片和表格。如果 Pandoc 尚未设置,Oleafly 会先把它设置好。
  • 通过 \input、\include 或 \subfile 引入的每个文件,都会成为各自的 .typ 文件。
  • BibTeX 文件原样复制。
  • Typst 会编译新项目以进行检查。

随后报告会说明项目能否编译,并统计转换了哪些内容:源文件、图片、表格、行间公式、交叉引用、公式转换器修复的公式和复制的文件,以及它选择的参考文献样式。需要处理 列出需要手动修复的内容,例如缺失的引入文件或图片、Typst 无法显示的图片格式、转换器无法处理的公式、没有对应 Typst 样式的 BibTeX 样式,或多行公式中某一行上的标签(它现在指向整个公式)。编译错误和警告会链接到对应的文件和行。

选择 打开 Typst 项目 切换过去。新项目会固定你的默认 Typst 版本。只要 Oleafly 保持打开,命令面板中的 显示 Typst 转换报告 就能把报告调出来。

如果只想转换单个文件而不是整个项目,请在工具页面使用 LaTeX 转 Typst。

图片预览

无法加载 AI 回答

请重试,或搜索文档。