Rychlý start

Všechny komponenty mdui jsou standardní Web Components. Komponenty mdui můžete používat stejně jako značku <div>. Dokumentace každé komponenty podrobně popisuje její kompletní API, včetně atributů, metod, událostí, slotů, CSS Partů, CSS Custom Property atd.

Tato kapitola shrnuje, jak Web Components používat.

Atributy

Atributy se dělí na HTML atributy a JavaScript vlastnosti. Obvykle jsou v párovém vztahu a jsou synchronizovány. To znamená, že když aktualizujete hodnotu HTML atributu, aktualizuje se také odpovídající JavaScript vlastnost a naopak.

HTML atributy lze nastavit přímo v HTML řetězci komponenty a číst a upravovat je pomocí metod getAttribute a setAttribute:

<mdui-button variant="text">Klikněte na mě</mdui-button>

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

  // Úprava HTML atributu
  button.setAttribute('variant', 'outlined');

  // Čtení HTML atributu
  console.log(button.getAttribute('variant')); // outlined
</script>

JavaScript vlastnosti lze číst nebo nastavovat přímo na instanci komponenty:

<mdui-button variant="text">Klikněte na mě</mdui-button>

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

  // Nastavení JavaScript vlastnosti
  button.variant = 'outlined';

  // Čtení JavaScript vlastnosti
  console.log(button.variant); // outlined
</script>

Některé vlastnosti jsou typu boolean. Pokud je HTML atribut těchto vlastností přítomen, je JavaScript vlastnost true, jinak je false. Aby však byla zajištěna kompatibilita s některými frameworky, mdui považuje řetězcovou hodnotu false také za boolean hodnotu false.

<!-- Tato komponenta má atribut disabled, což znamená, že výchozí hodnota atributu disabled je true -->
<mdui-button disabled></mdui-button>

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

  button.removeAttribute('disabled'); // ekvivalent button.disabled = false;
  button.setAttribute('disabled', ''); // ekvivalent button.disabled = true;

  // Výjimka: nastavení řetězcové hodnoty false je ekvivalentní nastavení boolean hodnoty false
  button.setAttribute('disabled', 'false'); // ekvivalent button.disabled = false;
</script>

Někdy jsou hodnotami vlastností pole, objekty nebo funkce. V takovém případě existuje pouze JavaScript vlastnost a žádný odpovídající HTML atribut. Například vlastnost labelFormatter komponenty <mdui-slider> je funkce, kterou lze nastavit pouze pomocí JavaScriptu:

<mdui-slider></mdui-slider>

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

Níže je uveden příklad části dokumentace vlastností komponenty <mdui-slider>:

U této komponenty má vlastnost name jak HTML atribut, tak JavaScript vlastnost a sloupec reflect označuje, že aktualizace JavaScript vlastnosti synchronizuje HTML atribut. U vlastnosti value se při aktualizaci JavaScript vlastnosti HTML atribut nesynchronizuje. Vlastnost labelFormatter má pouze JavaScript vlastnost.

Metody

Některé komponenty poskytují veřejné metody, které můžete volat k dosažení různých funkcí. Například metoda focus() komponenty <mdui-text-field> umožňuje zaměřit textové pole.

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

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

Na stránkách dokumentace jednotlivých komponent naleznete všechny dostupné metody a jejich parametry.

Události

Některé komponenty při provádění určitých akcí spouštějí události. Například komponenta <mdui-dialog> při otevření spouští událost open. Na tuto událost můžete naslouchat a provádět vlastní akce.

<mdui-dialog>Dialog</mdui-dialog>

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

  dialog.addEventListener('open', () => {
    console.log('Tato událost se spustí při otevření dialogu');
  });
</script>

Na stránkách dokumentace jednotlivých komponent naleznete všechny dostupné události a jejich parametry.

Pokud používáte mdui v jiných frameworkách (např. Vue, React, Angular), můžete k navázání událostí použít syntaxi poskytovanou daným frameworkem. Některé frameworky (např. React) však mohou mít syntaxi pro navázání událostí pouze pro standardní události (např. click), nikoli pro vlastní události (např. open). Proto při navazování vlastních událostí v Reactu musíte nejprve získat referenci na prvek a poté použít metodu addEventListener k navázání události.

Další informace o používání mdui v Reactu naleznete v části Integrace s frameworky - React.

Slot

Mnoho komponent poskytuje sloty pro vložení vlastního HTML obsahu do vnitřku komponenty.

Nejčastější je výchozí slot, což je běžný HTML nebo prostý text uvnitř komponenty. Například výchozí slot komponenty <mdui-button> slouží k nastavení textu tlačítka. V příkladu je "Klikněte na mě" obsahem výchozího slotu:

<mdui-button>Klikněte na mě</mdui-button>

Některé komponenty také poskytují pojmenované sloty. U pojmenovaných slotů je nutné v HTML atributu slot zadat název slotu. V následujícím příkladu komponenta <mdui-icon> určuje slot="start", což znamená, že se jedná o pojmenovaný slot s názvem start, a tato ikona bude vložena na levou stranu vnitřku komponenty:

<mdui-button>
  <mdui-icon slot="start" name="settings"></mdui-icon>
  Nastavení
</mdui-button>

Pokud komponenta používá více pojmenovaných slotů, pořadí jednotlivých pojmenovaných slotů není důležité, pokud jsou uvnitř komponenty, prohlížeč je automaticky umístí na správná místa.

Na stránkách dokumentace jednotlivých komponent naleznete všechny podporované sloty.

CSS Custom Property

CSS Custom Property jsou proměnné v CSS. mdui definuje řadu globálních CSS Custom Property, které jsou odkazovány uvnitř jednotlivých komponent. Proto můžete úpravou těchto CSS Custom Property globálně měnit styly komponent mdui.

Například následující kód zmenší zaoblení rohů všech komponent:

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

CSS Custom Property můžete také upravovat v lokálním rozsahu. Například následující kód zmenší zaoblení rohů pouze v prvku s class="sharp" a jeho potomcích:

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

Některé komponenty také poskytují CSS Custom Property specifické pro danou komponentu. Rozsah těchto vlastností je omezen na konkrétní komponentu, a proto neobsahují předponu --mdui. Například následující kód pomocí úpravy vlastnosti --z-index komponenty <mdui-dialog> mění styl z-index:

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

Na stránkách dokumentace jednotlivých komponent naleznete CSS Custom Property podporované danou komponentou.

CSS Part

Komponenty mdui používají shadow DOM k zapouzdření stylů a chování, ale běžné CSS selektory nemohou vybrat prvky uvnitř shadow DOM. Proto některé komponenty přidávají atribut part prvkům shadow DOM. Pomocí selektoru ::part můžete vybrat odpovídající prvek a přepsat část stylů.

Například následující kód pomocí part button upravuje vnitřní odsazení tlačítka a pomocí part label, icon, end-icon upravuje barvu textu a levé/pravé ikony:

<mdui-button class="custom-button" icon="explore" end-icon="flight">Tlačítko</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>

Strukturu prvků shadow DOM komponenty a jejich výchozí styly můžete zobrazit pomocí vývojářských nástrojů prohlížeče.

Před použitím CSS Part byste měli nejprve zvážit, zda vaše potřeby splňují globální CSS Custom Property a CSS Custom Property specifické pro danou komponentu. Pokud ano, měli byste upřednostnit použití CSS Custom Property pro přizpůsobení stylů.

Na stránkách dokumentace jednotlivých komponent naleznete všechny vlastnosti part, které komponenta zpřístupňuje.

Mechanismus aktualizace komponenty

Komponenty mdui jsou vyvinuty na základě Lit. Lit je lehká knihovna, která zjednodušuje vývoj Web Components. Při používání komponent mdui možná budete potřebovat znát mechanismus jejich vykreslování a aktualizace.

Když upravíte vlastnost komponenty mdui, komponenta se znovu vykreslí. Tento proces opětovného vykreslování však není synchronní. Když upravíte více hodnot vlastností najednou, Lit tyto změny uloží do vyrovnávací paměti až do dalšího cyklu aktualizace, aby se zajistilo, že bez ohledu na to, kolikrát upravíte hodnoty vlastností, se každá komponenta vykreslí pouze jednou. Navíc se znovu vykreslí pouze změněné části shadow DOM.

V následujícím příkladu nastavíme JavaScript vlastnost disabled tlačítka na true a poté okamžitě vyhledáme jeho HTML atribut. Protože však komponenta ještě nebyla znovu vykreslena, bude nalezený HTML atribut stále false:

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

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

Chcete-li počkat na dokončení opětovného vykreslení po změně hodnoty vlastnosti, můžete použít vlastnost updateComplete komponenty. Tato vlastnost vrací Promise. Když je Promise vyřešen (resolve), komponenta dokončila opětovné vykreslení:

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

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