# 用 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. 將它命名為 **「Measurement note」**，並開啟 `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)。