Typst 範本的表單

Typst 範本常常隨附自己的函式：封面、資訊方塊、簽核區塊。撰寫報告的人會呼叫它們，例如 #info-box(title: "Supply risk", tone: "risk")[...]。如果你負責維護範本，只要把每個函式的引數描述一次。視覺化模式接著會把對該函式的每一次呼叫顯示成一份表單：有標籤的欄位、供固定選項使用的清單、供是或否使用的開關。編輯欄位時，只會改寫 .typ 檔案中的那一個引數，所以報告仍是一般的 Typst 原始碼，編譯方式完全相同。

讀者看到什麼

獨占數行的呼叫會變成一張卡片。卡片的標題列會顯示表單的名稱，如果你指定了摘要，還會顯示簡短的摘要，例如方塊的標題。每個引數都有一列，包含它的標籤和一個控制項。

句子中間的呼叫，例如 #badge("review")，會在文字行中變成一個行內標籤。按一下行內標籤，會在小型浮出視窗中開啟相同的欄位。

文字欄位和標記欄位會在你按 Enter（多行欄位中是 ⌘ Enter 或 Ctrl Enter）或離開欄位時儲存。Esc 會把舊的值放回去。清單和開關會立即儲存。每次變更都是一個復原步驟。

把游標移進呼叫中，就會顯示它的原始碼，和視覺化模式中的其他元素一樣。卡片上的在原始碼中編輯也有相同的效果。

在哪裡宣告表單

有兩個地方，格式相同：

• 在套件中。 在套件的 typst.toml 加入 [tool.oleafly] 區段。Typst 把 [tool.*] 區段留給其他工具使用，所以套件仍然可以在任何地方安裝與編譯。這適用於 @local 套件，也適用於來自 Typst Universe 的 @preview 套件。
• 在專案中。 對於以一般 .typ 檔案保存在專案內的範本，請在專案根目錄建立 oleafly-forms.toml。每個表單還要用 module 指明定義該函式的檔案。

套件的表單：

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
function = "info-box"
label = "Info box"
summary = "title"

  [[tool.oleafly.forms.fields]]
  arg = "title"
  kind = "text"
  label = "Heading"
  placeholder = "Short heading"
  required = true

  [[tool.oleafly.forms.fields]]
  arg = "tone"
  kind = "choice"
  label = "Tone"
  default = "note"
  options = [{ value = "note", label = "Note" }, { value = "risk", label = "Risk" }, "neutral"]

  [[tool.oleafly.forms.fields]]
  arg = 0
  kind = "content"
  label = "Text"

專案的表單，寫在 oleafly-forms.toml 中：

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
module = "template/memo.typ"
function = "memo-header"
label = "Memo header"
fields = [
  { arg = "to", kind = "text", label = "To" },
  { arg = "subject", kind = "text", label = "Subject" },
]

各個鍵

schema = 1 是必要的。沒有它，或帶有其他數字的檔案，會被忽略。

每個 [[tool.oleafly.forms]] 項目有：

鍵	必要	意義
function	是	函式的名稱，是單一個 Typst 識別字。可以使用連字號。
module	僅限 oleafly-forms.toml	定義該函式的專案檔案，相對於專案根目錄，資料夾之間用 / 分隔。
label	否	表單在卡片和行內標籤上的名稱。預設為函式的名稱。
summary	否	其值會顯示在標籤旁邊的引數，寫法與欄位的 arg 相同。
fields	是	一個或多個欄位。

每個欄位有：

鍵	必要	意義
arg	是	具名引數用名稱（"title"），位置引數用數字（0 是第一個）。結尾的 [...] 區塊算作排在括號內引數之後的位置引數。
kind	是	text、content、choice、number 或 toggle。
label	是	欄位的標籤。
help	否	欄位下方的簡短說明。
placeholder	否	空欄位中的灰色文字。
required	否	true 會把空欄位標示為缺少，並隱藏它的清除按鈕。Oleafly 絕不會自己加入該引數。
default	否	引數被省略時，你的函式所使用的值。它只會顯示，絕不會寫入。

種類與它們額外的鍵：

• text 寫出 Typst 字串。加上 multiline = true 可得到較大的輸入框。
• content 編輯 Typst 標記，並把它寫成 [...] 區塊。字串引數仍然是字串。
• choice 需要 options：字串清單，或在標籤與值不同時使用 { value, label } 表。值會以字串寫出。
• number 接受 integer、min、max 和 step。數字沒有單位。
• toggle 寫出 true 或 false。

哪些呼叫會有表單

Oleafly 會依循報告中位於檔案最上層、屬於報告自己的 #import 和 #let 行：

• #import "@local/acme-report:0.1.0" as acme 會讓 #acme.info-box(...) 成為表單。
• #import "@local/acme-report:0.1.0": info-box, status-badge as badge 會讓 #info-box(...) 和 #badge(...) 成為表單。
• #import "@local/acme-report:0.1.0": * 會讓套件宣告了表單的每個函式都有表單。
• #import "template/memo.typ": memo-header 會對應到 module 為 template/memo.typ 的專案表單。路徑從報告自己的資料夾讀取，以 / 開頭時則從專案根目錄讀取。

套件版本必須完全相符。檔案中較後面的同名 #let，會從該處起取代這個表單。透過另一個重新匯入該套件的檔案而到達的呼叫，會保持它們的原始文字。

函式的名稱若與視覺化模式已經繪製的 Typst 元素相同，例如 table 或 figure，以單純的名稱呼叫時會保持內建的外觀。#acme.table(...) 或重新命名的匯入則仍會得到表單。

以唯讀顯示的欄位

有些引數無法從表單安全地編輯。它們的那一列會顯示原始碼和原因，而在原始碼中編輯會跳到該處：

• 在原始碼中計算而得：值是運算式，例如 title: data.title。
• 以其他類型的值撰寫：例如表單預期文字的地方卻是數字。
• 不在可選項目之內：你的 options 沒有列出的值。
• 由展開引數設定：帶有 ..args 的呼叫會傳入表單看不到的值，所以每個欄位都是唯讀。

當欄位無法加在它應該放的位置時，例如排在缺少的引數之後的位置引數，表單會這樣告訴你，並提供在原始碼中新增。

定義中的錯誤

在 Oleafly 中開啟 oleafly-forms.toml，或複製進專案的套件的 typst.toml，每個問題都會在它所在的那一行顯示成標記：未知的種類、缺少的標籤、重複的表單、位於專案之外的 module。有問題的表單會被略過，其他表單仍可運作。大於 256 KB 的檔案不會被讀取。

分享範本

Oleafly 會從編譯器使用的同一批資料夾讀取套件表單。沒有 @local 套件的共同作者只會看到一般的原始碼，不會有錯誤。若要與專案中的每個人共用表單，請開啟Typst 套件對話方塊，開啟使用專案資料夾中的套件，並選擇將套件複製到專案。套件及其表單接著會隨專案的 typst-packages 資料夾一起傳遞（請參閱 Typst 專案）。