JavaScript Academy · Lección

Definición de elementos personalizados

Registre elementos con la API customElements.

Definición de elementos personalizados es una lección gratuita de JavaScript Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de JavaScript Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de JavaScript Academy incluye 4 lecciones en total.

¿Qué son los elementos personalizados?

Los elementos personalizados permiten definir sus propias etiquetas HTML respaldadas por clases de JavaScript. En lugar de ensamblar una maraña de div, puede crear un componente reutilizable y autónomo como <user-card>.

Forman parte del estándar Web Components.
Funcionan de forma nativa en los navegadores, sin necesidad de un framework.
El nombre de un elemento personalizado debe contener un guion (por ejemplo, my-button).

El registro de customElements

El navegador expone un registro global en window.customElements. Registre una etiqueta nueva llamando a customElements.define(name, constructor).

Una vez definida, cada etiqueta coincidente del documento se actualiza y se convierte en una instancia de su clase.

// 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.

Extensión de HTMLElement

Un elemento personalizado es una clase que extends HTMLElement. La clase base proporciona a su elemento todas las capacidades estándar del DOM (atributos, eventos y estilos).

Llame siempre primero a super() en el constructor para que el elemento se inicialice correctamente.

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

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

Renderización del contenido

Dentro del elemento puede establecer this.innerHTML o usar métodos del DOM para crear el contenido. Un patrón habitual consiste en renderizar cuando el elemento se conecta a la página.

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

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

Uso del elemento en HTML

Después de registrarla, use su etiqueta como cualquier elemento integrado. Puede colocarla directamente en el marcado o crearla con document.createElement.

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

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

Reglas del constructor

El constructor se ejecuta cuando se crea una instancia. Existen reglas estrictas:

Llame primero a super().
No inspeccione ni añada atributos o elementos secundarios aquí.
Posponga el trabajo con el DOM a connectedCallback.

Use el constructor únicamente para establecer el estado inicial y configurar los detectores de eventos.

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

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

Añadir comportamiento

Como su elemento es un nodo DOM real, puede asociarle escuchadores de eventos y actualizar su contenido en respuesta a la interacción.

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

Requisito del guion

Los nombres de los elementos personalizados deben incluir un guion. Esto garantiza que nunca entren en conflicto con los elementos HTML integrados actuales o futuros.

my-widget es válido.
mywidget no es válido y produce un error.
Los nombres no distinguen entre mayúsculas y minúsculas, pero se escriben en minúsculas.

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

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

whenDefined y get

Dos métodos útiles del registro:

customElements.get(name) devuelve el constructor o undefined si no está registrado.
customElements.whenDefined(name) devuelve una Promise que se resuelve cuando el elemento está definido.

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

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

Definir una sola vez

Cada nombre solo se puede registrar una vez. Llamar a define con un nombre ya utilizado produce un error. Evite los registros duplicados en módulos compartidos.

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

Por qué importan los elementos personalizados

Los elementos personalizados proporcionan una interfaz de usuario encapsulada, reutilizable e independiente del framework. Permiten:

Estandarizar la reutilización de componentes en cualquier stack.
Integrarse con el propio ciclo de vida del navegador.
Combinarse de forma natural con Shadow DOM y templates, que se tratarán más adelante.

Comprobación rápida

Compruebe si entiende cómo definir elementos personalizados.

Resumen

Ha aprendido a definir elementos personalizados:

customElements.define(name, class) registra una etiqueta.
La clase extends HTMLElement y llama primero a super().
Los nombres deben incluir un guion.
Renderice el contenido en connectedCallback, no en el constructor.
get y whenDefined le ayudan a comprobar el estado del registro.

A continuación, exploraremos el ciclo de vida completo de un elemento personalizado.

Preguntas frecuentes

¿La lección «Definición de elementos personalizados» es gratis?

Sí — el texto completo de «Definición de elementos personalizados» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de JavaScript Academy, actualiza a CoddyKit PRO. El curso de JavaScript Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Definición de elementos personalizados»?

Registre elementos con la API customElements. Practicas JavaScript Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar JavaScript Academy?

No se requiere experiencia previa. JavaScript Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Definición de elementos personalizados»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de JavaScript Academy?

Sí. Cada lección de JavaScript Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

← Volver a JavaScript Academy