Üretilen UI'da Özel Vue Bileşenleri: Yeniden Üretme ile Güvenli Kullanım

Üretilen bir UI düzenlediğinizde ne kırılır?

Üretilen UI'lar tekrar oluşturulmak üzere tasarlanır. AppMaster gibi platformlarda Vue3 web uygulama kodu görsel editörlerden üretilir. Yeniden üretme (regeneration), ekranlar, mantık ve veri modelleri arasındaki tutarlığı sağlar.

Sorun basittir: üretilen dosyaları doğrudan düzenlerseniz, bir sonraki yeniden üretme yaptığınız düzenlemeleri üzerine yazabilir.

Bu yüzden ekipler özel koda yönelir. Yerleşik UI blokları genelde standart formlar ve tabloları karşılar, ama gerçek uygulamalar genelde birkaç özel öğe ister: karmaşık grafikler, harita seçimleri, zengin metin editörleri, imza panoları veya sürükle-bırak planlayıcılar. Bunlar, özel Vue bileşenleri eklemek için geçerli nedenlerdir — yeter ki onları bir eklenti gibi, üretilen dosyaları düzenlemek gibi görmeyin.

Özel kod üretilen kodla karıştığında sorunlar gecikebilir ve kafa karıştırıcı olur. Bir sonraki UI değişikliği yeniden üretmeyi tetikleene kadar veya bir ekip arkadaşı görsel editörde bir ekranı değiştirene kadar fark etmeyebilirsiniz. Yaygın problemler şunlardır:

• Şablon yeniden üretildiği için özel işaretlemeniz kaybolur.
• İçe aktarmalar veya kayıtlar dosya adları ya da yapı değişince bozulur.
• "Küçük bir düzeltme" her dağıtıma birleştirme çatışması götürür.
• Üretilen mantık ve özel mantık birbirinden uzaklaşır, kenar durumlar bozulur.
• Yükseltmeler riskli hissedilir çünkü neyin değişeceğini bilemezsiniz.

Ama hedef özelleştirmeden kaçınmak değil; yeniden oluşturmayı öngörülebilir kılmak. Üretilen ekranlar ile özel widget'lar arasında temiz bir sınır tutarsanız, yeniden üretme rutin bir işlem olur, stresli değil.

Yeniden üretmeyi güvenli kılan bir sınır kuralı

Özelleştirme yapmak ama işinizi kaybetmemek istiyorsanız, bir kuralı takip edin: üretilen dosyaları asla düzenlemeyin. Onları derlenmiş bir çıktı gibi salt-okunur kabul edin.

UI'nızı iki bölge olarak düşünün:

• Üretilen bölge: jeneratör tarafından üretilen sayfalar, düzenler ve ekranlar.
• Özel bölge: ayrı bir klasörde tuttuğunuz elle yazılmış Vue bileşenleri.

Üretilen UI, özel bileşenlerinizi tüketmeli; o bileşenlerin üretildiği yer olmamalı.

Bunu uzun vadede çalışır kılmak için "sınırı" küçük ve net tutun. Bir özel widget küçük bir ürün gibi davranmalı ve bir sözleşmeye sahip olmalı:

• Giren props: sadece görüntülemek için ihtiyaç duyduğu veriler.
• Çıkan eventler: sayfanın tepki vermesi gerekenler.

Widget içinde globale erişmekten veya ilgisiz API'leri çağırmaktan kaçının; sadece sözleşmenin açıkça izin verdiği durumlarda yapın.

AppMaster tarzı üretilen Vue3 ekranlarda bu genellikle üretilen ekranda minimal bağlama (props iletme ve eventleri yakalama) yapmanız anlamına gelir. Bu bağlama yeniden üretmelerde değişebilir, ama küçük ve kolayca tekrar yapılabilir kalır. Gerçek iş özel bölgedeki kodda güvende kalır.

Vue3 ile iyi işleyen izolasyon desenleri

Amaç basit: yeniden üretme üretilen dosyaları serbestçe değiştirebilmeli, sizin widget kodunuz ise dokunulmadan kalmalı.

Pratik yaklaşım, özel widget'ları küçük bir dahili modül olarak tutmaktır: bileşenler, stiller ve yardımcı araçlar tek yerde. Üretilen Vue3 uygulamalarda bu genelde özel kodun üretilen sayfaların dışında yaşaması ve bir bağımlılık olarak içe aktarılması anlamına gelir.

Bir sarmalayıcı (wrapper) bileşen çok yardımcı olur. Sarmalayıcı üretilen uygulamayla konuşur: sayfanın mevcut veri şeklini okur, normalleştirir ve widget'a temiz props verir. Üretilen veri şekli sonra değişirse, genelde widget'ı yeniden yazmak yerine sadece sarmalayıcıyı güncellersiniz.

Aşağıdaki desenler iyi dayanır:

• Widget'ı kara kutu gibi düşünün: props girer, eventler çıkar.
• API cevaplarını, tarihleri ve ID'leri widget-dostu formatlara eşleyen bir wrapper kullanın.
• Stilleri kapsayıcı (scoped) tutun, böylece üretilen sayfalar widget'ınızı istemeden ezemez.
• Üst DOM yapısına veya sayfaya özgü class isimlerine güvenmeyin.

Stil için scoped CSS (veya CSS Modules) tercih edin ve paylaşılan sınıfları isim alanıyla (namespace) belirleyin. Eğer widget uygulama temasına uymalıysa, tema tokenlarını (renkler, boşluk, font boyutu) prop olarak verin, sayfa stillerini içe aktarmayın.

Slotlar küçük ve isteğe bağlı kaldıklarında güvenlidir (ör. bir "boş durum" mesajı). Eğer slotlar temel düzeni veya davranışı kontrol etmeye başlarsa, widget tekrar üretilen katmana kaymış demektir ve yeniden üretme acıları başlar.

Kararlı bir bileşen sözleşmesi tasarlamak (props ve eventler)

Yeniden üretmeyi sorunsuz tutmanın en güvenli yolu, her widget'ı kararlı bir arayüz gibi görmektir. Üretilen ekranlar değişebilir. Bileşeniniz değişmemeli.

Girdi olarak (props) başlayın. Az, öngörülebilir ve doğrulanması kolay tutun. Basit primitifleri ve kontrolünüzdeki düz nesneleri tercih edin. Ekranın henüz hiçbir şey göndermediği durumlarda bile bileşenin kabul edilebilir davranması için varsayılanlar ekleyin. Eğer bir değer hatalı olabilir (ID'ler, tarih stringleri, enum benzeri değerler), doğrulayın ve yumuşak hata verin: çökme yerine boş durum gösterin.

Çıktılar için, widgetlerin uygulama içinde tutarlı hissetmesi adına eventleri standartlaştırın. Güvenilir bir set örneği:

• update:modelValue (v-model için)
• change (kullanıcının onayladığı değişiklikler için, her tuş vuruşu değil)
• error (bileşen görevini tamamlayamazsa)
• ready (asenkron işler bittiğinde ve widget kullanılabilir olduğunda)

Eğer asenkron iş varsa, bunu sözleşmenin parçası yapın. loading ve disabled prop'larını açık edin ve sunucu hataları için errorMessage düşünün. Bileşen kendi verisini çekiyorsa, yine de parent'in tepki verebilmesi için error ve ready eventlerini emit edin (toast, log, fallback UI gibi).

Erişilebilirlik beklentileri

Erişilebilirliği sözleşmeye dahil edin. Bir label (veya ariaLabel) prop kabul edin, klavye davranışını belgeleyin ve eylemler sonrası odak (focus) davranışını öngörülebilir tutun.

Örneğin, bir panodaki (dashboard) zaman çizelgesi widget'ı ok tuşlarıyla öğeler arasında gezinmeyi, Enter ile detayları açmayı desteklemeli ve bir iletişim kutusu kapandığında odağı onu açan kontrole geri vermelidir. Bu, widget'ı üretilen farklı ekranlarda ekstra iş yapmadan yeniden kullanılabilir kılar.

Adım adım: üretilen dosyalara dokunmadan bir özel widget eklemek

Küçük başlayın: kullanıcıların önem verdiği bir ekran, onu farklı kılan bir widget. İlk değişikliği dar tutmak, yeniden üretmenin neleri etkilediğini görmek için iyidir.

1. Bileşeni üretilen alanın dışında oluşturun. Sahip olduğunuz bir klasöre koyun ve versiyon kontrolünde tutun (genelde custom veya extensions).

2. Kamu yüzeyini (public surface) küçük tutun. Birkaç prop girer, birkaç event çıkar. Tüm sayfa durumunu paslamayın.

3. İnce bir wrapper ekleyin. Bunun işi "üretilen sayfa verisini" widget sözleşmesine çevirmektir.

4. Desteklenen bir genişletme noktasından entegre edin. Wrapper'ı referans etmek için üretilen dosyaları düzenlemeyi gerektirmeyen bir yol kullanın.

5. Yeniden üretin ve doğrulayın. Özel klasörünüz, wrapper ve bileşeniniz değişmemeli ve derlenmeli.

Sınırları keskin tutun. Widget görüntüleme ve etkileşim ile ilgilensin. Wrapper veri haritalama ve eylem yönlendirme yapsın. İş kuralları uygulamanın mantık katmanında (backend veya paylaşılan süreçler) kalsın, widget içinde gömülü olmasın.

Hızlı bir kontrol: şimdi yeniden üretme olsaydı, bir ekip arkadaşı projeyi yeniden oluşturup manuel düzenlemeleri yeniden yapmadan aynı sonucu alabilir miydi? Cevap evetse, desen sağlamdır.

Mantığı nereye koymalısınız ki UI sürdürülebilir kalsın

Özel bir widget çoğunlukla nasıl göründüğü ve kullanıcı girdisine nasıl cevap verdiğiyle ilgilenmeli. Widget içine ne kadar çok iş kuralı eklerseniz, onu yeniden kullanmak, test etmek ve değiştirmek o kadar zorlaşır.

İyi varsayılan: iş mantığını sayfa veya özellik katmanında tutun; widget "dumb" kalsın. Sayfa hangi veriyi verdiğini ve widget bir event yayınladığında ne olacağını belirler. Widget render yapar ve kullanıcı niyetini raporlar.

Widget'a yakın mantığa gerçekten ihtiyaç duyarsanız (formatlama, küçük durum yönetimi, istemci tarafı doğrulama), bunu küçük bir servis katmanının arkasına saklayın. Vue3'te bu bir modül, bir composable veya net API'li bir store olabilir. Widget bu API'yi içe aktarır, rastgele uygulama içlerinden değil.

Pratik bir ayrım:

• Widget (bileşen): UI durumu, girdi işleme, görsellik, select, change, retry gibi eventleri emit etme.
• Service/composable: veri şekillendirme, önbellekleme, API hatalarını kullanıcı mesajlarına eşleme.
• Sayfa/container: iş kuralları, izinler, hangi verinin yükleneceği, ne zaman kaydedileceği.
• Üretilen uygulama parçaları: dokunulmaz; veriyi paslayın ve eventleri dinleyin.

Widget içinde doğrudan API çağrılarından kaçının, bu widget'ın sözleşmesinin parçası değilse. Eğer fetch işini kendi üstleniyorsa bunu belli yapın (ör. bileşeni CustomerSearchWidget gibi isimlendirin ve çağrı kodunu bir serviste toplayın). Aksi halde items, loading ve error gibi prop'ları paslayın.

Hata mesajları kullanıcıya yönelik ve tutarlı olmalı. Ham sunucu metnini göstermek yerine, uygulamanızın her yerde kullandığı küçük bir mesaj kümesine eşleyin: “Veri yüklenemedi. Tekrar deneyin.” Gerekirse yeniden deneme eylemi ekleyin ve ayrıntılı hataları widget dışında loglayın.

Örnek: özel bir ApprovalBadge widget'ı faturanın onaylanabilir olup olmadığını karar vermemeli. Sayfa status ve canApprove hesaplasın. Rozet approve eventini fırlatsın; sayfa gerçek kuralı uygular ve backend'i çağırır, sonra başarı veya hata durumunu UI'ye temiz olarak döner.

Yeniden üretmeden sonra ağrıya neden olan yaygın hatalar

Çoğu sorun Vue ile ilgili değildir. Sorun, özel çalışmayı jeneratörün sahip olduğu yerlere karıştırmaktan veya değişmesi muhtemel detaylara dayanmaktan kaynaklanır.

Küçük bir widgetı sürekli temizlik gerektiren işe çeviren en yaygın hatalar:

• Üretilen Vue dosyalarını doğrudan düzenlemek ve neyi değiştirdiğinizi unutmak.
• Geniş seçiciler veya global CSS kullanmak; markup değişince diğer ekranları etkiler.
• Üretilen durum şeklini doğrudan okumak veya değiştirmek; masum bir yeniden adlandırma widget'ı kırar.
• Bir bileşeni fazla sayfa-spesifik varsayımla doldurmak.
• Bileşen API'sini (props/eventler) göç planı olmadan değiştirmek.

Yaygın bir senaryo: özel bir tablo widget'ı eklersiniz ve çalışır. Bir ay sonra üretilen bir düzen değişikliği global .btn kuralınızın giriş ve yönetici sayfalarını etkilemesine neden olur. Ya da bir veri nesnesi user.name'den user.profile.name'e döner ve widget sessizce başarısız olur. Sorun widget değil; kararsız detaylara olan bağımlılıktır.

İki alışkanlık çoğunu önler:

Birincisi, üretilen kodu salt-okunur kabul edin ve özel dosyaları ayrı tutun, net bir içe aktarma sınırı oluşturun.

İkincisi, bileşen sözleşmesini küçük ve açık tutun. Geliştirmeniz gerekirse basit bir versiyon prop'u ekleyin (ör. apiVersion) veya bir sürüm boyunca hem eski hem yeni prop şekillerini destekleyin.

Yayına almadan önce hızlı kontrol listesi

Özel bir widget'ı üretilen Vue3 uygulamasına merge etmeden önce hızlı bir gerçeklik kontrolü yapın. Bir sonraki yeniden üretmeyi kahramanlık gerektirmeden atlatmalı ve başkası tarafından tekrar kullanılabiliyor olmalı.

• Yeniden üretme testi: tam bir regenerate ve rebuild çalıştırın. Bir üretilen dosyayı tekrar düzenlemek zorunda kaldıysanız, sınır yanlış demektir.
• Net girişler ve çıkışlar: props girer, eventler çıkar. Harici DOM'a erişim veya belirli bir sayfa store'una bağlı sihirli bağımlılıklardan kaçının.
• Stil kapsama: stilleri scoped tutun ve net bir sınıf öneki kullanın (ör. timeline-).
• Tüm durumlar iyi görünsün: loading, error ve empty durumları mantıklı ve mevcut olmalı.
• Kopyalamadan yeniden kullan: başka bir sayfaya eklemek için içeriği kopyalamak yerine prop ve event değişiklikleriyle çalıştığından emin olun.

Bunu doğrulamanın hızlı yolu: widget'ı bir yönetici ekranına ve sonra müşteri portalına eklemeyi hayal edin. Sadece prop değişiklikleri ve event işleyicileriyle ikisi de çalışıyorsa, güvendesiniz.

Gerçekçi bir örnek: bir panoya timeline widget eklemek

Destek ekibi genelde bir ticket'ın hikayesini anlatan bir ekran ister: durum değişiklikleri, dahili notlar, müşteri yanıtları ve ödeme veya teslimat olayları. Bir zaman çizelgesi widget'ı iyi uyar, ama bir sonraki yeniden üretmede işi kaybetmek istemezsiniz.

Güvenli yaklaşım, widget'ı üretilen UI'nin dışında izole tutmak ve sayfaya ince bir wrapper aracılığıyla dahil etmektir.

Widget sözleşmesi

Basit ve öngörülebilir tutun. Örneğin, wrapper şu propsları geçer:

• ticketId (string)
• range (son 7 gün, son 30 gün, özel)
• mode (compact vs detailed)

Widget şu eventleri emit eder:

• select kullanıcı bir olaya tıkladığında
• changeFilters kullanıcı filtreleri değiştirdiğinde

Artık widget panoyu, veri modellerini veya isteklerin nasıl yapıldığını bilmez. Bir zaman çizelgesi render eder ve kullanıcı eylemlerini bildirir.

Wrapper'ın sayfayla bağlantısı

Wrapper panonun yanında durur ve sayfa verisini sözleşmeye çevirir. Mevcut ticket ID'sini sayfa durumundan okur, UI filtrelerini range'e çevirir ve backend kayıtlarını widget'ın beklediği olay formatına eşler.

Widget select emit ettiğinde wrapper detay paneli açabilir veya bir sayfa eylemi tetikleyebilir. changeFilters geldiğinde wrapper sayfa filtrelerini günceller ve veriyi yeniler.

Panodaki UI yeniden üretildiğinde widget dokunulmadan kalır çünkü üretilen dosyaların dışında yaşıyor. Genelde sadece sayfa bir alanın adını değiştirirse veya filtreleri nasıl sakladığını değiştirirse wrapper'a bakarsınız.

Sürprizleri önleyen test ve sürüm alışkanlıkları

Özel bileşenler genelde sıkıcı şekillerde başarısız olur: prop şekli değişir, bir event çalışmaz olur veya üretilen sayfa widget'ın beklediğinden daha sık yeniden render edilir. Birkaç alışkanlık bu sorunları erken yakalar.

Yerel test: sınır kırılmalarını erken yakalayın

Üretilen UI ile widget arasındaki sınırı bir API gibi test edin. Önce widget'ı tam uygulama olmadan, sözleşmeye uygun sabit prop'larla render edin.

"Mutlu yol" prop'ları ile ve eksik değerlerle render edin. Önemli eventleri (kaydet, iptal, seç) simüle edin ve parent'in bunları işlediğini doğrulayın. Yavaş veri ve küçük ekranları test edin. Sözleşmede olmadıkça global state yazmadığını doğrulayın.

AppMaster Vue3 web uygulamasında çalışıyorsanız, bunları yeniden üretmeden önce yapın; iki şeyi aynı anda değiştirmeden sınır sorununu tanılamak daha kolaydır.

Yeniden üretmeden sonra regresyon: önce neyi tekrar kontrol etmelisiniz

Her yeniden üretmeden sonra temas noktalarını tekrar kontrol edin: aynı prop'lar paslanıyor mu, aynı eventler ele alınıyor mu? Genelde bozulma ilk burada görünür.

Dahil etmeyi öngörülebilir tutun. Dosya yollarının değişebileceği kırılgan importlardan kaçının. Özel bileşenleriniz için tek stabil bir giriş noktası kullanın.

Prod için widget içinde hafif logging ve hata yakalama ekleyin:

• Mount edildiğinde ana prop'lar (temizlenmiş)
• Sözleşme ihlalleri (zorunlu prop yok veya yanlış tip)
• Başarısız API çağrıları için kısa hata kodu
• Beklenmeyen boş durumlar

Bir şey bozulduğunda hızlıca şunu yanıtlamak istersiniz: değişen girdiler mi (üretim), yoksa widget mı değişti?

Bir deseni uygulama çapında tekrar edilebilir hale getirmek için sonraki adımlar

İlk widget çalıştıktan sonra gerçek kazanç, bunu tekrarlanabilir hale getirmektir ki bir sonraki widget tek seferlik bir yamaya dönüşmesin.

Widget sözleşmeleri için küçük bir dahili standart oluşturun ve ekip notlarınızın olduğu yerde yazın. Basit tutun: adlandırma, zorunlu vs isteğe bağlı prop'lar, küçük bir event seti, hata davranışı ve sahiplik (üretilen UI vs özel klasör).

Ayrıca sınır kurallarını açık dilde yazın: üretilen dosyaları düzenlemeyin, özel kodu izole edin ve veriyi sadece props ve eventlerle geçirin. Bu, kalıcı bir bakım yüküne dönüşen "hızlı düzeltmeyi" engeller.

İkinci bir widget inşa etmeden önce küçük bir yeniden üretme denemesi yapın. İlk widget'ı yayınlayın, sonra normal değişiklikler (bir etiket değişikliği, bir düzen değişikliği, yeni bir alan) sırasında en az iki kez yeniden üretme yapın ve hiçbir şeyin bozulmadığını onaylayın.

AppMaster kullanıyorsanız, genelde UI ve mantığın çoğunu görsel editörlerde (UI builder, Business Process Editor ve Data Designer) tutmak en iyi sonuç verir. Özel Vue bileşenleri, editörlerin ifade edemediği gerçekten özel widget'lar için saklayın: özel zaman çizelgeleri, etkileşimli grafikler veya sıra dışı giriş kontrolleri gibi. Bu yaklaşıma temiz bir başlangıç istiyorsanız, AppMaster on appmaster.io yeniden üretme etrafında tasarlandığı için özel widget'ları izole etmek iş akışının doğal bir parçası olur.