Tur
Kullanıcıyı sayfanın önemli bölümlerinde adım adım gezdirir. Her adımda bir öğe öne çıkar, ekranın geri kalanı kararır ve öğenin yanında başlık, açıklama, adım sayacı ile Geri / İleri düğmelerini taşıyan küçük bir balon açılır. İlk girişte panelin tanıtımı ya da yeni bir özelliğin gösterilmesi için uygundur.
Temel kullanım
Her turun benzersiz bir name değeri vardır. steps dizisindeki her adım bir target (CSS seçicisi), bir title ve bir text alır. Bileşenin içine koyduğunuz içerik turun kapsamındadır; oradaki bir düğme start() ile turu başlatır. Son adımda "İleri" yerine "Bitir" görünür.
<acun:tour name="siparis-turu" :steps="[
['target' => '#siparis-arama', 'title' => 'Sipariş arama', 'text' => 'Siparişleri numara, müşteri adı ya da telefonla bulun.'],
['target' => '#siparis-ekle', 'title' => 'Yeni sipariş', 'text' => 'Telefonla gelen bir siparişi buradan kaydedin.'],
['target' => '#siparis-ozet', 'title' => 'Aylık özet', 'text' => 'Bu ayki kargoları ve bekleyen iadeleri buradan izleyin.', 'placement' => 'top'],
]">
<acun:button variant="white" x-on:click="start()">Turu başlat</acun:button>
</acun:tour>
<div class="mt-6 space-y-4">
<div class="flex flex-wrap items-center gap-3">
<div id="siparis-arama" class="w-64"><acun:input name="ara" placeholder="Sipariş ara…" /></div>
<acun:button id="siparis-ekle">Yeni sipariş</acun:button>
</div>
<div id="siparis-ozet" class="grid grid-cols-2 gap-3">
<acun:stat-card label="Bu ay kargolanan" value="148" />
<acun:stat-card label="Bekleyen iade" value="23" />
</div>
</div>| Prop | Değerler |
|---|---|
name | Benzersiz ad (zorunlu) |
steps | [['target' => '#seçici', 'title' => …, 'text' => …], …] |
start() | Bileşenin içinden turu başlatır |
Konum
placement balonun hedefin hangi yanında açılacağını seçer; varsayılan bottom. Seçilen yanda yer yoksa balon önce karşı yana, o da olmazsa diğer iki yana geçer ve ekrandan taşmayacak şekilde kaydırılır. Son adım bunu gösterir: üstte açılmak ister ama düğmenin üstünde yer olmadığı için alta geçer. Bileşendeki placement kendi yönü olmayan adımların varsayılanıdır.
<acun:tour name="konum-turu" :steps="[
['target' => '#konum-siparis', 'title' => 'Sağda', 'text' => 'right: balon sipariş kartının sağında açılır.', 'placement' => 'right'],
['target' => '#konum-kurye', 'title' => 'Solda', 'text' => 'left: balon kurye kartının solunda açılır.', 'placement' => 'left'],
['target' => '#konum-not', 'title' => 'Üstte', 'text' => 'top: balon teslimat notunun üstünde açılır.', 'placement' => 'top'],
['target' => '#konum-baslat', 'title' => 'Yer yoksa', 'text' => 'Bu adım üstte açılmak istedi; orada yer olmadığı için alta geçti.', 'placement' => 'top'],
]">
<acun:button id="konum-baslat" variant="white" x-on:click="start()">Konumları göster</acun:button>
</acun:tour>
<div class="mt-6 flex items-start justify-between gap-6">
<div id="konum-siparis" class="w-40 rounded-sm bg-white p-4 text-sm shadow-sm dark:bg-zinc-900">
<p class="text-xs text-gray-500 dark:text-zinc-400">Sipariş</p>
<p class="font-semibold text-gray-900 dark:text-zinc-100">#10482</p>
</div>
<div id="konum-kurye" class="w-40 rounded-sm bg-white p-4 text-sm shadow-sm dark:bg-zinc-900">
<p class="text-xs text-gray-500 dark:text-zinc-400">Kurye</p>
<p class="font-semibold text-gray-900 dark:text-zinc-100">Mehmet Kaya</p>
</div>
</div>
<p id="konum-not" class="mt-32 rounded-sm bg-white p-4 text-sm shadow-sm dark:bg-zinc-900">Teslimat notu: bina girişi arka sokakta; paket kapıcıya bırakılabilir.</p>| Prop | Değerler |
|---|---|
steps.*.placement | top | bottom | left | right |
placement | Adımların varsayılan yönü; varsayılan bottom |
Her yerden başlatma
Tur, sayfanın herhangi bir yerinden start-tour olayı adıyla gönderilerek başlatılır; düğmenin bileşenin içinde olması gerekmez. target vermeyen adım ekranın ortasında açılır, tura bir karşılamayla başlamak için uygundur. Hedefi sayfada bulunmayan (ya da gizli olan) adım atlanır ve sayaca katılmaz: aşağıdaki turda grafik adımı bu yüzden görünmez, sayaç 3 adım gösterir.
<div class="flex flex-wrap items-center justify-between gap-3">
<h3 class="text-base font-semibold text-gray-900 dark:text-zinc-100">Aylık rapor</h3>
<acun:button variant="ghost" size="sm" x-data x-on:click="$dispatch('start-tour', { name: 'rapor-turu' })">Bu sayfa nasıl kullanılır?</acun:button>
</div>
<div class="mt-4 flex flex-wrap items-center gap-3">
<div id="rapor-donem" class="w-48"><acun:select name="donem" :options="['2026-09' => 'Eylül 2026', '2026-08' => 'Ağustos 2026']" /></div>
<acun:button id="rapor-aktar" variant="white">Excel'e aktar</acun:button>
</div>
<acun:tour name="rapor-turu" :steps="[
['title' => 'Aylık rapor', 'text' => 'Bu sayfa seçtiğiniz ayın satış rakamlarını özetler. Kısaca bakalım.'],
['target' => '#rapor-donem', 'title' => 'Dönem', 'text' => 'Raporun hangi aya ait olduğunu buradan seçin.'],
['target' => '#rapor-grafik', 'title' => 'Haftalık grafik', 'text' => 'Satışların haftalara göre dağılımı.'],
['target' => '#rapor-aktar', 'title' => 'Dışa aktarma', 'text' => 'Seçili dönemin satırlarını Excel dosyası olarak indirin.'],
]" />| Prop | Değerler |
|---|---|
start-tour | $dispatch('start-tour', { name: '…' }) |
steps.*.target | Boş: ortada açılır · bulunamazsa: adım atlanır |
Otomatik başlatma ve hatırlama
autostart turu sayfa yüklenince (görseller dahil) başlatır. remember ile bitirilen ya da atlanan tur bu tarayıcıda bir daha kendiliğinden başlamaz: bilgi localStorage'da acun-tour: ve turun adıyla saklanır (aşağıda acun-tour:ilk-giris). start() ve start-tour bu bilgiye bakmaz, tur her zaman elle yeniden izlenebilir. Otomatik başlatmayı yeniden açmak için anahtarı silin: localStorage.removeItem('acun-tour:ilk-giris'). Tarayıcı depolamaya izin vermezse (ör. bazı gizli pencereler) tur yalnızca hatırlamaz, hata vermez. Bu örnek sayfayı açar açmaz odağı alacağı için burada canlı gösterilmiyor.
<acun:tour name="ilk-giris" autostart remember :steps="[
['title' => 'Hoş geldiniz', 'text' => 'Panelin temel bölümlerini birkaç adımda tanıtalım.'],
['target' => '#ana-menu', 'title' => 'Menü', 'text' => 'Siparişlere, müşterilere ve raporlara buradan ulaşırsınız.', 'placement' => 'right'],
['target' => '#bildirimler', 'title' => 'Bildirimler', 'text' => 'Size atanan destek talepleri burada listelenir.'],
]" />
{{-- Hatırlanmış olsa da elle başlatılabilir. --}}
<acun:button variant="ghost" x-data x-on:click="$dispatch('start-tour', { name: 'ilk-giris' })">Tanıtımı yeniden izle</acun:button>| Prop | Değerler |
|---|---|
autostart | true | false |
remember | true | false · anahtar: 'acun-tour:' + name |
Livewire ile
Sunucudan start-tour olayını gönderin. Tur bitince ya da atlanınca tour-ended olayı { name, finished } ile yayılır (finished atlanınca false); bunu dinleyerek turun görüldüğünü kullanıcı kaydına yazabilir, autostart değerini de bu kayda bağlayabilirsiniz. Böylece tur tarayıcı değişse de tekrar açılmaz. Bileşene verdiğiniz x-on: gibi ek nitelikler kök öğeye eklenir.
// <acun:tour
// name="ilk-giris"
// :steps="$turAdimlari"
// :autostart="! auth()->user()->tur_goruldu"
// x-on:tour-ended.window="$event.detail.name === 'ilk-giris' && $wire.turuGorulduSay()"
// />
public function turuGorulduSay(): void
{
auth()->user()->forceFill(['tur_goruldu' => true])->save();
}
public function yardimGoster(): void
{
$this->dispatch('start-tour', name: 'ilk-giris');
}| Prop | Değerler |
|---|---|
tour-ended | { name, finished } · finished: false = atlandı |
Klavye ve erişilebilirlik
Tur yalnızca klavyeyle kullanılabilir. Her adımda odak balona geçer; ekran okuyucu başlığı, açıklamayı ve sayacı okur. Tab ve Shift+Tab balonun düğmeleri arasında döner, → sonraki, ← önceki adıma geçer, Esc turu bitirir (atlanmış sayılır). Tur kapanınca odak turu başlatan öğeye geri döner. Balon role="dialog" ve aria-modal="true" taşır; adını başlıktan, açıklamasını metin ile sayaçtan alır. Tur açıkken arkadaki sayfa tıklanmaz. İşletim sistemi azaltılmış hareket istiyorsa sayfa hedefe animasyonsuz kaydırılır. Düğme metinleri (Geri, İleri, Bitir, Turu atla) ve sayaç biçimi (:current / :total) __() ile çevrilir.
<acun:tour name="form-turu" :steps="[
['target' => '#musteri-ad', 'title' => 'Ad soyad', 'text' => 'Müşterinin faturada görünecek adını yazın.'],
['target' => '#musteri-telefon', 'title' => 'Telefon', 'text' => 'Kuryenin ulaşabileceği bir cep telefonu numarası girin.'],
['target' => '#musteri-kaydet', 'title' => 'Kaydet', 'text' => 'Kaydedilen müşteri, müşteri listesine düşer.', 'placement' => 'right'],
]">
<acun:button variant="white" x-on:click="start()">Formu tanıt</acun:button>
</acun:tour>
<div class="mt-6 max-w-sm space-y-4">
<div id="musteri-ad"><acun:input name="ad" label="Ad soyad" /></div>
<div id="musteri-telefon"><acun:input name="telefon" type="tel" label="Telefon" /></div>
<acun:button id="musteri-kaydet">Kaydet</acun:button>
</div>| Prop | Değerler |
|---|---|
Tab / Shift+Tab | Balonun düğmeleri arasında |
→ / ← | Sonraki / önceki adım |
Esc | Turu bitirir |
Prop'lar ve slot'lar
Bileşenin kabul ettiği değerler.
| Prop | Varsayılan | Açıklama |
|---|---|---|
name | — | Zorunlu. start-tour olayındaki ad; hatırlama anahtarı da bundan üretilir |
steps | [] | Adımlar dizisi; her adım target, title, text ve isteğe bağlı placement alır |
placement | bottom | Kendi yönü olmayan adımlar için: top · bottom · left · right |
autostart | false | Sayfa yüklenince başlar |
remember | false | Bitirilen ya da atlanan tur bu tarayıcıda yeniden kendiliğinden başlamaz (localStorage: 'acun-tour:' + name) |
steps.*.target | null | Hedefin CSS seçicisi. Boşsa balon ekranın ortasında açılır; öğe bulunamaz ya da gizliyse adım atlanır |
steps.*.title | '' | Balonun başlığı; aynı zamanda pencerenin erişilebilir adı |
steps.*.text | '' | Açıklama; düz metin olarak yazılır (HTML işlenmez) |
steps.*.placement | bottom | top · bottom · left · right; yer yoksa başka yana geçer ve ekranın içinde kalır |