# 图片与图表

图表编排器：在画布上绘制或直接写代码，LaTeX 用 TikZ，Typst 用 fletcher，Markdown 用 Mermaid，带实时预览和可编辑的源码。

在画布上画一幅图表，就能得到所用文档语言的纯源码：LaTeX 用 TikZ，Typst 用 fletcher 图表，Markdown 用 Mermaid 流程图。绘图和代码保持同步，所以你可以随时在两者之间切换。

编排器在你的设备上运行，不需要账号。（由助手编写的图片，参见[用 AI 画图](/docs/ai-figures/)。）

## 打开编排器

在主屏幕上，选择程序坞中的 **图表编排器**。你也可以在 ⌘K（Ctrl+K）命令面板中运行 **打开图表编排器**，或在搜索栏中输入 `/diagram`。会弹出一个对话框 **选择图表编排器**，询问这幅图表用于什么：**TikZ 图表** 用于 LaTeX 文档，**Typst 图表** 用于 Typst 文档，**Mermaid 图表** 用于 Markdown 文档。

如果是在已打开的文档中，请改为选择编辑器工具栏上的 **绘制图表**。编排器会跳过这个问题，直接使用该文档的语言：`.tex` 文件用 TikZ，`.typ` 文件用 Typst，Markdown 文件用 Mermaid。**返回项目** 会带你回到文档。

标题栏会显示图表的名称（点击即可重命名）以及标注其语言的小标签。

![先用代码编写 TikZ 图，再在画布上把它当作图形来编辑。](https://cdn.oleafly.com/images/gifs/desktop/tikz-composer.gif?v=2)

## 在画布上绘制

**绘制** 模式就是画布。它在三种语言中的用法相同。

从调色板中选一个形状（矩形、圆角矩形、圆形、椭圆、菱形、平行四边形或文本），然后点击并拖动来放置并调整大小。**数学** 和 **代码** 是文本框，初始内容分别是一个公式或该图表语言的代码示例。

要连接两个形状，从其中一个的控制点拖到另一个。移动任意一个形状时，连线都会保持连接。选中连线，可以选择箭头（终点、两端或无）、路由方式（直线、直角或曲线）和标签。选中形状，可以更改它的标签、填充、边框、圆角半径或字体。

移动形状时它们会自动对齐，撤销和重做的用法照常。按住空格键并拖动可以平移，双击形状可以编辑其中的文字。

![用 fletcher 包绘制一张工作流图并编译。](https://cdn.oleafly.com/images/gifs/desktop/typst-composer.gif?v=2)

## 编辑代码

**代码** 模式把同一幅图表显示为源码，并带有 **代码片段** 菜单，提供矩形节点、圆形节点、箭头边和直线边等常用片段。编辑任意一边，另一边都会跟着变化：移动方框，代码随之改变；在代码中重命名标签，画布也随之改变。

代码是每种语言的普通源码：

- TikZ：包含节点和边的 `tikzpicture`。
- Typst：完整的 fletcher 代码片段，包含 `#import "@preview/fletcher:…"` 这一行，以及内含 `node(…)` 和 `edge(…)` 项的 `#diagram(…)` 调用。fletcher 的版本与已打开的 Typst 项目的 Typst 版本相匹配：Typst 0.13 及更高版本用 0.5.8，0.12 用 0.5.5，更早的版本用 0.5.1。
- Mermaid：包含节点形状、带标签的连线、用于颜色的 `style` 行以及用作分组框的子图的流程图。Mermaid 会自己布局图表，所以你在画布上设置的位置不属于代码的一部分。

### 画布无法绘制的代码

在 Typst 和 Mermaid 中，画布无法显示的代码会完全保持你写的样子。对于 Typst，这包括导入语句、`#let` 行、`#figure(…)` 之类的包装、额外的图表设置和循环。对于 Mermaid，这包括 `click` 行、指令、注释和 frontmatter。你没有在画布上改动的节点或边会保留原有文本，改动过的则会保留画布不认识的那些选项。

当画布没有显示全部内容时，标题栏中会出现一个带计数的说明按钮，例如 **2 条说明**。它列出哪些内容只保留在代码中，以及画布近似显示了哪些内容，例如没有设定大小的节点、带格式的标签，或画布没有的 Mermaid 形状。

TikZ 的行为不同。说明里会点出画布没有建模的 TikZ 命令，而在画布上编辑会根据绘图重写 TikZ，所以这些命令会丢失。手写的或复杂的 TikZ 请留在代码模式中处理。

## 预览结果

**编译** 会在画布旁边的预览窗格中，脱离你的文档单独渲染图表。可以选择 1x、2x 或 3x 的 PNG 缩放，以及背景色或透明背景。

- TikZ 用 Tectonic 在单独的构建中编译，所以写了一半的图表绝不会影响你的文档。
- Typst 预览使用已打开的 Typst 项目自己的 Typst 版本和包缓存；没有打开 Typst 项目时，则使用内置的 Typst。第一次 Typst 预览会从 Typst Universe 下载 fletcher。在离线模式下或没有网络连接时，预览会提示缺少该包，而不是显示笼统的错误。
- Mermaid 使用应用自带的 Mermaid 渲染器预览。

错误会显示在预览窗格中。对于 Typst 和 Mermaid，每个错误都会指出它在代码中的行号，点击即可跳转过去。

如果编译失败，**用 AI 修复** 会把代码及其错误发送给你已连接的 AI 提供商，并请求返回同一语言的修正后代码。

## 插入、保存和下载

先编译，再打开 **编译** 旁边的 **保存** 菜单：

- **以 TikZ 插入**、**以 Typst 插入** 或 **以 Mermaid 插入** 会把图表放在已打开的 `.tex`、`.typ` 或 Markdown 文档的光标处，使用该文档的语言。如果编排器设置的是另一种语言，绘图会先经由画布转换，所以画布无法显示的代码不会带过去。
- **保存到项目** 会把 `figures/<name>.png` 和源码 `figures/<name>.tikz`、`.typ` 或 `.mmd` 写入你从列表中选的项目。保存到使用另一种语言的项目时，会把绘图转换成该项目的语言。覆盖已存在的文件前，Oleafly 会先询问。用 `#include` 把保存的 Typst 图表添加到文档中，Mermaid 图表则放进 `mermaid` 代码块中。
- **保存到项目 → 新建项目** 会用编排器的语言创建一个图表项目。
- **保存图片** 会把 PNG 及其源码保存在 Oleafly 的图片缓存中，不属于任何项目。

**下载** 菜单可以保存 PNG、Typst 和 Mermaid 图表的 SVG，或保存源码，格式为 **TikZ (.tikz)**、**Typst (.typ)** 或 **Mermaid (.mmd)**。下载另一种语言时，会经由画布转换绘图。

![为 Markdown 笔记本编写 Mermaid 流程图并预览。](https://cdn.oleafly.com/images/gifs/desktop/mermaid-composer.gif?v=2)

## Markdown 文档中的 Mermaid

插入到 Markdown 文档时，会添加一个围栏式的 `mermaid` 代码块，Markdown 预览会把它画出来。PDF 需要图片，所以编排器还会把渲染好的 PNG 保存到 `figures/mermaid-<hash>.png`，Markdown 编译会用这张图片替换代码块。因此图表也会出现在编译好的 PDF 中。如果之后你手动编辑了这个代码块，PDF 会显示代码，直到你再次从编排器插入或保存图表。

## 重新打开和导入图表

编排器保存的源文件末尾有一行注释，里面记录着画布模型。导入这样的文件后，绘图会完全恢复成你离开时的样子。

标题栏中的 **导入图表文件** 会打开一个 `.tikz`、`.tex`、`.typ`、`.mmd` 或 `.md` 文件，并替换当前的草稿。如果文件使用另一种语言，编排器会切换到该语言。画布能读懂的代码会被绘制出来；其他内容则只作为代码打开。

## 图表项目

一个图表项目只包含一幅图。可以用 **保存到项目 → 新建项目** 创建三种语言中任意一种的项目。Typst 图表项目有一个独立的 `main.typ`，页面大小与绘图一致，所以编译它就会得到图表 PDF。

打开项目的主文件，把编辑器工具栏从 **代码** 切换到 **画布**（TikZ）或 **可视化**（Typst 和 Markdown），就能在同一块画布上编辑它。

**Diagram / Figure** 模板（TikZ）和 **Typst Figure** 模板也会启动只含一幅图的项目，以源码形式编写。这类项目的预览就是图片本身，它们的[导出菜单](/docs/export/)提供 **导出为 PDF（矢量图）** 和 **导出为 PNG**。把它们用于在多篇论文中复用的图片。
