Web Bileşenleri Oryantasyonu

Web Bileşenleri; Özel Öğeler, Gölge DOM ve HTML Şablonları'dır. Bunlar, işaretlemeleri ve stilleri dokümandan kapsüllenmiş, yeniden kullanılabilir, çerçeveden bağımsız bileşenler için platform temel öğeleridir. Tasarım sistemleri, yerleştirilebilir widget'lar ve bağımsız kullanıcı arayüzü için bunları kullanın.

Aşağıdaki kurallar tüm alanlar için geçerlidir. Mevcut görevle ilgili kılavuzu alın. Her kılavuzda, ihtiyaç duyduğu bağlam yeniden belirtilir ve ilgili API'ler ile dikkat edilmesi gereken noktalar açıklanır.

Özel bir öğeye ihtiyacınız olup olmadığına karar verme

Özel öğeleri yalnızca bir etikette kapsüllenmiş davranış, yaşam döngüsü veya yeniden kullanılabilir JS destekli API gerektiğinde kullanın. Aşağıdaki durumlarda beceri oluşturmayın:

• CSS içeren düz bir HTML öğesi yeterli olacaktır. Stili belirlenmiş bir <button> veya <details>, yeniden uygulamaya göre daha erişilebilir ve daha ucuzdur.
• Öğe yalnızca sunum amaçlıdır ve herhangi bir davranış içermez. Yerel bir öğedeki sınıf daha performanslıdır ve @layer veya @scope ile kapsamlandırılabilir.
• Yalnızca sunucuda stil kapsamı belirlemeniz gerekir ve etkileşim gerekmez. Kapsamlı bir stil sayfası veya bildirim temelli gölge DOM (yükseltme olmadan) yeterli olabilir.

Yerel semantiği yeniden oluşturmak (odağı, etkinleştirmeyi ve ARIA'yı yeniden oluşturan özel bir <my-button>), en yaygın hatalı kullanımdır: Platformun erişilebilirliğini yalnızca yerel öğeyi yeniden kullanırsanız ücretsiz olarak devralırsınız. <my-button> stili sarmalayıcı gerekli olduğunda (genellikle paylaşılan stil kancaları, ek işaretleme veya yerel bir öğenin ifade edemeyeceği davranışlar için) gerçek <button> öğesini yeniden uygulamak yerine sarmalayın (stilleri dahili bir yerel öğeye yönlendirmek için Web Bileşenlerini Stilize Etme bölümüne bakın).

Test, yalnızca farklı bir görünüme değil, kapsüllenmiş duruma, komut dosyası oluşturulabilir bir API'ye veya yerel öğenin ifade edemeyeceği bir davranışa ihtiyacınız olup olmadığıdır. Beğenme/favorilere ekleme açma/kapatma düğmesi uygundur: Kilitli alan durumunu taşır, bu durumu çevreleyen sayfa için bir stil kancası olarak gösterir ve kendi change etkinliğini gönderir. Bunların hiçbirini stillendirilmiş bir <button> sağlamaz. Yalnızca basıldığında renk değiştiren bir düğme, <button> + CSS'ye ulaşmaz. Oluşturduğunuzda, durumunu uygun şekilde özel bir durum veya özellikle modelleyin (Özel Öğeler bölümüne bakın).

Aracı kod tabanıyla eşleştirme

Bir şeyin özel öğe olması gerekip gerekmediği, projede halihazırda kullanılanlara bağlıdır. Temsilciler aşırı soyutlama yapma ve yeni bir öğeye çok hevesli bir şekilde ulaşma eğilimindedir. Şüpheye düştüğünüzde genellikle daha hafif seçenek (yerel öğe, CSS, sunucu şablonu) doğru olur ve yeniden kullanım veya davranış gerçekten gerektiriyorsa daha sonra özel bir öğeye yükseltebilirsiniz. Buluşsal yöntemler (yaklaşık öncelik sırasına göre):

• Kod tabanında zaten bir bileşen modeli (React, Vue, Svelte vb.) vardır. Uygulama içi kullanıcı arayüzü için varsayılan olarak bu çerçevenin bileşenini kullanın. Özel öğeleri yalnızca çerçevenin dışına çıkması veya çerçeveden daha uzun süre dayanması gereken durumlarda kullanın: uygulamalar veya çerçeveler arasında paylaşılan bir tasarım sistemi temel öğesi, çerçevenin kontrol etmediği işaretlemeye bırakılan bir widget veya düz HTML olarak çalışması gereken çıkış (e-posta, İYS, SSR parçaları). Sıradan uygulama görünümleri için paralel bir bileşen sistemi oluşturmayın.
• Araç yok, çoğunlukla statik işaretleme. Düz HTML + CSS veya sunucu şablonu/kısmi şablon tercih edin. Özel bir öğe, yalnızca etikette davranış, yaşam döngüsü veya JS destekli bir API'ye gerçekten ihtiyacınız olduğunda işe yarar. Yalnızca işaretleme paylaşmak için kullanılmaz. İşaretleme paylaşımı, sunucu dahil etme veya <template> tarafından JS gönderilmeden yapılır.
• Etkileşim adaları içeren statik site oluşturucu. İşaretlemeyi statik olarak oluşturun. Özel öğeyi etkileşimli bölüm için ayırın. "Çok sayıda işaretleme, az etkileşim" için işaretlemeyi Light DOM'da (veya Declarative Shadow DOM) tutun ve her şeyi JS'den yeniden oluşturmak yerine küçük bir özel öğenin bunu aşamalı olarak geliştirmesine izin verin.
• Bunun yerine, yerleşik bir öğeyi daha da geliştirebilirsiniz. Yerel bir öğeyi mümkün olduğunca kullanmak (CSS, birkaç dinleyici, ara sıra sözde öğe) genellikle özel bir öğeye tercih edilir. Çünkü platformun erişilebilirliğini ve davranışını ücretsiz olarak kullanmaya devam edersiniz. Geçici çözümler sürdürülebilir olmaktan çıktığında (öğenin yerleşik davranışıyla mücadele etmeniz gerektiğinde veya yazma deneyimi temiz bir bileşen API'sinden daha kötü hale geldiğinde) özel bir öğeye geçin. Yerleşik bir öğede biraz JS'ye ihtiyaç duymak, tek başına bu öğeyi değiştirmek için bir neden değildir.

Çapraz kurallar

Aşağıdaki tüm kılavuzlar için geçerlidir:

• ZORUNLU: Etiket adı, en az bir kısa çizgi içeren tireli yazım (kebab-case) biçiminde olmalıdır (ör. my-element). Özel öğeleri mevcut ve gelecekteki yerleşik öğelerden ayıran özellik budur.
• ZORUNLU: this öğesine dokunmadan önce kurucuda ilk olarak super() öğesini çağırın. this öğesini okuyan veya yazan herhangi bir ifadeden sonra çağrıldığında hata verir.
• ZORUNLU: Gölge şablonlarında semantik öğeler (<button>, <nav>, <ul>) kullanın. Gölge ağaçlardaki erişilebilirlik hatalarının çoğu anlamsal olmayan işaretlemeden kaynaklanır. Bir alan, yansıttığı öğenin rolünü değiştirmez.
• ZORUNLU: ARIA id referansları (aria-labelledby, aria-describedby, aria-controls) gölge sınırını aşamaz. Referans veren öğe ve işaret ettiği id aynı ağaçta bulunmalıdır.
• Geliştirici araçları, sayfa komut dosyaları ve sunucu hidrasyonunun element.shadowRoot adresine ulaşabilmesi için attachShadow({ mode: 'open' }) adresini tercih edin. 'closed' öğesini yalnızca dahili yapıyı sayfa komut dosyalarından gizlemeniz gerektiğinde kullanın.
• Özelleştirilmiş yerleşik öğelerden (extends HTMLButtonElement ile is="…") kaçının. Safari bunları kalıcı olarak reddetti.

Kullanım alanı kılavuz matrisi

Görevi belirleyin ve kılavuzunu alın: