Gyors áttekintés

Az mdui komponensei szabványos Web Components komponensek, így ugyanúgy használhatja őket, mint a <div> címkét. Minden komponens dokumentációs oldala részletesen ismerteti a teljes API-t, beleértve az attribútumokat, tulajdonságokat, metódusokat, eseményeket, slot-okat, CSS Part-okat, CSS egyéni tulajdonságokat stb.

Ez a fejezet a Web Components használatát mutatja be.

Attribútumok

Az attribútumok két típusra oszthatók: HTML attribútumok és JavaScript tulajdonságok. Ezek általában egy az egyben megfeleltethetők, és szinkronban maradnak egymással. Ha frissíti a HTML-attribútum értékét, a JavaScript-tulajdonság értéke is frissül, és ez fordítva is igaz.

A HTML attribútumokat közvetlenül a komponens HTML karakterláncában állíthatja be, és a getAttribute és setAttribute metódusokkal olvashatja és módosíthatja:

<mdui-button variant="text">Kattints rám</mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  // HTML attribútum módosítása
  button.setAttribute('variant', 'outlined');

  // HTML attribútum beolvasása
  console.log(button.getAttribute('variant')); // outlined
</script>

A JavaScript tulajdonságokat közvetlenül a komponens példányának tulajdonságaiként olvashatja vagy állíthatja be:

<mdui-button variant="text">Kattints rám</mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  // JavaScript tulajdonság beállítása
  button.variant = 'outlined';

  // JavaScript tulajdonság beolvasása
  console.log(button.variant); // outlined
</script>

Egyes tulajdonságok boolean típusúak. Ezeknél a HTML attribútum megléte esetén a JavaScript tulajdonság true, egyébként false. Azonban egyes keretrendszerekkel való kompatibilitás miatt az mdui a false karakterláncot is boolean false értékként értelmezi.

<!-- Ennél a komponensnél a disabled attribútum jelen van, azaz a disabled tulajdonság alapértelmezett értéke true -->
<mdui-button disabled></mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  button.removeAttribute('disabled'); // egyenértékű a button.disabled = false;
  button.setAttribute('disabled', ''); // egyenértékű a button.disabled = true;

  // Kivételes eset: a 'false' karakterláncra állítás egyenértékű a boolean false érték beállításával
  button.setAttribute('disabled', 'false'); // egyenértékű a button.disabled = false;
</script>

Néha a tulajdonság értéke tömb, objektum vagy függvény. Ilyenkor csak JavaScript tulajdonság létezik, nincs megfelelő HTML attribútum. Például a <mdui-slider> komponens labelFormatter tulajdonsága egy függvény, amelyet csak JavaScript-en keresztül állíthat be:

<mdui-slider></mdui-slider>

<script>
  const slider = document.querySelector('mdui-slider');
  slider.labelFormatter = (value) => `${value}%`;
</script>

Az alábbiakban a <mdui-slider> komponens tulajdonság dokumentációjának egy részlete látható példaként:

Ennél a komponensnél a name attribútumnak van HTML attribútuma és JavaScript tulajdonsága is, és a reflect oszlop azt jelzi, hogy a JavaScript tulajdonság frissítésekor a HTML attribútum is frissül. A value tulajdonságnál a JavaScript tulajdonság frissítésekor a HTML attribútum nem frissül. A labelFormatter tulajdonságnak pedig csak JavaScript tulajdonsága van.

Metódusok

Egyes komponensek nyilvános metódusokat biztosítanak, amelyek meghívásával különböző funkciókat valósíthat meg. Például a <mdui-text-field> komponens focus() metódusával a szövegmező fókuszba kerülhet.

<mdui-text-field></mdui-text-field>

<script>
  const textField = document.querySelector('mdui-text-field');
  textField.focus();
</script>

Az egyes komponensek dokumentációs oldalain megtekintheti az összes elérhető metódust és azok paramétereit.

Események

Egyes komponensek bizonyos műveletek végrehajtásakor eseményeket aktiválnak. Például a <mdui-dialog> komponens megnyitásakor aktiválja az open eseményt. Figyelheti ezt az eseményt, hogy egyéni műveleteket hajtson végre.

<mdui-dialog>Párbeszédablak</mdui-dialog>

<script>
  const dialog = document.querySelector('mdui-dialog');

  dialog.addEventListener('open', () => {
    console.log('A párbeszédablak nyitásakor ez az esemény aktiválódik');
  });
</script>

Az egyes komponensek dokumentációs oldalain megtekintheti az összes elérhető eseményt és azok paramétereit.

Ha más keretrendszerben (például Vue, React, Angular) használja az mdui-t, használhatja a keretrendszer által biztosított szintaxist az események kötésére. Azonban egyes keretrendszerek (például a React) eseménykötési szintaxisa csak a szabványos eseményekhez (például click esemény) használható, és nem használható egyéni események (például open esemény) kötésére. Ezért a Reactben az egyéni események kötéséhez először meg kell szereznie az elem referenciáját, majd az addEventListener metódussal kell az eseményt kötnie.

Az mdui Reactben való használatával kapcsolatos további információkért lásd a Keretrendszerek integrációja - React oldalt.

Slot

Számos komponens biztosít slot-okat, amelyek lehetővé teszik egyéni HTML-tartalom beillesztését a komponens belsejébe.

A leggyakoribb az alapértelmezett slot, amely egy sima HTML vagy egyszerű szöveg a komponens belsejében. Például a <mdui-button> komponens alapértelmezett slotja a gomb szövegének beállítására szolgál. A példában a „Kattints rám" az alapértelmezett slot tartalma:

<mdui-button>Kattints rám</mdui-button>

Egyes komponensek névvel ellátott slot-okat is biztosítanak. A névvel ellátott slot-ok esetén meg kell adnia a slot nevét a HTML slot attribútumában. Az alábbi példában a <mdui-icon> komponens a slot="start" értéket adja meg, ami a start nevű slot-ot jelöli, vagyis ez az ikon a komponens bal oldalára kerül beillesztésre:

<mdui-button>
  <mdui-icon slot="start" name="settings"></mdui-icon>
  Beállítások
</mdui-button>

Ha egy komponens több névvel ellátott slot-ot használ, a slot-ok sorrendje nem számít, amíg a komponensen belül vannak, a böngésző automatikusan a megfelelő helyre helyezi őket.

Az egyes komponensek dokumentációs oldalain megtekintheti az összes támogatott slot-ot.

CSS egyéni tulajdonságok

A CSS egyéni tulajdonságok a CSS változói. Az mdui számos globális CSS egyéni tulajdonságot határoz meg, amelyeket az egyes komponensek belsőleg hivatkoznak. Így ezeknek a CSS egyéni tulajdonságoknak a módosításával globálisan módosíthatja az mdui komponensek stílusát.

Például az alábbi kód kicsinyíti az összes komponens sarkainak lekerekítését:

: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;
}

A CSS egyéni tulajdonságokat lokális hatókörben is módosíthatja. Például az alábbi kód csak a class="sharp" elemen és annak gyermekein belül kicsinyíti a sarkok lekerekítését:

.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;
}

Egyes komponensek komponensspecifikus CSS egyéni tulajdonságokat is biztosítanak. Ezeknek a tulajdonságoknak a hatóköre az adott komponensre korlátozódik, ezért nem tartalmazzák a --mdui előtagot. Például az alábbi kód a <mdui-dialog> komponens --z-index tulajdonságának módosításával módosítja a z-index stílust:

mdui-dialog {
  --z-index: 3000;
}

Az egyes komponensek dokumentációs oldalain megtekintheti a komponensek által támogatott CSS egyéni tulajdonságokat.

CSS Part

Az mdui komponensek shadow DOM-ot használnak a stílusok és viselkedések elkülönítésére, de a szokásos CSS szelektorok nem képesek kiválasztani a shadow DOM belsejében lévő elemeket. Ezért egyes komponensek part attribútumot adnak a shadow DOM elemekhez, így a ::part CSS szelektor segítségével kiválaszthatja a megfelelő elemeket, és felülírhatja azok egyes stílusait.

Például az alábbi kód a button part segítségével módosítja a gomb belső kitöltését, és a label, icon, end-icon part-ok segítségével módosítja a szöveg, a bal és jobb oldali ikonok színét:

<mdui-button class="custom-button" icon="explore" end-icon="flight">Gomb</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>

A komponensek shadow DOM elemeinek szerkezetét és alapértelmezett stílusait a böngésző fejlesztői eszközeinek megnyitásával tekintheti meg.

A CSS Part használata előtt érdemes eldöntenie, hogy a globális CSS egyéni tulajdonságok és a komponensspecifikus CSS egyéni tulajdonságok használata kielégíti-e az igényeit. Ha igen, akkor előnyben kell részesítenie a CSS egyéni tulajdonságok használatát a stílusok testreszabásához.

Az egyes komponensek dokumentációs oldalain megtekintheti a komponensek által közzétett összes part attribútumot.

Komponens frissítési mechanizmusa

Az mdui komponensek a Lit-re épülnek. A Lit egy könnyűsúlyú könyvtár, amely megkönnyíti a Web Components fejlesztését. Az mdui komponensek használatakor fontos megértenie a renderelési és frissítési mechanizmusukat.

Amikor módosítja egy mdui komponens tulajdonságát, a komponens újrarenderelődik. Ez az újrarenderelési folyamat azonban nem szinkron módon történik. Amikor egyszerre több tulajdonság értékét módosítja, a Lit gyorsítótárazza ezeket a változásokat a következő frissítési ciklusig, hogy biztosítsa, függetlenül attól, hogy hányszor módosította a tulajdonságokat, minden komponens csak egyszer renderelődik újra. Emellett csak a shadow DOM-ban megváltozott részek renderelődnek újra.

Az alábbi példában a gomb disabled JavaScript tulajdonságát true értékre állítjuk, majd azonnal lekérdezzük a HTML attribútumát. Mivel azonban a komponens még nem renderelődött újra, a lekérdezett HTML attribútum értéke továbbra is false:

const button = document.querySelector('mdui-button');
button.disabled = true;

console.log(button.hasAttribute('disabled')); // false

Ha meg szeretné várni, amíg egy tulajdonság értékváltozása utáni újrarenderelés befejeződik, használhatja a komponens updateComplete tulajdonságát. Ez a tulajdonság egy Promise-t ad vissza, amely a Promise feloldódása után jelzi, hogy a komponens újrarenderelése befejeződött:

const button = document.querySelector('mdui-button');
button.disabled = true;

button.updateComplete.then(() => {
  console.log(button.hasAttribute('disabled')); // true
});