İçeriğe geç
biticaretgeliştiriciler

Uygulamalar

Yönetim paneli sayfasında boş, hata ve yükleniyor durumları

Gömülü uygulama sayfasının boş liste, yüklenemeyen sayfa ve bekleme durumlarını yönetim panelinin kendi sayfalarıyla aynı görünüm ve sözcüklerle gösterin.

Yönetim paneline gömülü sayfanız (Yönetim panelinde sayfa gösterin) üç durumu panelin kendi sayfaları gibi göstermelidir: henüz hiçbir şeyin olmadığı liste, yüklenemeyen sayfa ve beklerken dönen gösterge. app-page.js her üçü için hazır yapı taşları sunar; bunları kullandığınızda sayfanız panelin geri kalanıyla aynı görünür ve aynı sözcüklerle konuşur.

Hangisini ne zaman gösterin

Durum Ne zaman Nasıl
Boş İstek başarılı, ama listede kayıt yok. empty(…) ya da <bt-empty-state>
Hata Sayfanın ilk yüklemesi başarısız oldu ya da 15 saniyede bitmedi. load(…) kendiliğinden, ya da showError(…)
Yükleniyor İlk yükleme sürerken. load(…) kendiliğinden

Boş liste bir hata değildir: API'niz 200 ve boş bir liste döndürüyorsa boş durumu gösterin. Hata durumu yalnızca sayfanın ilk yüklemesi içindir; bir düğmeye basıldıktan sonra başarısız olan işlemi (kaydetme, silme) toast ile bildirin. İlk yükleme başarısız olduğunda toast göstermeyin: sayfada tek bir hata durumu yeterlidir.

Sözcükler

  • Boş: başlık "Henüz … yok" (Henüz değerlendirme yok), altında listenin ne işe yaradığını anlatan tek bir cümle (Müşterilerin yazdığı değerlendirmeler burada görünür.) ve varsa birincil eylem (Dosya yükle, Hesap ekle); bir şey ekleyen eylem artı simgesini (plus) taşır. Aramaya uyan kayıt yoksa başlık "Aramanıza uyan … yok" olur.
  • Hata: başlık "Sayfa yüklenemedi" ya da "… yüklenemedi", altında nedeni (API'nizin Türkçe message alanı, bağlantı kurulamadıysa Bağlantı kurulamadı.) ve "Yeniden dene" düğmesi. İngilizce tarayıcı hatalarını (Failed to fetch) ve "Bir hata oluştu." gibi belirsiz cümleleri göstermeyin.

JavaScript

load(main, başlık, yükleyici, çiz, seçenekler) sayfanın ilk yüklemesini yürütür: önce yükleniyor göstergesini çizer, yükleyici()'nin döndürdüğü promise'i bekler ve gelen veriyle çiz(veri)'yi çağırır. Promise reddedilirse ya da 15 saniyede sonuçlanmazsa göstergenin yerine hata durumu gelir; hata durumundaki "Yeniden dene" yüklemeyi baştan çalıştırır. Gösterge hiçbir zaman sonsuza kadar dönmez. seçenekler.back ({content, onAction}) hata durumuna ikinci bir düğme ekler.

js
var P = biticaretAppPage
var app = biticaretAppBridge.createApp({ hostOrigin: document.body.dataset.host })
var main = document.getElementById('app')

function getJSON(path) {
  return app.fetch(path).then(function (res) {
    return res.json().then(
      function (data) {
        if (!res.ok) throw new Error(data.message || P.unexpectedAnswer)
        return data
      },
      function () {
        throw new Error(P.unexpectedAnswer)
      }
    )
  })
}

P.load(main, 'Dosyalar', function () { return getJSON('/admin/api/files') }, function (data) {
  if (data.files.length === 0) {
    return P.show(main, 'Dosyalar', P.empty({
      icon: 'upload',
      heading: 'Henüz dosya yok',
      body: 'Yüklediğiniz dosyalar burada görünür.',
      action: { content: 'Dosya yükle', icon: 'plus', onAction: openUpload },
    }))
  }
  P.show(main, 'Dosyalar', P.card({ title: 'Dosyalar' }, P.list(data.files.map(function (f) { return f.name }))))
})
Yapı taşı İşlevi
empty({icon, heading, body, action, secondaryAction, inline}) Kendi kartı içinde boş durum. Her eylem {content, icon, onAction} biçimindedir. inline: true, zaten var olan bir kartın içinde küçük bir boş durum çizer.
load(main, title, loader, draw, {back}) İlk yükleme: gösterge, sonra çizim ya da hata durumu (15 saniye sınırıyla).
showError(main, {title, heading, message, error, retry, back}) Hata durumunu kendiniz çizmek için: heading (varsayılan "Sayfa yüklenemedi"), message ya da error'dan çıkan neden, retry için "Yeniden dene".
errorMessage(err) Bir hatanın Türkçe nedeni: API'nin mesajı ya da tarayıcının ve App Bridge'in İngilizce hataları için Bağlantı kurulamadı.
unexpectedAnswer API'niz mesajsız ya da JSON olmayan bir yanıt verdiğinde gösterilecek cümle.
loading(label) Yalnızca göstergeyi çizer; ilk yükleme için load kullanın.

Sayfa betiğiniz kendi göstergesini (bt-spinner), kendi "Bir hata oluştu." kartını ya da bt-empty-state dışında bir "Henüz … yok" paragrafını çizmemelidir.

Go şablonu

Sunucuda çizilen sayfalarda aynı durumları design system öğeleriyle yazın. Boş liste:

html
{{if .Rows}}
  <bt-data-table accessibility-label="Ödemeler">…</bt-data-table>
{{else}}
  <bt-card>
    <bt-empty-state icon="orders" heading="Henüz ödeme yok" action-content="Ödeme bağlantısı oluştur" action-icon="plus" action-url="/admin/links/new">Onaylanan ödemeler burada görünür.</bt-empty-state>
  </bt-card>
{{end}}

Verisi alınamayan sayfa, panelin kritik uyarısıyla (bt-banner, tone="critical"); "Yeniden dene" aynı sayfayı yeniden açar:

html
{{if .LoadError}}
  <bt-banner tone="critical" title="Sayfa yüklenemedi" action-content="Yeniden dene" action-url="{{.Path}}">{{.LoadError}}</bt-banner>
{{end}}

Yönetim panelinin kendi yedeği

Yönetim paneli, uygulamanın çerçevesinin App Bridge üzerinden yanıt vermesini 15 saniye bekler. app-bridge.js, createApp çağrıldığı anda bir el sıkışma mesajı (APP_READY) gönderir; daha eski bir kitaplık sürümünde çerçeveden gelen herhangi bir App Bridge mesajı aynı işi görür. 15 saniye içinde hiçbir mesaj gelmezse (uygulamanın sunucusu kapalıysa, sayfa açılmıyorsa ya da createApp hiç çağrılmıyorsa) panel çerçevenin yerine kendi boş durumunu gösterir: "Uygulama yanıt vermiyor", çerçeveyi yeniden yükleyen "Yeniden dene" düğmesi ve Uygulamalar altındaki uygulama sayfasının bağlantısı. Bu yüzden createApp'ı sayfanın başında, verinizi beklemeden çağırın.