Biểu mẫu cho mẫu Typst

Một mẫu Typst thường đi kèm các hàm riêng: một trang bìa, một hộp thông tin, một khối ký duyệt. Người viết báo cáo gọi chúng, như trong #info-box(title: "Supply risk", tone: "risk")[...]. Nếu bạn duy trì mẫu, bạn có thể mô tả các đối số của mỗi hàm một lần. Khi đó chế độ Visual hiển thị mỗi lời gọi tới hàm đó dưới dạng một biểu mẫu: các trường có nhãn, một danh sách cho các lựa chọn cố định, một công tắc cho có hoặc không. Chỉnh sửa một trường chỉ viết lại đúng một đối số đó trong tệp .typ, nên báo cáo vẫn là mã nguồn Typst thông thường và biên dịch theo cùng cách.

Người đọc thấy gì

Một lời gọi nằm riêng trên các dòng của nó trở thành một thẻ. Phần đầu thẻ hiển thị tên của biểu mẫu và, nếu bạn chọn, một dòng tóm tắt ngắn như tiêu đề của hộp. Mỗi đối số có một hàng với nhãn và một điều khiển.

Một lời gọi nằm trong một câu, như #badge("review"), trở thành một chip trong dòng văn bản. Nhấp vào chip sẽ mở cùng các trường đó trong một popover nhỏ.

Các trường văn bản và trường markup lưu khi bạn nhấn Enter (⌘ Enter hoặc Ctrl Enter trong trường nhiều dòng) hoặc rời khỏi trường. Esc trả lại giá trị cũ. Danh sách và công tắc lưu ngay lập tức. Mỗi thay đổi là một bước hoàn tác.

Di chuyển con trỏ vào một lời gọi sẽ hiển thị mã nguồn của nó, giống mọi thành phần khác của chế độ Visual. Edit in source trên thẻ cũng làm điều tương tự.

Nơi khai báo biểu mẫu

Có hai nơi, cùng một định dạng:

• Trong một gói. Thêm một mục [tool.oleafly] vào typst.toml của gói. Typst dành các mục [tool.*] cho các công cụ khác, nên gói vẫn cài đặt và biên dịch được ở mọi nơi. Cách này dùng được cho các gói @local và cho các gói @preview từ Typst Universe.
• Trong dự án. Với các mẫu được giữ dưới dạng tệp .typ thường bên trong dự án, hãy tạo oleafly-forms.toml ở thư mục gốc dự án. Mỗi biểu mẫu cũng nêu tên tệp định nghĩa hàm, bằng module.

Một biểu mẫu trong gói:

[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"

Một biểu mẫu trong dự án, trong 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" },
]

Các khóa

schema = 1 là bắt buộc. Một tệp không có nó, hoặc có số khác, sẽ bị bỏ qua.

Mỗi mục [[tool.oleafly.forms]] có:

Khóa	Bắt buộc	Ý nghĩa
function	Có	Tên của hàm, dưới dạng một định danh Typst. Dấu gạch nối được phép.
module	Chỉ trong oleafly-forms.toml	Tệp dự án định nghĩa hàm, tính từ thư mục gốc dự án, với / giữa các thư mục.
label	Không	Tên của biểu mẫu trên thẻ và chip. Mặc định là tên của hàm.
summary	Không	Đối số có giá trị hiển thị cạnh nhãn, viết giống arg của một trường.
fields	Có	Một hoặc nhiều trường.

Mỗi trường có:

Khóa	Bắt buộc	Ý nghĩa
arg	Có	Tên của một đối số có tên ("title"), hoặc một số cho đối số theo vị trí (0 là đối số đầu tiên). Một khối [...] ở cuối được tính là đối số theo vị trí đứng sau những đối số trong ngoặc tròn.
kind	Có	text, content, choice, number hoặc toggle.
label	Có	Nhãn của trường.
help	Không	Một ghi chú ngắn dưới trường.
placeholder	Không	Chữ xám trong một trường trống.
required	Không	true đánh dấu một trường trống là còn thiếu và ẩn nút Clear của nó. Oleafly không bao giờ tự thêm đối số.
default	Không	Giá trị mà hàm của bạn dùng khi đối số bị bỏ qua. Nó được hiển thị, không bao giờ được ghi.

Các loại trường và khóa bổ sung của chúng:

• text ghi một chuỗi Typst. Thêm multiline = true để có ô lớn hơn.
• content chỉnh sửa markup Typst và ghi nó dưới dạng một khối [...]. Một đối số chuỗi vẫn là chuỗi.
• choice cần options: một danh sách chuỗi, hoặc các bảng { value, label } khi nhãn khác với giá trị. Giá trị được ghi dưới dạng chuỗi.
• number nhận integer, min, max và step. Số không có đơn vị.
• toggle ghi true hoặc false.

Những lời gọi nào có biểu mẫu

Oleafly đi theo các dòng #import và #let của chính báo cáo ở cấp cao nhất của tệp:

• #import "@local/acme-report:0.1.0" as acme biến #acme.info-box(...) thành một biểu mẫu.
• #import "@local/acme-report:0.1.0": info-box, status-badge as badge biến #info-box(...) và #badge(...) thành các biểu mẫu.
• #import "@local/acme-report:0.1.0": * khiến mọi hàm mà gói khai báo biểu mẫu cho đều trở thành biểu mẫu.
• #import "template/memo.typ": memo-header khớp với một biểu mẫu dự án có module là template/memo.typ. Đường dẫn được đọc từ thư mục của chính báo cáo, hoặc từ thư mục gốc dự án khi chúng bắt đầu bằng /.

Phiên bản gói phải khớp chính xác. Một #let cùng tên, ở phần sau của tệp, thay thế biểu mẫu từ điểm đó trở đi. Các lời gọi đi qua một tệp khác nhập lại gói vẫn giữ nguyên văn bản nguồn.

Một hàm được đặt tên giống một thành phần Typst mà chế độ Visual đã vẽ sẵn, chẳng hạn table hoặc figure, giữ giao diện có sẵn khi được gọi bằng tên trần. #acme.table(...) hoặc một import đã đổi tên vẫn có biểu mẫu.

Các trường chỉ đọc

Một số đối số không thể chỉnh sửa an toàn từ một biểu mẫu. Hàng của chúng hiển thị mã nguồn kèm lý do, và Edit in source nhảy tới đó:

• Computed in the source: giá trị là một biểu thức, chẳng hạn title: data.title.
• Written as a different kind of value: ví dụ một số ở nơi biểu mẫu mong đợi văn bản.
• Not one of the choices: một giá trị mà options của bạn không liệt kê.
• Được đặt bởi một đối số spread: một lời gọi có ..args truyền vào những giá trị mà biểu mẫu không thấy, nên mọi trường đều chỉ đọc.

Khi một trường không thể được thêm vào vị trí của nó, chẳng hạn một đối số theo vị trí đứng sau một đối số còn thiếu, biểu mẫu sẽ báo điều đó và đưa ra Add in source.

Lỗi trong định nghĩa

Mở oleafly-forms.toml, hoặc typst.toml của một gói đã vendored, trong Oleafly và mỗi vấn đề hiển thị dưới dạng một dấu đánh dấu trên dòng của nó: một loại trường không xác định, một nhãn bị thiếu, một biểu mẫu trùng lặp, một module nằm ngoài dự án. Một biểu mẫu hỏng bị loại ra và các biểu mẫu khác vẫn hoạt động. Một tệp lớn hơn 256 KB sẽ không được đọc.

Chia sẻ mẫu

Oleafly đọc các biểu mẫu của gói từ cùng các thư mục mà trình biên dịch dùng. Một cộng tác viên không có gói @local sẽ thấy mã nguồn thường và không có lỗi. Để chia sẻ biểu mẫu với mọi người trong một dự án, hãy mở hộp thoại Typst packages, bật Use packages from the project folder và chọn Vendor packages into project. Khi đó gói, cùng các biểu mẫu của nó, đi theo trong thư mục typst-packages của dự án (xem Dự án Typst).