Guida rapida

I componenti mdui, come standard Web Component, possono essere usati come elementi <div>. La documentazione di ciascun componente fornisce un'API completa, inclusi attributi, metodi, eventi, slot, CSS Part e Proprietà CSS personalizzate.

Questa guida si concentra sull'utilizzo dei Web Component.

Attributi

Gli attributi sono divisi in attributi HTML e Proprietà JavaScript. Di solito corrispondono uno a uno e sono sincronizzati. Ciò significa che l'aggiornamento del valore di un Attributo HTML aggiorna anche il valore della proprietà JavaScript e viceversa.

Gli attributi HTML possono essere impostati direttamente nella stringa HTML del componente. Possono essere letti o modificati utilizzando i metodi getAttribute e setAttribute:

<mdui-button variant="text">Cliccami</mdui-button>

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

  // Modifica l'Attributo HTML
  button.setAttribute('variant', 'outlined');

  // Legge l'Attributo HTML
  console.log(button.getAttribute('variant')); // outlined
</script>

Le proprietà JavaScript possono essere accessibili direttamente sull'istanza del componente o impostate per modificare il valore della proprietà:

<mdui-button variant="text">Cliccami</mdui-button>

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

  // Imposta la proprietà JavaScript
  button.variant = 'outlined';

  // Legge la proprietà JavaScript
  console.log(button.variant); // outlined
</script>

Gli attributi booleani corrispondono a Proprietà JavaScript che sono true quando l'Attributo HTML è presente e false altrimenti. Tuttavia, mdui tratta il valore stringa false come il valore booleano false per la compatibilità con alcuni framework.

<!-- Questo componente ha l'Attributo disabled, quindi la proprietà disabled è true per impostazione predefinita -->
<mdui-button disabled></mdui-button>

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

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

  // Eccezione: impostare sul valore stringa "false" equivale a impostare sul valore booleano false
  button.setAttribute('disabled', 'false'); // Equivalente a button.disabled = false;
</script>

Per le proprietà che sono array, oggetti o funzioni, esiste solo una Proprietà JavaScript; non esiste un Attributo HTML corrispondente. Ad esempio, la proprietà labelFormatter del componente <mdui-slider> è una funzione, che può essere impostata solo utilizzando la proprietà JavaScript:

<mdui-slider></mdui-slider>

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

Ecco un esempio dalla documentazione degli attributi del componente <mdui-slider>:

L'attributo name di questo componente ha sia proprietà HTML che JavaScript, e la colonna rifletti indica che se la proprietà JavaScript viene aggiornata, verrà aggiornato anche l'Attributo HTML. Tuttavia, l'attributo value non riflette le modifiche dalla proprietà JavaScript all'Attributo HTML. La proprietà labelFormatter esiste solo come proprietà JavaScript.

Metodi

I componenti forniscono metodi pubblici che attivano comportamenti specifici. Ad esempio, il metodo focus() del componente <mdui-text-field> imposta il focus sul campo di testo.

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

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

Consulta la documentazione di ciascun componente per un elenco completo di metodi e parametri.

Eventi

I componenti emettono eventi in risposta ad azioni specifiche. Ad esempio, il componente <mdui-dialog> emette un evento open quando inizia ad aprirsi. Questi eventi possono essere ascoltati, consentendo l'esecuzione di azioni personalizzate.

<mdui-dialog>Dialogo</mdui-dialog>

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

  dialog.addEventListener('open', () => {
    console.log('Questo evento viene attivato quando il dialogo inizia ad aprirsi');
  });
</script>

Un elenco completo di eventi e dei loro parametri per ciascun componente può essere trovato nelle rispettive pagine di documentazione.

Quando si integra mdui con altri framework come Vue, React o Angular, è possibile utilizzare la sintassi del framework per associare gli eventi. Tuttavia, alcuni framework, come React, potrebbero supportare solo eventi standard come click e non eventi personalizzati come open. In questi casi, potrebbe essere necessario associare manualmente l'evento utilizzando addEventListener ottenendo un riferimento all'elemento.

Per ulteriori informazioni sull'utilizzo di mdui con React, consultare la sezione Framework - React.

Slot

I componenti spesso forniscono slot per l'inserimento di contenuto HTML personalizzato.

Lo slot predefinito è il più comune, utilizzato per HTML semplice o testo all'interno del componente. Ad esempio, lo slot predefinito del componente <mdui-button> imposta il testo del pulsante:

<mdui-button>Cliccami</mdui-button>

Alcuni componenti offrono anche slot nominati. Dovresti specificare il nome dello slot nell'Attributo HTML slot. Ad esempio, il componente <mdui-icon> utilizza slot="start" per indicare uno slot nominato chiamato start, posizionando l'icona a sinistra all'interno del componente:

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

Per i componenti con più slot nominati, l'ordine non ha importanza. Devono solo essere all'interno del componente e il browser li posizionerà automaticamente nelle posizioni corrette.

Consulta la documentazione di ciascun componente per un elenco degli slot supportati.

Proprietà CSS Personalizzate

mdui utilizza le proprietà CSS Personalizzate, note anche come variabili CSS, per stabilire una serie di design tokens globali. Questi token vengono referenziati da vari componenti, consentendo di regolare gli stili dei componenti mdui a livello globale.

Ad esempio, puoi ridurre il raggio d'angolo di tutti i componenti modificando le relative Proprietà CSS personalizzate:

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

Le proprietà CSS personalizzate possono anche essere modificate all'interno di un ambito locale. Ad esempio, puoi ridurre il raggio d'angolo per gli elementi con class="sharp" e i loro elementi figli impostando le appropriate Proprietà CSS personalizzate:

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

Alcuni componenti forniscono anche Proprietà CSS personalizzate uniche. Queste sono limitate a componenti specifici e non includono il prefisso --mdui. Ad esempio, puoi modificare lo stile z-index del componente <mdui-dialog> modificando la sua Proprietà --z-index.

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

Consulta la documentazione di ciascun componente per un elenco delle proprietà CSS personalizzate supportate.

CSS Part

I componenti mdui utilizzano il shadow DOM per incapsulare stili e comportamenti. Tuttavia, i selettori CSS standard non possono selezionare elementi all'interno del shadow DOM. Per superare questo, alcuni componenti aggiungono un Attributo part agli elementi all'interno del shadow DOM. Questi elementi possono quindi essere selezionati e stilizzati utilizzando il selettore CSS ::part.

Ad esempio, la CSS Part button modifica il padding interno del pulsante, mentre le CSS Part label, icon e end-icon regolano rispettivamente il colore del testo, il colore dell'icona sinistra e il colore dell'icona destra:

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

Puoi ispezionare gli elementi del shadow DOM dei componenti negli strumenti di sviluppo del tuo browser per vedere la loro struttura e gli stili predefiniti.

Prima di utilizzare CSS Part, verifica se le proprietà CSS personalizzate globali o le proprietà CSS personalizzate specifiche del componente coprono già le tue esigenze. Se lo fanno, preferiscile per la personalizzazione dello stile.

Per un elenco delle proprietà part esposte pubblicamente, consulta la documentazione di ciascun componente.

Meccanismo di Aggiornamento del Componente

I componenti mdui sono costruiti utilizzando Lit, una libreria leggera che semplifica lo sviluppo di Web Component. Comprendere il meccanismo di rendering e aggiornamento dei componenti può migliorare la tua esperienza quando utilizzi i componenti mdui.

Quando modifichi le proprietà dei componenti mdui, i componenti eseguiranno nuovamente il rendering. Tuttavia, questo nuovo rendering non è sincrono. Quando più valori di Proprietà cambiano contemporaneamente, Lit raggruppa queste modifiche fino al ciclo di aggiornamento successivo. Questo approccio garantisce che ogni componente venga riproposto una sola volta, indipendentemente da quante Proprietà cambiano. Solo le parti del shadow DOM che effettivamente cambiano verranno riproposte.

Nell'esempio seguente, impostiamo la proprietà JavaScript disabled di un pulsante su true e interroghiamo immediatamente il suo Attributo HTML. Tuttavia, il componente non ha ancora avuto la possibilità di riproporsi, quindi l'Attributo HTML interrogato rimane false:

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

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

Per assicurarsi che un componente abbia completato il nuovo rendering dopo una modifica del valore della proprietà, puoi utilizzare la proprietà updateComplete. Questa Proprietà restituisce una Promise che si risolve una volta che il componente ha terminato il nuovo rendering.

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

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