Форми для шаблонів Typst

Шаблон Typst часто постачається з власними функціями: титульна сторінка, інформаційний блок, блок підписів. Той, хто пише звіт, викликає їх так: #info-box(title: "Supply risk", tone: "risk")[...]. Якщо ви супроводжуєте шаблон, ви можете один раз описати аргументи кожної функції. Тоді візуальний режим показує кожен виклик цієї функції як форму: підписані поля, список для фіксованих варіантів, перемикач для «так» чи «ні». Редагування поля переписує у файлі .typ лише цей один аргумент, тож звіт лишається звичайним кодом Typst, який компілюється так само.

Що бачить користувач

Виклик, що займає окремі рядки, стає карткою. Заголовок картки показує назву форми та, якщо ви її задасте, короткий підсумок, наприклад заголовок блоку. Кожен аргумент отримує рядок із підписом і елементом керування.

Виклик усередині речення, наприклад #badge("review"), стає чипом у рядку тексту. Клацання чипа відкриває ті самі поля в невеликому спливному вікні.

Текстові поля та поля розмітки зберігаються, коли ви натискаєте Enter (⌘ Enter або Ctrl Enter у багаторядковому полі) або залишаєте поле. Esc повертає старе значення. Списки та перемикачі зберігаються одразу. Кожна зміна є одним кроком скасування.

Якщо перемістити курсор у виклик, з’являється його код, як і в будь-якого іншого елемента візуального режиму. Редагувати в коді на картці робить те саме.

Де оголошувати форми

Є два місця, формат однаковий:

• У пакеті. Додайте розділ [tool.oleafly] до typst.toml пакета. Typst резервує розділи [tool.*] для інших інструментів, тож пакет, як і раніше, встановлюється й компілюється всюди. Це працює для пакетів @local і для пакетів @preview з Typst Universe.
• У проєкті. Для шаблонів, що лежать у проєкті звичайними файлами .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-forms.toml або typst.toml скопійованого в проєкт пакета в Oleafly, і кожна проблема з’явиться позначкою на своєму рядку: невідомий вид, відсутній підпис, дубльована форма, module поза проєктом. Зламана форма пропускається, а решта працює далі. Файл більший за 256 KB не читається.

Поширення шаблонів

Oleafly читає форми пакетів із тих самих тек, що й компілятор. Співавтор, у якого немає пакета @local, бачить звичайний код і жодних помилок. Щоб поділитися формами з усіма в проєкті, відкрийте діалог Пакети Typst, увімкніть Використовувати пакети з папки проєкту і виберіть Скопіювати пакети в проєкт. Пакет і його форми тоді подорожують у теці проєкту typst-packages (див. Проєкти Typst).