Prácticas recomendadas para los elementos personalizados

Los elementos personalizados te permiten crear tus propias etiquetas HTML. Esta lista de tareas abarca prácticas recomendadas para ayudarte a crear elementos de alta calidad.

Los elementos personalizados te permiten extender el código HTML y definir tus propias etiquetas. Son un función increíblemente potente, pero también son de bajo nivel, lo que significa que no es siempre esté claro cuál es la mejor manera de implementar tu propio elemento.

Para ayudarte a crear las mejores experiencias posibles, reunimos esta lista de tareas. Desglosa todo lo que creemos que hace falta elemento personalizado con buen comportamiento.

Lista de tareas

Shadow DOM

Atributos y propiedades

Eventos

Explicaciones

No anular el autor de la página

Es posible que un desarrollador que usa tu elemento quiera anular algunos de a su estado inicial. Por ejemplo, cambiar su role de ARIA o la enfocabilidad con tabindex Verifica si se establecieron estos y otros atributos globales. antes de aplicar tus propios valores.

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

Haz que las propiedades sean diferidas

Un desarrollador puede intentar establecer una propiedad en tu elemento antes de su se cargó la definición. Esto es especialmente cierto si el desarrollador usa un framework que controla la carga de componentes, su inserción en la página y que vinculan sus propiedades a un modelo.

En el siguiente ejemplo, Angular vincula declarativamente los atributos la propiedad isChecked a la propiedad checked de la casilla de verificación. Si la definición de la casilla de verificación del instructivo se cargó de forma diferida, es posible que Angular intente configurar la propiedad marcada antes de que se actualice el elemento.

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

Un elemento personalizado debería manejar esta situación verificando si alguna propiedad tiene ya se establecieron en su instancia. La <howto-checkbox> demuestra este patrón mediante un método llamado _upgradeProperty().

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

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

_upgradeProperty() captura el valor de la instancia no actualizada y borra la propiedad para que no oculte el propio establecedor de propiedades del elemento personalizado. De esta manera, cuando finalmente se carga la definición del elemento, puede reflejan el estado correcto.

Evita problemas de reentrada

Resulta tentador usar attributeChangedCallback() para reflejar el estado en un propiedad subyacente, por ejemplo:

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

Pero esto puede crear un bucle infinito si el establecedor de propiedades también se refleja en el atributo.

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');
}

Una alternativa es permitir que el establecedor de propiedades se refleje en el atributo. el método get determine su valor según el atributo.

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

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

En este ejemplo, agregar o quitar el atributo también establecerá la propiedad.

Por último, attributeChangedCallback() se puede usar para controlar efectos secundarios como aplicar estados de 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;
    ...
  }
}