Hızlı Başlangıç
mdui'nin bileşenleri standart Web Components bileşenleridir. mdui bileşenlerini <div> etiketi gibi kullanabilirsiniz. Her bileşenin dokümantasyonunda, öznitelikler, özellikler, yöntemler, olaylar, slot, CSS Part, CSS Custom Property dahil olmak üzere tüm API'si ayrıntılı olarak açıklanmıştır.
Bu bölümdeki dokümantasyon size Web Components kullanımını tanıtacaktır.
Öznitelik
Öznitelikler, HTML öznitelikleri ve JavaScript özellikleri olarak ikiye ayrılır. Genellikle bire bir karşılık gelirler ve senkronize kalırlar. Yani, bir HTML özniteliği değerini güncellediğinizde, JavaScript özellik değeri de buna göre güncellenir; bunun tersi de geçerlidir.
HTML öznitelikleri doğrudan bileşenin HTML dizesinde ayarlanabilir ve getAttribute ve setAttribute yöntemleriyle okunup değiştirilebilir:
<mdui-button variant="text">Bana Tıkla</mdui-button>
<script>
const button = document.querySelector('mdui-button');
// HTML özniteliğini değiştir
button.setAttribute('variant', 'outlined');
// HTML özniteliğini oku
console.log(button.getAttribute('variant')); // outlined
</script>
JavaScript özellikleri ise doğrudan bileşen örneğinin özellik değerlerini okumak veya ayarlamak için kullanılabilir:
<mdui-button variant="text">Bana Tıkla</mdui-button>
<script>
const button = document.querySelector('mdui-button');
// JavaScript özelliğini ayarla
button.variant = 'outlined';
// JavaScript özelliğini oku
console.log(button.variant); // outlined
</script>
Bazı özellik değerleri boolean türündedir. Bu özelliklerin HTML özniteliği mevcut olduğunda, JavaScript özelliği true, aksi halde false olur. Ancak, bazı çerçevelerle uyumluluk için mdui, false dize değerini de boolean false değeri olarak değerlendirir.
<!-- Bu bileşen disabled özniteliğine sahiptir, yani varsayılan olarak disabled özellik değeri true'dur -->
<mdui-button disabled></mdui-button>
<script>
const button = document.querySelector('mdui-button');
button.removeAttribute('disabled'); // button.disabled = false; ile eşdeğerdir
button.setAttribute('disabled', ''); // button.disabled = true; ile eşdeğerdir
// İstisna durumu, 'false' dize değeri ayarlamak, boolean false değeri ayarlamakla eşdeğerdir
button.setAttribute('disabled', 'false'); // button.disabled = false; ile eşdeğerdir
</script>
Bazen özellik değerleri dizi, nesne veya fonksiyon olabilir. Bu durumda yalnızca JavaScript özelliği bulunur, karşılık gelen bir HTML özniteliği yoktur. Örneğin, <mdui-slider> bileşeninin labelFormatter özelliği bir fonksiyondur. Bu özelliği yalnızca JavaScript aracılığıyla ayarlayabilirsiniz:
<mdui-slider></mdui-slider>
<script>
const slider = document.querySelector('mdui-slider');
slider.labelFormatter = (value) => `${value}%`;
</script>
Aşağıda, <mdui-slider> bileşeninin özellik dokümantasyonunun bir kısmı örnek olarak verilmiştir:
| HTML özniteliği | JavaScript özelliği | reflect |
|---|---|---|
name |
name |
|
value |
value |
|
labelFormatter |
Bu bileşenin name özniteliği, HTML özniteliğine ve JavaScript özelliğine sahiptir ve reflect sütunu, JavaScript özelliği güncellendiğinde HTML özniteliğinin de senkronize olarak güncellendiğini gösterir. value özelliği ise JavaScript özelliği güncellendiğinde HTML özniteliğini güncellemez. labelFormatter özelliği ise yalnızca JavaScript özelliğine sahiptir.
Yöntem
Bazı bileşenler genel yöntemler sağlar. Bu yöntemleri çağırarak farklı işlevleri gerçekleştirebilirsiniz. Örneğin, <mdui-text-field> bileşeninin focus() yöntemi, metin alanının odaklanmasını sağlar.
<mdui-text-field></mdui-text-field>
<script>
const textField = document.querySelector('mdui-text-field');
textField.focus();
</script>
Her bir bileşenin dokümantasyon sayfasında mevcut tüm yöntemleri ve parametrelerini inceleyebilirsiniz.
Olay
Bazı bileşenler belirli işlemleri gerçekleştirirken olaylar tetikler. Örneğin, <mdui-dialog> bileşeni açılırken open olayını tetikler. Bu olayı dinleyerek özel işlemler gerçekleştirebilirsiniz.
<mdui-dialog>Diyalog</mdui-dialog>
<script>
const dialog = document.querySelector('mdui-dialog');
dialog.addEventListener('open', () => {
console.log('Diyalog açılmaya başladığında bu olay tetiklenir');
});
</script>
Her bir bileşenin dokümantasyon sayfasında mevcut tüm olayları ve parametrelerini inceleyebilirsiniz.
Eğer mdui'yi diğer çerçevelerde (Vue, React, Angular vb.) kullanıyorsanız, olayları bağlamak için çerçevenin sağladığı sözdizimini kullanabilirsiniz. Ancak, React gibi bazı çerçevelerin olay bağlama sözdizimi yalnızca standart olayları (örneğin click olayı) bağlamak için kullanılabilir, özel olayları (örneğin open olayı) bağlamak için kullanılamaz. Bu nedenle, React'te özel olayları bağlamak için önce öğenin referansını almanız ve ardından addEventListener yöntemini kullanarak olayı bağlamanız gerekir.
React'te mdui kullanımı hakkında daha fazla bilgi için bkz. Çerçevelerle Entegrasyon - React.
Slot
Birçok bileşen, özel HTML içeriğini bileşenin içine yerleştirmek için slot sağlar.
En yaygın olanı varsayılan slottur. Bu, bileşenin içindeki sıradan bir HTML veya düz metindir. Örneğin, <mdui-button> bileşeninin varsayılan slot'u, butonun metnini ayarlamak için kullanılır. Örnekteki "Bana Tıkla" varsayılan slot'un içeriğidir:
<mdui-button>Bana Tıkla</mdui-button>
Bazı bileşenler ayrıca adlandırılmış slot da sağlar. Adlandırılmış slot için HTML'deki slot özniteliğinde slot adını belirtmeniz gerekir. Aşağıdaki örnekte, <mdui-icon> bileşeni slot="start" olarak belirtilmiştir. Bu, start adında adlandırılmış bir slot olduğu anlamına gelir, yani bu simge bileşenin içindeki sol tarafa eklenecektir:
<mdui-button>
<mdui-icon slot="start" name="settings"></mdui-icon>
Ayarlar
</mdui-button>
Bir bileşen birden fazla adlandırılmış slot kullanıyorsa, adlandırılmış slot'ların sırası önemli değildir. Bileşenin içinde oldukları sürece, tarayıcı bunları otomatik olarak doğru konumlara yerleştirecektir.
Desteklenen tüm slot'ları her bir bileşenin dokümantasyon sayfasında inceleyebilirsiniz.
CSS Custom Property
CSS Custom Property, CSS'teki değişkenlerdir. mdui, bir dizi genel CSS Custom Property tanımlar. Bu özellikler her bileşenin içinde referans alınır. Bu nedenle, bu CSS Custom Property'leri değiştirerek mdui bileşenlerinin stillerini genel olarak değiştirebilirsiniz.
Örneğin, aşağıdaki kod tüm bileşenlerin köşe yuvarlaklık boyutunu küçültür:
:root {
--mdui-shape-corner-extra-small: 0.125rem;
--mdui-shape-corner-small: 0.25rem;
--mdui-shape-corner-medium: 0.375rem;
--mdui-shape-corner-large: 0.5rem;
--mdui-shape-corner-extra-large: 0.875rem;
}
Ayrıca yerel kapsamda da CSS Custom Property'leri değiştirebilirsiniz. Örneğin, aşağıdaki kod yalnızca class="sharp" içeren öğe ve alt öğelerinde köşe yuvarlaklık boyutunu küçültür:
.sharp {
--mdui-shape-corner-extra-small: 0.125rem;
--mdui-shape-corner-small: 0.25rem;
--mdui-shape-corner-medium: 0.375rem;
--mdui-shape-corner-large: 0.5rem;
--mdui-shape-corner-extra-large: 0.875rem;
}
Bazı bileşenler ayrıca o bileşene özgü CSS Custom Property'ler sağlar. Bu özelliklerin kapsamı belirli bir bileşen olduğu için --mdui ön eki içermezler. Örneğin, aşağıdaki kod <mdui-dialog> bileşeninin --z-index özelliğini değiştirerek z-index stilini değiştirir:
mdui-dialog {
--z-index: 3000;
}
Bir bileşenin desteklediği CSS Custom Property'leri, her bir bileşenin dokümantasyon sayfasında inceleyebilirsiniz.
CSS Part
mdui bileşenleri, stilleri ve davranışları kapsüllemek için shadow DOM kullanır, ancak normal CSS seçicileri shadow DOM içindeki öğeleri seçemez. Bu nedenle, bazı bileşenler Shadow DOM öğelerine part özniteliği ekler. ::part CSS seçicisini kullanarak ilgili öğeleri seçebilir ve stillerinin bir kısmını geçersiz kılabilirsiniz.
Örneğin, aşağıdaki kod button part'ını kullanarak butonun iç boşluğunu değiştirir ve label, icon, end-icon part'larını kullanarak sırasıyla metin, sol simge ve sağ simgenin renklerini değiştirir:
<mdui-button class="custom-button" icon="explore" end-icon="flight">Buton</mdui-button>
<style>
.custom-button::part(button) {
padding: 0 2rem;
}
.custom-button::part(label) {
color: blue;
}
.custom-button::part(icon) {
color: red;
}
.custom-button::part(end-icon) {
color: yellow;
}
</style>Bileşenin shadow DOM öğelerinin yapısını ve varsayılan stillerini, tarayıcının geliştirici araçlarını açarak inceleyebilirsiniz.
CSS Part kullanmadan önce, genel CSS Custom Property'leri ve bileşene özgü CSS Custom Property'lerin ihtiyaçlarınızı karşılayıp karşılamadığını değerlendirmelisiniz. Eğer ihtiyaçlarınızı karşılıyorsa, stilleri özelleştirmek için öncelikle CSS Custom Property'leri kullanmalısınız.
Bir bileşen tarafından açığa çıkarılan tüm part özniteliklerini, her bir bileşenin dokümantasyon sayfasında inceleyebilirsiniz.
Bileşen Güncelleme Mekanizması
mdui bileşenleri, Lit tabanlı olarak geliştirilmiştir. Lit, Web Components geliştirmeyi daha kolay hale getiren hafif bir kütüphanedir. mdui bileşenlerini kullanırken, bunların render ve güncelleme mekanizmalarını anlamanız gerekebilir.
Bir mdui bileşeninin özelliklerini değiştirdiğinizde, bileşen yeniden render edilir. Ancak bu yeniden render işlemi senkronize olarak gerçekleşmez. Birden fazla özellik değerini aynı anda değiştirdiğinizde, Lit bu değişiklikleri bir sonraki güncelleme döngüsüne kadar önbelleğe alır. Bu sayede, özellik değerlerini kaç kez değiştirdiğinizden bağımsız olarak her bileşen yalnızca bir kez yeniden render edilir. Ayrıca, yalnızca shadow DOM'da değişen kısımlar yeniden render edilir.
Aşağıdaki örnekte, butonun disabled JavaScript özellik değerini true olarak ayarlayıp hemen HTML özniteliğini sorguluyoruz. Ancak, bileşen henüz yeniden render edilmediği için sorgulanan HTML özniteliği hala false olacaktır:
const button = document.querySelector('mdui-button');
button.disabled = true;
console.log(button.hasAttribute('disabled')); // false
Bir özellik değeri değişikliğinden sonra yeniden render işleminin tamamlanmasını beklemek için bileşenin updateComplete özelliğini kullanabilirsiniz. Bu özellik, bileşen yeniden render işlemini tamamladığında çözülen bir Promise döndürür:
const button = document.querySelector('mdui-button');
button.disabled = true;
button.updateComplete.then(() => {
console.log(button.hasAttribute('disabled')); // true
});