Práticas recomendadas para elementos personalizados

Com os elementos personalizados, você pode criar suas próprias tags HTML. Esta lista de verificação abrange as práticas recomendadas para ajudar você a criar elementos de alta qualidade.

Com os elementos personalizados, você pode estender o HTML e definir suas próprias tags. Eles são incrivelmente eficiente, mas também são de baixo nível, o que significa que não são sempre claro a melhor forma de implementar seu próprio elemento.

Para ajudar você a criar as melhores experiências possíveis, reunimos esta lista de verificação. Ele detalha tudo que achamos que é preciso para ser um um elemento personalizado bem-comportado.

Lista de verificação

Shadow DOM

Atributos e propriedades

Eventos

Vídeos de explicação

Não substituir o autor da página

É possível que um desenvolvedor que use seu elemento queira modificar algumas o estado inicial dela. Por exemplo, mudar a role ARIA ou a capacidade de foco com tabindex. Verifique se esses e outros atributos globais foram definidos. antes de aplicar seus próprios valores.

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

Tornar as propriedades lentas

Um desenvolvedor pode tentar definir uma propriedade no seu elemento antes que o foi carregada. Isso é especialmente verdadeiro se o desenvolvedor estiver usando um que lida com o carregamento de componentes, inserindo-os na página e vinculando as propriedades a um modelo.

No exemplo a seguir, o Angular vincula de forma declarativa o isChecked à propriedade checked da caixa de seleção. Se a definição de a caixa de seleção de instruções foi carregada lentamente. É possível que o Angular tente definir a propriedade marcada antes do upgrade do elemento.

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

Um elemento personalizado deve lidar com esse cenário verificando se alguma propriedade tem já foi definido na instância. O <howto-checkbox> demonstra esse padrão usando um método chamado _upgradeProperty().

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

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

_upgradeProperty() captura o valor da instância não atualizada e exclui a propriedade para que ela não sombre o configurador de propriedades do próprio elemento personalizado. Dessa forma, quando a definição do elemento for finalmente carregada, ela poderá refletem o estado correto.

Evitar problemas de reentrada

É tentador usar attributeChangedCallback() para refletir o estado de uma propriedade subjacente, por exemplo:

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

Mas isso pode criar um loop infinito se o setter da propriedade também refletir o 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');
}

Uma alternativa é permitir que o setter da propriedade reflita o atributo, e faça com que o getter determine seu valor com base no atributo.

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

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

Nesse exemplo, a adição ou remoção do atributo também definirá a propriedade.

Por fim, o attributeChangedCallback() pode ser usado para processar efeitos colaterais como aplicar estados 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;
    ...
  }
}