# Typst şablonları için formlar

Kendi Typst işlevlerinize bir form verin; böylece bir rapor dolduran kişiler Görsel kipte işlev çağrısı sözdizimi yerine etiketli alanlar görsün.

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:

```toml
[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:

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

## 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](/docs/typst/)).