Verwendung

Die Komponenten von mdui sind normale Web Components. Sie können mdui-Komponenten wie <div>-Tags verwenden. Die Dokumentation jeder Komponente beschreibt detailliert ihre vollständige API, einschließlich Attribute, Methoden, Ereignisse, Slots, CSS-Parts und CSS-Custom-Properties.

Dieses Kapitel führt Sie in die Verwendung von Web Components ein.

Attribute

Attribute werden in HTML-Attribute und JavaScript-Properties unterteilt. Sie entsprechen sich normalerweise und bleiben synchron. Das heißt, wenn Sie den Wert eines HTML-Attributs ändern, wird der Wert der JavaScript-Property ebenfalls aktualisiert, und umgekehrt.

HTML-Attribute können direkt im HTML-String der Komponente gesetzt und mit den Methoden getAttribute und setAttribute gelesen und geändert werden:

<mdui-button variant="text">Klick mich</mdui-button>

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

  // HTML-Attribut ändern
  button.setAttribute('variant', 'outlined');

  // HTML-Attribut lesen
  console.log(button.getAttribute('variant')); // outlined
</script>

JavaScript-Properties können direkt gelesen oder gesetzt werden, indem auf die Eigenschaften der Komponenteninstanz zugegriffen wird:

<mdui-button variant="text">Klick mich</mdui-button>

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

  // JavaScript-Property setzen
  button.variant = 'outlined';

  // JavaScript-Property lesen
  console.log(button.variant); // outlined
</script>

Einige Eigenschaftswerte sind vom Typ Boolean. Wenn das HTML-Attribut für diese Eigenschaften vorhanden ist, ist die JavaScript-Property true, andernfalls false. Aus Kompatibilitätsgründen mit bestimmten Frameworks wertet mdui den String false jedoch auch als Boolean-Wert false.

<!-- Diese Komponente hat das disabled-Attribut, d. h. der Standardwert von disabled ist true -->
<mdui-button disabled></mdui-button>

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

  button.removeAttribute('disabled'); // Äquivalent zu button.disabled = false;
  button.setAttribute('disabled', ''); // Äquivalent zu button.disabled = true;

  // Ausnahmefall: Das Setzen des Strings 'false' ist äquivalent zum Setzen des Boolean-Werts false
  button.setAttribute('disabled', 'false'); // Äquivalent zu button.disabled = false;
</script>

Manchmal sind Eigenschaftswerte Arrays, Objekte oder Funktionen. In diesem Fall gibt es nur die JavaScript-Property und kein entsprechendes HTML-Attribut. Beispielsweise ist die labelFormatter-Eigenschaft der <mdui-slider>-Komponente eine Funktion. Sie können diese Eigenschaft nur über JavaScript setzen:

<mdui-slider></mdui-slider>

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

Im Folgenden wird ein Teil der Eigenschaftsdokumentation der <mdui-slider>-Komponente als Beispiel erläutert:

Bei dieser Komponente gibt es für die Eigenschaft name sowohl ein HTML-Attribut als auch eine JavaScript-Property, und die Spalte reflect zeigt an, dass eine Aktualisierung der JavaScript-Property das HTML-Attribut synchron aktualisiert. Bei der Eigenschaft value wird beim Aktualisieren der JavaScript-Property das HTML-Attribut nicht aktualisiert. Die Eigenschaft labelFormatter hat nur eine JavaScript-Property.

Methoden

Einige Komponenten bieten öffentliche Methoden an, die Sie aufrufen können, um verschiedene Funktionen zu implementieren. Beispielsweise kann die focus()-Methode der <mdui-text-field>-Komponente das Textfeld fokussieren.

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

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

Sie können auf den Dokumentationsseiten der einzelnen Komponenten alle verfügbaren Methoden und deren Parameter einsehen.

Ereignisse

Einige Komponenten lösen Ereignisse aus, wenn bestimmte Aktionen ausgeführt werden. Beispielsweise löst die <mdui-dialog>-Komponente beim Öffnen das open-Ereignis aus. Sie können dieses Ereignis abhören, um benutzerdefinierte Aktionen auszuführen.

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

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

  dialog.addEventListener('open', () => {
    console.log('Das Ereignis wird ausgelöst, wenn der Dialog zu öffnen beginnt');
  });
</script>

Sie können auf den Dokumentationsseiten der einzelnen Komponenten alle verfügbaren Ereignisse und deren Parameter einsehen.

Wenn Sie mdui in anderen Frameworks (wie Vue, React, Angular usw.) verwenden, können Sie die vom Framework bereitgestellte Syntax zum Binden von Ereignissen verwenden. Einige Frameworks (wie React) können mit ihrer Ereignisbindungssyntax jedoch nur Standardereignisse (wie click) binden, nicht aber benutzerdefinierte Ereignisse (wie open). Daher müssen Sie beim Binden benutzerdefinierter Ereignisse in React zuerst eine Referenz auf das Element erhalten und dann die addEventListener-Methode verwenden, um das Ereignis zu binden.

Weitere Informationen zur Verwendung von mdui in React finden Sie unter Framework-Integration - React.

Slots

Viele Komponenten bieten Slots an, um benutzerdefinierte HTML-Inhalte in die Komponente einzufügen.

Der häufigste ist der Default-Slot. Es ist ein gewöhnlicher HTML- oder reiner Text innerhalb der Komponente. Beispielsweise wird der Default-Slot der <mdui-button>-Komponente verwendet, um den Text des Buttons festzulegen. Im Beispiel ist "Klick mich" der Inhalt des Default-Slots:

<mdui-button>Klick mich</mdui-button>

Einige Komponenten bieten auch benannte Slots an. Bei benannten Slots müssen Sie den Slot-Namen im HTML-slot-Attribut angeben. Im folgenden Beispiel gibt die <mdui-icon>-Komponente slot="start" an, was bedeutet, dass dies der benannte Slot start ist und dieses Symbol in den linken Bereich innerhalb der Komponente eingefügt wird:

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

Wenn eine Komponente mehrere benannte Slots verwendet, spielt die Reihenfolge der benannten Slots keine Rolle. Solange sie sich innerhalb der Komponente befinden, platziert der Browser sie automatisch an der richtigen Stelle.

Sie können auf den Dokumentationsseiten der einzelnen Komponenten alle unterstützten Slots einsehen.

CSS-Custom-Properties

CSS-Custom-Properties sind Variablen in CSS. mdui definiert eine Reihe von globalen CSS-Custom-Properties. Diese Eigenschaften werden innerhalb der Komponenten referenziert. Daher können Sie durch Ändern dieser CSS-Custom-Properties das Erscheinungsbild aller mdui-Komponenten global ändern.

Der folgende Code verkleinert beispielsweise die runden Ecken aller Komponenten:

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

Sie können CSS-Custom-Properties auch in einem lokalen Geltungsbereich ändern. Der folgende Code verkleinert beispielsweise die runden Ecken nur innerhalb des Elements mit der Klasse sharp und seinen untergeordneten Elementen:

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

Einige Komponenten bieten auch komponentenspezifische CSS-Custom-Properties an. Der Geltungsbereich dieser Eigenschaften ist auf die jeweilige Komponente beschränkt, daher enthalten sie nicht das Präfix --mdui. Der folgende Code ändert beispielsweise den z-index der <mdui-dialog>-Komponente, indem die Eigenschaft --z-index geändert wird:

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

Sie können auf den Dokumentationsseiten der einzelnen Komponenten die von der Komponente unterstützten CSS-Custom-Properties einsehen.

CSS-Parts

mdui-Komponenten verwenden Shadow DOM, um Stile und Verhalten zu kapseln, aber reguläre CSS-Selektoren können nicht auf Elemente im Shadow DOM zugreifen. Daher fügen einige Komponenten ihren Shadow-DOM-Elementen part-Attribute hinzu. Sie können den ::part-CSS-Selektor verwenden, um auf die entsprechenden Elemente zuzugreifen und Teile der Stile zu überschreiben.

Der folgende Code verwendet beispielsweise den button-Part, um den Innenabstand des Buttons zu ändern, und die label-, icon- und end-icon-Parts, um die Farben von Text, linkem und rechtem Symbol zu ändern:

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

Um die Struktur der Shadow-DOM-Elemente und die Standardstile einer Komponente zu verstehen, können Sie die Entwicklertools Ihres Browsers öffnen.

Bevor Sie CSS-Parts verwenden, sollten Sie prüfen, ob die Verwendung globaler CSS-Custom-Properties und komponentenspezifischer CSS-Custom-Properties Ihren Anforderungen genügt. Wenn dies der Fall ist, sollten Sie CSS-Custom-Properties priorisieren, um das Erscheinungsbild anzupassen.

Sie können auf den Dokumentationsseiten der einzelnen Komponenten alle öffentlichen part-Attribute der Komponente einsehen.

Aktualisierungsmechanismus von Komponenten

mdui-Komponenten basieren auf Lit. Lit ist eine leichtgewichtige Bibliothek, die die Entwicklung von Web Components erleichtert. Bei der Verwendung von mdui-Komponenten müssen Sie möglicherweise deren Rendering- und Aktualisierungsmechanismus verstehen.

Wenn Sie eine Eigenschaft einer mdui-Komponente ändern, wird die Komponente neu gerendert. Dieser Neu-Rendering-Prozess erfolgt jedoch nicht synchron. Wenn Sie mehrere Eigenschaftswerte gleichzeitig ändern, puffert Lit diese Änderungen bis zum nächsten Aktualisierungszyklus, um sicherzustellen, dass jede Komponente nur einmal neu gerendert wird, unabhängig davon, wie oft Sie Eigenschaftswerte ändern. Außerdem wird nur der Teil des Shadow DOM, der sich geändert hat, neu gerendert.

Im folgenden Beispiel setzen wir die disabled-JavaScript-Property des Buttons auf true und fragen dann sofort sein HTML-Attribut ab. Da die Komponente zu diesem Zeitpunkt noch nicht neu gerendert wurde, ist das abgefragte HTML-Attribut immer noch false:

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

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

Um zu warten, bis das Neu-Rendering nach einer Eigenschaftsänderung abgeschlossen ist, können Sie die updateComplete-Eigenschaft der Komponente verwenden. Diese Eigenschaft gibt ein Promise zurück. Sobald das Promise aufgelöst ist, ist das Neu-Rendering der Komponente abgeschlossen:

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

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