Estendendo elementos integrados

A especificação define elementos personalizados autônomos (que estendem HTMLElement e são usados como <my-card>) e elementos integrados personalizados (que estendem uma classe nativa específica e são usados como <button is="my-button">). Os elementos integrados personalizados herdam gratuitamente a semântica nativa.

Um <my-button> autônomo não recebe nenhum comportamento nativo de <button> — não é ativado com Enter ou Espaço, não participa de formulários e não fornece role="button" para tecnologias assistivas. Um botão personalizado (is="my-button") herda tudo isso automaticamente.

Estenda a classe HTML específica em vez de HTMLElement: class MyButton extends HTMLButtonElement {}. O elemento mantém todo o comportamento nativo — envio de formulários, gerenciamento do foco e estado desativado — e o senhor adiciona seus aprimoramentos por cima.

customElements.define("my-button", MyButton, { extends: "button" }). O terceiro argumento informa ao registro qual tag nativa o elemento estende. Sem esse argumento, o registro gera um erro.

Use elementos integrados personalizados com o atributo de identificação na tag existente: <button is="my-button">Click</button>. Escrever <my-button> criaria um elemento autônomo e faria o componente perder o comportamento nativo.

O Safari se recusou a implementar elementos integrados personalizados, alegando preocupações de acessibilidade. Eles funcionam no Chrome, Edge e Firefox; no Safari, o atributo is é ignorado e o elemento se comporta como um <button> comum. Use o preenchimento de compatibilidade oficial quando for necessário oferecer suporte ao Safari.

O preenchimento de compatibilidade @ungap/custom-elements restaura o suporte a elementos integrados personalizados no Safari. Ele é pequeno e bem mantido; inclua-o quando sua equipe precisar de suporte entre navegadores sem abandonar o padrão do atributo de identificação.

Se for importante oferecer suporte ao Safari sem um preenchimento de compatibilidade, crie um elemento autônomo e replique manualmente o comportamento necessário: adicione role="button", tabindex="0", manipuladores de teclado para Enter e Espaço e associação a formulários por meio do recurso ElementInternals.

Os elementos autônomos podem participar do envio de formulários definindo static formAssociated = true e usando this.attachInternals(). O objeto ElementInternals retornado fornece setFormValue e setValidity para uma integração completa com formulários.

Escolha elementos integrados personalizados para componentes que se comportam principalmente como um elemento nativo, como um botão aprimorado ou um campo de entrada inteligente, e quando sua plataforma de destino for Chrome/Firefox ou o senhor aceitar usar o preenchimento de compatibilidade. Escolha elementos autônomos para componentes totalmente novos, como cartões e caixas de diálogo, que não tenham um equivalente nativo.

O erro mais comum ao criar componentes web é criar <my-button> como um elemento autônomo. Ele não enviará formulários, não responderá a Enter ou Espaço e não será anunciado como um botão. Estenda HTMLButtonElement ou replique cuidadosamente todos os comportamentos de um botão real.

Qual é a vantagem prática de estender HTMLButtonElement, criando um elemento integrado personalizado, em vez de estender HTMLElement, criando um elemento autônomo, para um componente semelhante a um botão?

Os elementos integrados personalizados estendem uma classe HTML específica, como uma classe de botão ou de campo de entrada, e são usados por meio do atributo de identificação, herdando todo o comportamento nativo. Registre-os com a opção { extends: "button" }. O Safari não oferece suporte nativo a eles — use um preenchimento de compatibilidade ou elementos autônomos com replicação manual do comportamento quando for necessário oferecer suporte completo entre navegadores.