Szybki start

Komponenty mdui to standardowe Web Components. Możesz ich używać jak znaczników <div>. Dokumentacja każdego komponentu zawiera pełny opis API: właściwości, metody, zdarzenia, sloty, CSS Part, niestandardowe właściwości CSS itp.

Ten rozdział omawia podstawy korzystania z Web Components.

Atrybuty

Atrybuty dzielą się na atrybuty HTML i właściwości JavaScript. Zazwyczaj są one ze sobą zsynchronizowane: gdy zmienisz wartość atrybutu HTML, zmieni się też właściwość JavaScript i odwrotnie.

Atrybuty HTML można ustawić bezpośrednio w ciągu HTML komponentu, a następnie odczytywać i modyfikować za pomocą getAttribute i setAttribute:

<mdui-button variant="text">Kliknij mnie</mdui-button>

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

  // Modyfikacja atrybutu HTML
  button.setAttribute('variant', 'outlined');

  // Odczyt atrybutu HTML
  console.log(button.getAttribute('variant')); // outlined
</script>

Właściwości JavaScript można bezpośrednio odczytywać lub ustawiać na instancji komponentu:

<mdui-button variant="text">Kliknij mnie</mdui-button>

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

  // Ustawienie właściwości JavaScript
  button.variant = 'outlined';

  // Odczyt właściwości JavaScript
  console.log(button.variant); // outlined
</script>

Niektóre właściwości mają typ logiczny (boolean). Dla nich obecność atrybutu HTML oznacza true, brak – false. Dla zgodności z niektórymi frameworkami, mdui traktuje również ciąg "false" jako wartość logiczną false.

<!-- Ten komponent ma atrybut disabled, czyli domyślnie disabled=true -->
<mdui-button disabled></mdui-button>

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

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

  // Wyjątek: ustawienie ciągu "false" jest równoznaczne z false
  button.setAttribute('disabled', 'false'); // odpowiednik button.disabled = false;
</script>

Czasami właściwością może być tablica, obiekt lub funkcja. Wtedy istnieje tylko właściwość JavaScript, bez odpowiadającego atrybutu HTML. Przykładowo, w komponencie <mdui-slider> właściwość labelFormatter jest funkcją i można ją ustawić tylko przez JavaScript:

<mdui-slider></mdui-slider>

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

Poniżej fragment dokumentacji <mdui-slider> dla przykładu:

Dla name istnieją zarówno atrybut HTML, jak i właściwość JavaScript, a kolumna reflect wskazuje, że zmiana właściwości JavaScript zaktualizuje atrybut HTML. Dla value zmiana właściwości JavaScript nie aktualizuje atrybutu HTML. labelFormatter ma tylko właściwość JavaScript.

Metody

Niektóre komponenty udostępniają publiczne metody. Możesz je wywołać, aby uzyskać różne funkcjonalności. Na przykład metoda focus() komponentu <mdui-text-field> pozwala ustawić fokus na polu tekstowym.

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

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

W dokumentacji każdego komponentu znajdziesz wszystkie dostępne metody i ich parametry.

Zdarzenia

Niektóre komponenty podczas wykonywania określonych akcji wyzwalają zdarzenia. Na przykład komponent <mdui-dialog> wyzwala zdarzenie open podczas otwierania. Możesz nasłuchiwać tego zdarzenia, aby wykonać własne akcje.

<mdui-dialog>Okno dialogowe</mdui-dialog>

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

  dialog.addEventListener('open', () => {
    console.log('Zdarzenie wywołane na początku otwierania okna dialogowego');
  });
</script>

W dokumentacji każdego komponentu znajdziesz wszystkie dostępne zdarzenia i ich parametry.

Jeśli używasz mdui w innych frameworkach (Vue, React, Angular), możesz używać składni frameworka do wiązania zdarzeń. Jednak niektóre frameworki (np. React) pozwalają na wiązanie tylko standardowych zdarzeń (np. click), a nie niestandardowych (jak open). Dlatego w React, aby związać niestandardowe zdarzenie, musisz najpierw pobrać referencję do elementu i użyć addEventListener.

Więcej informacji o używaniu mdui z React znajdziesz w sekcji Integracja z frameworkami - React.

Slot

Wiele komponentów udostępnia sloty, które umożliwiają wstawienie własnej treści HTML do wnętrza komponentu.

Najczęściej spotykany jest slot domyślny – zwykły HTML lub zwykły tekst wewnątrz komponentu. Na przykład domyślny slot komponentu <mdui-button> służy do ustawienia tekstu przycisku. W przykładzie „Kliknij mnie” to zawartość slotu domyślnego:

<mdui-button>Kliknij mnie</mdui-button>

Niektóre komponenty mają również sloty nazwane. Dla slotu nazwanego należy podać atrybut slot z odpowiednią nazwą. W poniższym przykładzie komponent <mdui-icon> ma slot="start", co oznacza, że jest to slot nazwany start – ta ikona zostanie wstawiona do lewej strony wewnątrz przycisku:

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

Jeśli komponent używa wielu slotów nazwanych, kolejność ich umieszczenia nie ma znaczenia – przeglądarka automatycznie umieści je we właściwych miejscach.

W dokumentacji każdego komponentu znajdziesz wszystkie obsługiwane sloty.

Niestandardowe właściwości CSS

Niestandardowe właściwości CSS to zmienne w CSS. mdui definiuje szereg globalnych niestandardowych właściwości CSS, które służą wewnątrz komponentów. Dzięki temu możesz modyfikować te właściwości, aby globalnie zmienić style komponentów mdui.

Na przykład poniższy kod zmniejsza zaokrąglenia rogów wszystkich komponentów:

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

Możesz też modyfikować te właściwości w lokalnym zakresie. Poniższy kod zmniejszy zaokrąglenia tylko dla elementu z klasą sharp i jego dzieci:

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

Niektóre komponenty udostępniają również własne, niestandardowe właściwości CSS, które działają tylko dla danego komponentu i nie mają przedrostka --mdui. Na przykład poniższy kod zmienia właściwość --z-index dla komponentu <mdui-dialog>:

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

W dokumentacji każdego komponentu znajdziesz obsługiwane przez niego niestandardowe właściwości CSS.

CSS Part

Komponenty mdui używają shadow DOM do enkapsulacji stylów i zachowań. Zwykłe selektory CSS nie mogą wybrać elementów wewnątrz shadow DOM. Dlatego niektóre komponenty dodają atrybut part do elementów w shadow DOM. Możesz użyć selektora ::part, aby wybrać te elementy i nadpisać część stylów.

Na przykład poniższy kod używa parta button do zmiany wewnętrznego odstępu przycisku, a partów label, icon, end-icon do zmiany koloru tekstu i ikon:

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

Strukturę elementów shadow DOM i ich domyślne style możesz podejrzeć w narzędziach deweloperskich przeglądarki.

Zanim użyjesz CSS Part, zastanów się, czy globalne lub lokalne niestandardowe właściwości CSS nie spełnią twoich potrzeb. Jeśli tak, to preferuj je do dostosowywania stylów.

W dokumentacji każdego komponentu znajdziesz wszystkie publiczne part.

Mechanizm aktualizacji komponentów

Komponenty mdui są oparte na Lit. Lit to lekka biblioteka ułatwiająca tworzenie Web Components. Podczas korzystania z komponentów mdui warto znać mechanizm renderowania i aktualizacji.

Gdy zmienisz właściwość komponentu mdui, komponent zostanie ponownie wyrenderowany. Jednak to ponowne renderowanie nie jest synchroniczne. Kiedy zmienisz wiele właściwości jednocześnie, Lit buforuje te zmiany do następnego cyklu aktualizacji, dzięki czemu niezależnie od liczby zmian, każdy komponent renderuje się tylko raz. Ponadto renderowane są tylko te części shadow DOM, które uległy zmianie.

W poniższym przykładzie ustawiamy właściwość JavaScript disabled przycisku na true, a następnie od razu odczytujemy atrybut HTML. Ponieważ komponent nie został jeszcze ponownie wyrenderowany, odczytany atrybut HTML nadal będzie false:

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

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

Aby poczekać na zakończenie ponownego renderowania po zmianie właściwości, możesz użyć właściwości updateComplete komponentu. Zwraca ona Promise, który zostanie rozwiązany po zakończeniu renderowania:

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

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