Typst şablonları için formlar

Bir Typst şablonu çoğu zaman kendi işlevleriyle gelir: bir kapak sayfası, bir bilgi kutusu, bir onay bloğu. Raporu yazan kişi bunları #info-box(title: "Supply risk", tone: "risk")[...] gibi çağırır. Şablonu siz sürdürüyorsanız her işlevin bağımsız değişkenlerini bir kez tanımlayabilirsiniz. Görsel kip de o işlevin her çağrısını bir form olarak gösterir: etiketli alanlar, sabit seçenekler için bir liste, evet ya da hayır için bir anahtar. Bir alanı düzenlemek .typ dosyasında yalnızca o tek bağımsız değişkeni yeniden yazar; böylece rapor, aynı şekilde derlenen sıradan Typst kaynağı olarak kalır.

Okuyucunun gördüğü

Kendi satırlarında duran bir çağrı bir kart olur. Kartın başlığı formun adını ve, seçerseniz, kutunun başlığı gibi kısa bir özeti gösterir. Her bağımsız değişkenin etiketi ve bir denetimi olan bir satırı vardır.

Bir cümlenin içindeki bir çağrı, örneğin #badge("review"), metin satırında bir kutucuk olur. Kutucuğa tıklamak aynı alanları küçük bir açılır pencerede açar.

Metin alanları ve işaretleme alanları Enter tuşuna bastığınızda (çok satırlı bir alanda ⌘ Enter ya da Ctrl Enter) ya da alandan çıktığınızda kaydedilir. Esc eski değeri geri koyar. Listeler ve anahtarlar anında kaydedilir. Her değişiklik tek bir geri alma adımıdır.

İmleci bir çağrının içine götürmek, Görsel kipteki diğer öğeler gibi kaynağını gösterir. Kart üzerindeki Kaynakta düzenle de aynısını yapar.

Formlar nerede tanımlanır

İkisi de aynı biçimi kullanan iki yer vardır:

• Bir pakette. Paketin typst.toml dosyasına bir [tool.oleafly] bölümü ekleyin. Typst, [tool.*] bölümlerini başka araçlara ayırır; bu yüzden paket her yerde yine kurulur ve derlenir. Bu, @local paketleri için ve Typst Universe’teki @preview paketleri için çalışır.
• Projede. Proje içinde düz .typ dosyaları olarak tutulan şablonlar için projenin kök dizininde oleafly-forms.toml oluşturun. Her form ayrıca işlevi tanımlayan dosyayı module ile belirtir.

Bir paket formu:

[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 içinde bir proje formu:

[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" },
]

Anahtarlar

schema = 1 zorunludur. Bu satırı içermeyen ya da başka bir sayı içeren bir dosya yok sayılır.

Her [[tool.oleafly.forms]] girdisi şunlara sahiptir:

Anahtar	Zorunlu	Anlamı
function	Evet	İşlevin adı, tek bir Typst tanımlayıcısı olarak. Tireler sorun değildir.
module	Yalnızca oleafly-forms.toml içinde	İşlevi tanımlayan proje dosyası, proje köküne göre, klasörler arasında / ile.
label	Hayır	Formun kartlardaki ve kutucuklardaki adı. Varsayılan olarak işlevin adıdır.
summary	Hayır	Değeri etiketin yanında görünen bağımsız değişken; bir alanın arg değeri gibi yazılır.
fields	Evet	Bir ya da daha fazla alan.

Her alanın şunları vardır:

Anahtar	Zorunlu	Anlamı
arg	Evet	Adlandırılmış bir bağımsız değişken için bir ad ("title") ya da konumsal olan için bir sayı (0 ilkidir). Sondaki bir [...] bloğu, parantez içindekilerden sonra gelen konumsal bir bağımsız değişken sayılır.
kind	Evet	text, content, choice, number veya toggle.
label	Evet	Alanın etiketi.
help	Hayır	Alanın altında kısa bir not.
placeholder	Hayır	Boş bir alandaki gri metin.
required	Hayır	true, boş bir alanı eksik olarak işaretler ve Temizle düğmesini gizler. Oleafly bağımsız değişkeni kendiliğinden asla eklemez.
default	Hayır	İşlevinizin bağımsız değişken atlandığında kullandığı değer. Gösterilir, hiçbir zaman yazılmaz.

Türler ve ek anahtarları:

• text bir Typst dizgisi yazar. Daha büyük bir kutu için multiline = true ekleyin.
• content Typst işaretlemesini düzenler ve bunu bir [...] bloğu olarak yazar. Dizgi olan bir bağımsız değişken dizgi olarak kalır.
• choice için options gerekir: dizgilerden oluşan bir liste ya da etiket değerden farklıysa { value, label } tabloları. Değerler dizgi olarak yazılır.
• number integer, min, max ve step alır. Sayıların birimi yoktur.
• toggle true ya da false yazar.

Hangi çağrılar form alır

Oleafly, raporun kendi #import ve #let satırlarını dosyanın üst düzeyinde izler:

• #import "@local/acme-report:0.1.0" as acme, #acme.info-box(...) çağrısını bir form yapar.
• #import "@local/acme-report:0.1.0": info-box, status-badge as badge, #info-box(...) ve #badge(...) çağrılarını form yapar.
• #import "@local/acme-report:0.1.0": *, paketin form tanımladığı her işlevi bir form yapar.
• #import "template/memo.typ": memo-header, module değeri template/memo.typ olan bir proje formuyla eşleşir. Yollar raporun kendi klasöründen, / ile başlıyorsa proje kökünden okunur.

Paket sürümü tam olarak eşleşmelidir. Dosyada daha aşağıda aynı adla yazılan bir #let, o noktadan itibaren formun yerini alır. Paketi yeniden içe aktaran başka bir dosya üzerinden ulaşılan çağrılar kaynak metinlerini korur.

table ya da figure gibi Görsel kipin zaten çizdiği bir Typst öğesi gibi adlandırılmış bir işlev, yalın adıyla çağrıldığında yerleşik görünümünü korur. #acme.table(...) ya da yeniden adlandırılmış bir içe aktarma yine formu alır.

Salt okunur gösterilen alanlar

Bazı bağımsız değişkenler bir formdan güvenle düzenlenemez. Satırları kaynağı nedeniyle birlikte gösterir ve Kaynakta düzenle oraya atlar:

• Kaynakta hesaplanıyor: değer, title: data.title gibi bir ifadedir.
• Farklı türde bir değer olarak yazılmış: örneğin formun metin beklediği yerde bir sayı.
• Seçeneklerden biri değil: options içinde olmayan bir değer.
• Yayma bağımsız değişkeniyle ayarlanmış: ..args içeren bir çağrı, formun göremediği değerleri geçirir; bu yüzden her alan salt okunurdur.

Bir alan eklenmesi gereken yere eklenemediğinde, örneğin eksik olan bir bağımsız değişkenden sonraki konumsal bir bağımsız değişken, form bunu söyler ve Kaynağa ekle önerir.

Bir tanımdaki hatalar

oleafly-forms.toml dosyasını ya da kopyalanmış bir paketin typst.toml dosyasını Oleafly’de açın; her sorun kendi satırında bir işaret olarak görünür: bilinmeyen bir tür, eksik bir etiket, yinelenen bir form, projenin dışındaki bir module. Bozuk bir form dışarıda bırakılır ve diğerleri çalışmaya devam eder. 256 KB’tan büyük bir dosya okunmaz.

Şablonları paylaşma

Oleafly paket formlarını derleyicinin kullandığı klasörlerden okur. @local pakete sahip olmayan bir iş birlikçi düz kaynak görür ve hata görmez. Formları bir projedeki herkesle paylaşmak için Typst paketleri iletişim kutusunu açın, Proje klasöründeki paketleri kullan’ı açın ve Paketleri projeye kopyala’yı seçin. Paket ve formları o zaman projenin typst-packages klasöründe birlikte taşınır (bkz. Typst projeleri).