Best practice per elementi personalizzati

Gli elementi personalizzati ti consentono di creare tag HTML personalizzati. Questo elenco di controllo illustra le best practice per aiutarti a creare elementi di alta qualità.

Gli elementi personalizzati ti consentono di estendere l'HTML e definire i tuoi tag. È un funzione incredibilmente potente, ma sono anche di basso livello, il che significa che sempre chiaro il modo migliore per implementare il proprio elemento.

Per aiutarti a creare le migliori esperienze possibili, abbiamo creato questa presentazione elenco di controllo. Suddivide tutte le cose che pensiamo siano necessarie per un elemento personalizzato ben gestito.

Elenco di controllo

DOM shadow

Attributi e proprietà

Eventi

Video esplicativi

Non sostituire l'autore della pagina

È possibile che uno sviluppatore che utilizza il tuo elemento voglia eseguire l'override di allo stato iniziale. Ad esempio, la modifica dell'ARIA role o della regolabilità con tabindex. Controlla se questi e altri attributi globali sono stati impostati, prima di applicare i tuoi valori.

connectedCallback() {
  if (!this.hasAttribute('role'))
    this.setAttribute('role', 'checkbox');
  if (!this.hasAttribute('tabindex'))
    this.setAttribute('tabindex', 0);

Rendi le proprietà lazy

Uno sviluppatore potrebbe tentare di impostare una proprietà sull'elemento prima che la definizione è stata caricata. Ciò è particolarmente vero se lo sviluppatore utilizza una che gestisce il caricamento dei componenti, inserendoli nella pagina associando le proprie proprietà a un modello.

Nell'esempio seguente, Angular sta associando in modo dichiarativo il valore isChecked alla proprietà checked della casella di controllo. Se la definizione di la casella di controllo "howto" è stata caricata tramite caricamento lento. È possibile che Angular provi a impostare la proprietà selezionata prima dell'upgrade dell'elemento.

<howto-checkbox [checked]="defaults.isChecked"></howto-checkbox>

Un elemento personalizzato dovrebbe gestire questo scenario controllando se alcune proprietà hanno è già stato impostato sulla sua istanza. La <howto-checkbox> dimostra questo pattern utilizzando un metodo chiamato _upgradeProperty().

connectedCallback() {
  ...
  this._upgradeProperty('checked');
}

_upgradeProperty(prop) {
  if (this.hasOwnProperty(prop)) {
    let value = this[prop];
    delete this[prop];
    this[prop] = value;
  }
}

_upgradeProperty() acquisisce il valore dell'istanza di cui non è stato eseguito l'upgrade ed elimina la proprietà in modo che non esegua lo shadowing del setter delle proprietà dell'elemento personalizzato. In questo modo, quando la definizione dell'elemento viene caricata, può immediatamente che riflettano lo stato corretto.

Evita problemi di rientro

Si può avere la tentazione di usare attributeChangedCallback() per riflettere lo stato in una proprietà sottostante, ad esempio:

// When the [checked] attribute changes, set the checked property to match.
attributeChangedCallback(name, oldValue, newValue) {
  if (name === 'checked')
    this.checked = newValue;
}

Questo può creare un ciclo infinito se il setter delle proprietà riflette anche l'attributo.

set checked(value) {
  const isChecked = Boolean(value);
  if (isChecked)
    // OOPS! This will cause an infinite loop because it triggers the
    // attributeChangedCallback() which then sets this property again.
    this.setAttribute('checked', '');
  else
    this.removeAttribute('checked');
}

Un'alternativa è consentire al setter della proprietà di riflettere sull'attributo e fare in modo che il getter determini il proprio valore in base all'attributo.

set checked(value) {
  const isChecked = Boolean(value);
  if (isChecked)
    this.setAttribute('checked', '');
  else
    this.removeAttribute('checked');
}

get checked() {
  return this.hasAttribute('checked');
}

In questo esempio, l'aggiunta o la rimozione dell'attributo stabilirà anche la proprietà.

Infine, puoi usare attributeChangedCallback() per gestire gli effetti collaterali come l'applicazione degli stati ARIA.

attributeChangedCallback(name, oldValue, newValue) {
  const hasValue = newValue !== null;
  switch (name) {
    case 'checked':
      // Note the attributeChangedCallback is only handling the *side effects*
      // of setting the attribute.
      this.setAttribute('aria-checked', hasValue);
      break;
    ...
  }
}