Kurulum

Bir kapsayıcı yerleştirin. Hesaplayıcının görünmesini istediğiniz yere data-mo-tool taşıyan bir öğe koyun. Değer, aracın key’idir.
```
<div data-mo-tool="kdv"></div>
```

Yükleyiciyi ekleyin. Sayfada bir kez, tercihen gövdenin sonunda:

<script src="https://api.mirac-ozdemir.com/widget.js" async></script>

Bitti. Sayfa yüklenince yükleyici kapsayıcıyı iframe ile değiştirir.

Kapsayıcının içine bir yedek bağlantı koyabilirsiniz (betik yüklenmezse görünür). Yükleyici kapsayıcının mevcut içeriğini iframe ile değiştirir:

<div data-mo-tool="kdv">
  <a href="https://mirac-ozdemir.com/tr/araclar/kdv-hesaplama">KDV hesaplama aracını açın</a>
</div>

Aynı kapsayıcıyı özel öğe olarak da yazabilirsiniz (<mo-calculator tool="kdv">): Özel öğeler ve SDK. Arama kutusu ve kategori listesi için Widget türleri.

Öznitelikler

Aşağıdaki öznitelikler data-mo-tool (hesaplayıcı) kapsayıcısı içindir. Arama ve kategori widget’larının ek öznitelikleri Widget türleri sayfasındadır.

Öznitelik	Değerler	Varsayılan	Açıklama
`data-mo-tool`	Araç anahtarı: `^[a-z0-9]+(-[a-z0-9]+)*$`, 2–64 karakter	zorunlu	Gömülecek aracın `key`’i.
`data-locale`	`tr`, `en`	`tr`	Arayüz dili. Araç o dilde yayınlanmamışsa widget “bulunamadı” gösterir.
`data-theme`	`auto`, `light`, `dark`, `inherit`	`auto`	`auto` ziyaretçinin sistem temasını izler; `inherit` sizin sayfanızın temasını izler (aşağıya bakın).
`data-header`	`true`/`false` (`1`/`0`, `yes`/`no`)	`true`	`false` araç başlığını gizler; kendi başlığınızı kullanırken işe yarar.
`data-height`	Tamsayı px, 120–10000 arası sıkıştırılır	hatırlanan yükseklik, yoksa `480`	Başlangıç yüksekliği; sonra içeriğe göre otomatik ayarlanır.
`data-accent`	6 onaltılık hane, `#` isteğe bağlı (`0a7d5a`)	site rengi	Birincil renk; üzerindeki yazı rengi parlaklığa göre seçilir.
`data-radius`	`none`, `sm`, `md`, `lg`	`md`	Köşe yuvarlaklığı ölçeği.
`data-density`	`comfortable`, `compact`	`comfortable`	Boşluk ölçeği.
`data-view`	`full`, `result`	`full`	`result` yalnızca sonuç panelini gösterir: Widget türleri.
`data-autorun`	`true`/`false`	`false`	Ön değerler uygulandıktan hemen sonra hesaplar.
`data-input-<alan>`	ön değer (≤ 64 karakter)	yok	Tek bir girdiyi doldurur (aşağıya bakın).
`data-inputs`	JSON nesnesi	yok	Birden çok girdiyi doldurur.
`data-title`	metin (en çok 200 karakter)	yerelleştirilmiş başlık	iframe’in `title` niteliği (erişilebilirlik).
`data-lazy`	`true`/`false`	`true`	`false` iframe’i beklemeden (eager) yükler.

Geçersiz bir değer konsola İngilizce bir console.warn ile yazılır ve o kapsayıcı atlanır (örn. [MiracOzdemirWidget] Invalid data-locale value: "de" (expected one of: tr, en)). Değerler katı izin listeleriyle doğrulanır; seçenekleri başka yerden dinamik olarak üretiyorsanız bu davranışı bilin.

Ön değerler ve otomatik hesaplama

Formu açılışta doldurmak için data-input-<alan> öznitelikleri kullanılır. <alan> aracın girdi alanının adıdır (araç tanımındaki alan adı); öznitelikte kebab-case yazılır ve yükleyici camelCase’e çevirir (data-input-vat-rate-option → vatRateOption).

<div
  data-mo-tool="kdv"
  data-input-amount="1000"
  data-input-mode="exclusive"
  data-input-vat-rate-option="standard"
  data-autorun="true"
></div>

Aynısını JSON ile de verebilirsiniz; ikisi birlikte kullanılırsa data-input-* değerleri JSON’dakini ezer:

<div data-mo-tool="kdv" data-inputs='{"amount":"1000","mode":"exclusive"}' data-autorun="true"></div>

Kurallar:

Değerler hesaplama istekleriyle aynı kanonik biçimdedir: ondalıklar string ("1234.56"), mantıksal değerler true/false, seçenekler seçenek anahtarı, tarihler YYYY-MM-DD.
En çok 50 alan, her değer en çok 64 karakter. Alan adı ^[a-z][A-Za-z0-9_]{0,63}$ kuralına uymalıdır.
Bilinmeyen alanlar ve geçersiz değerler sessizce yok sayılır (paylaşım bağlantılarındaki kuralın aynısı); widget yine de açılır.
data-autorun="true" ön değerler uygulandığında hesaplamayı kendiliğinden çalıştırır; mo:result olayı bu hesaplamadan sonra gelir.
Geçersiz bir data-inputs (JSON nesnesi değilse) konsola uyarı yazar ve kapsayıcı atlanır.

Sonradan değer vermek için setInputs kullanın.

Tema: `inherit`

data-theme="inherit" widget’ın temasını sizin sayfanızdan alır. Yükleyici sırayla şunlara bakar: kapsayıcıdan yukarı doğru data-theme, data-bs-theme veya data-color-mode özniteliği (light/dark), dark/theme-dark/dark-mode (veya light/theme-light/light-mode) sınıfı, ardından hesaplanmış color-scheme, en son prefers-color-scheme. Sayfanızın teması çalışma anında değişirse (<html> veya <body> üzerinde bu öznitelikler/sınıflar ya da sistem teması değişince) widget iframe’i yeniden yüklenmeden güncellenir.

Yer tutucu ve yerleşim kayması (CLS)

Yükleyici, iframe yüklenirken kapsayıcıda iskelet (skeleton) bir yer tutucu çizer ve iframe ready olana kadar görünmez tutar; böylece içerik aşağı itilmez. Başlangıç yüksekliği şu sırayla belirlenir: data-height varsa o; yoksa aynı {araç, dil, görünüm} için son ölçülen yükseklik (sizin sitenizin localStorage’ında mo-widget-h:… anahtarıyla, en iyi çaba); o da yoksa 480.

Kayma istemiyorsanız aracın tipik yüksekliğini data-height ile verin.
data-lazy="false" iframe’i hemen yükler (sayfanın üst kısmındaki widget’lar için).
Yükleyici ayrıca sayfaya site origin’ine bir <link rel="preconnect"> ekler; ilk yükleme hızlanır.
Kapsayıcının position değeri static ise yükleyici onu relative yapar (yer tutucu için).

Aynı sayfaya istediğiniz kadar widget ekleyebilirsiniz; yükleyiciyi bir kez eklemek yeterlidir. Betiği yanlışlıkla iki kez eklerseniz ikinci yükleme yalnızca yeniden tarama yapar, çift widget oluşmaz.

<div data-mo-tool="kdv" data-height="520"></div>
<div data-mo-tool="gelir-vergisi-hesaplama" data-theme="dark" data-accent="0a7d5a"></div>
<script src="https://api.mirac-ozdemir.com/widget.js" async></script>

Dinamik içerik ve SPA’lar

Yükleyici sayfa yüklenince bir kez tarar. Sonradan (framework ile, AJAX ile) kapsayıcı eklerseniz window.MiracOzdemirWidget ile mount edin:

container.setAttribute('data-mo-tool', 'kdv');
window.MiracOzdemirWidget.mount(container); // iframe'i döner, geçersizse null

Kapsayıcıyı kaldırmadan önce unmount(container) çağırın. Seçenekleri sonradan değiştirmek için çoğu zaman unmount gerekmez: update. Framework örnekleri: Framework entegrasyonları.

iframe’in nitelikleri

Yükleyici iframe’i şu niteliklerle oluşturur (erişilebilirlik ve güvenlik için):

title: yerelleştirilmiş, örn. Hesaplama araci: kdv (en: Calculator: kdv); data-title verdiyseniz o. iframe ready olunca, data-title yoksa, aracın başlığıyla değiştirilir.
width="100%", loading="lazy" (data-lazy="false" ile eager)
referrerpolicy="strict-origin-when-cross-origin"
sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
Stil: width:100%; border:0; display:block; height:<px>; ready’ye kadar opacity:0

Gereksinimler

Sayfanız HTTPS üzerinde olmalıdır (karma içerik engellenir).
Sayfanızda bir Content-Security-Policy varsa betik ve iframe kaynaklarına izin verin: Güvenlik ve CSP.
Çerez veya kullanıcı kaydı gerekmez.
Betiği sabit bir sürüme ve bütünlük (SRI) denetimine bağlamak isterseniz: Sürüm politikası.