JavaScript Academy · Aula

Definindo elementos personalizados

Registre elementos com a API customElements.

Definindo elementos personalizados é uma aula grátis de JavaScript Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de JavaScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de JavaScript Academy inclui 4 aulas no total.

O que são elementos personalizados?

Elementos personalizados permitem definir suas próprias tags HTML respaldadas por classes JavaScript. Em vez de juntar uma confusão de elementos div, você cria um componente reutilizável e independente, como <user-card>.

Eles fazem parte do padrão Componentes da Web.
Eles funcionam nativamente nos navegadores, sem exigir uma estrutura de desenvolvimento.
O nome de um elemento personalizado deve conter um hífen (por exemplo, my-button).

O registro customElements

O navegador expõe um registro global em window.customElements. Registre uma nova tag chamando customElements.define(name, constructor).

Depois de definida, cada tag correspondente no documento é convertida em uma instância da sua classe.

// Register a tag named 'hello-world'
customElements.define('hello-world', HelloWorld);

// After this, every <hello-world> in the page
// becomes an instance of the HelloWorld class.

Estendendo HTMLElement

Um elemento personalizado é uma classe que usa extends HTMLElement. A classe base fornece ao elemento todos os recursos padrão do DOM (atributos, eventos e estilos).

Sempre chame super() primeiro no construtor para que o elemento seja inicializado corretamente.

class HelloWorld extends HTMLElement {
  constructor() {
    super(); // required, sets up the element
  }
}

customElements.define('hello-world', HelloWorld);

Renderizando conteúdo

Dentro do elemento, você pode definir this.innerHTML ou usar métodos do DOM para criar conteúdo. Um padrão comum é renderizar quando o elemento é conectado à página.

class HelloWorld extends HTMLElement {
  connectedCallback() {
    this.innerHTML = '<p>Hello from a custom element!</p>';
  }
}

customElements.define('hello-world', HelloWorld);

Usando o elemento em HTML

Depois do registro, use sua tag como usaria qualquer elemento nativo. Você pode inseri-la diretamente na marcação ou criá-la com document.createElement.

// In HTML:
// <hello-world></hello-world>

// Or in JavaScript:
const el = document.createElement('hello-world');
document.body.appendChild(el);

Regras do construtor

O construtor é executado quando uma instância é criada. Existem regras rigorosas:

Chame super() primeiro.
Não inspecione nem adicione atributos ou elementos filhos aqui.
Adie o trabalho com o DOM para connectedCallback.

Use o construtor apenas para definir o estado inicial e configurar ouvintes de eventos.

class CounterButton extends HTMLElement {
  constructor() {
    super();
    this.count = 0; // safe: just internal state
  }
}

customElements.define('counter-button', CounterButton);

Adicionando comportamento

Como seu elemento é um nó DOM real, você pode adicionar ouvintes de eventos e atualizar o conteúdo dele em resposta à interação.

class CounterButton extends HTMLElement {
  constructor() {
    super();
    this.count = 0;
  }
  connectedCallback() {
    this.textContent = 'Clicked 0 times';
    this.addEventListener('click', () => {
      this.count++;
      this.textContent = 'Clicked ' + this.count + ' times';
    });
  }
}
customElements.define('counter-button', CounterButton);

O requisito do hífen

Os nomes de elementos personalizados devem incluir um hífen. Isso garante que eles nunca entrem em conflito com elementos HTML integrados atuais ou futuros.

my-widget é válido.
mywidget é inválido e lança um erro.
Os nomes não diferenciam maiúsculas de minúsculas, mas são escritos em minúsculas.

// Valid:
customElements.define('app-header', AppHeader);

// Invalid - throws SyntaxError (no hyphen):
// customElements.define('appheader', AppHeader);

whenDefined e get

Dois métodos úteis do registro:

customElements.get(name) retorna o construtor ou undefined se não estiver registrado.
customElements.whenDefined(name) retorna uma Promise que é resolvida assim que o elemento é definido.

customElements.whenDefined('hello-world').then(() => {
  console.log('hello-world is ready to use');
});

const Ctor = customElements.get('hello-world');

Definindo apenas uma vez

Cada nome pode ser registrado apenas uma vez. Chamar define com um nome já usado lança um erro. Evite registros duplicados em módulos compartilhados.

if (!customElements.get('hello-world')) {
  customElements.define('hello-world', HelloWorld);
}

Por que os elementos personalizados são importantes

Os elementos personalizados oferecem uma interface de usuário independente de estrutura, encapsulada e reutilizável. Eles:

Padronizam a reutilização de componentes em qualquer pilha tecnológica.
Integram-se naturalmente ao ciclo de vida do navegador.
Combinam naturalmente com o DOM de sombra e os modelos, que serão abordados mais adiante.

Verificação rápida

Teste sua compreensão sobre a definição de elementos personalizados.

Recapitulação

Você aprendeu a definir elementos personalizados:

customElements.define(name, class) registra uma etiqueta.
A classe extends HTMLElement e chama super() primeiro.
Os nomes devem incluir um hífen.
Faça o render do conteúdo em connectedCallback, não no construtor.
get e whenDefined ajudam você a verificar o status do registro.

Em seguida, vamos explorar o ciclo de vida completo de um elemento personalizado.

Perguntas Frequentes

A aula “Definindo elementos personalizados” é grátis?

Sim — o texto completo de “Definindo elementos personalizados” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de JavaScript Academy, atualize para CoddyKit PRO. O curso de JavaScript Academy inclui 4 aulas no total.

O que vou aprender em “Definindo elementos personalizados”?

Registre elementos com a API customElements. Você pratica JavaScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar JavaScript Academy?

Nenhuma experiência prévia é necessária. JavaScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Definindo elementos personalizados”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de JavaScript Academy?

Sim. Cada aula de JavaScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para JavaScript Academy