Definir elementos con customElements.define
Registre una clase de elemento personalizado en el navegador
Definir elementos con customElements.define es una lección gratuita de HTML 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 HTML Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de HTML Academy incluye 4 lecciones en total.
¿Qué son los elementos personalizados?
Los elementos personalizados le permiten inventar sus propias etiquetas HTML respaldadas por una clase JavaScript. Una vez definidos, <my-card> se comporta como cualquier elemento integrado: puede escribirse en HTML, consultarse, estilizarse, programarse y utilizarse sin cambios dentro de frameworks.
El requisito del guion
Todo nombre de elemento personalizado debe incluir al menos un guion: user-avatar, app-button, my-card. El guion distingue los elementos personalizados de las etiquetas HTML integradas actuales y futuras, y la especificación lo exige.
Definición de una clase
Un elemento personalizado es una clase que extiende HTMLElement (o una subclase de un elemento integrado). La clase puede declarar un constructor y callbacks del ciclo de vida. Las propiedades y métodos públicos de la clase se convierten en su interfaz de scripting.
class MyCard extends HTMLElement {
constructor() {
super();
this.textContent = "Hello from MyCard";
}
}Registro con define
customElements.define("my-card", MyCard) registra la clase con el nombre de etiqueta. Después del registro, todos los <my-card> existentes y futuros del documento se actualizan para convertirse en instancias de la clase.
super() es obligatorio
El constructor debe llamar a super() como su primera instrucción antes de acceder a this. Omitir super() provoca el error "Failed to construct 'HTMLElement'". Trátelo como la regla estándar de los constructores de clases de JavaScript que es.
No lea el DOM en el constructor
El constructor no puede leer los atributos ni los elementos secundarios del elemento, ya que es posible que todavía no se hayan analizado durante la construcción. Traslade la configuración que interactúa con el DOM a connectedCallback, que se ejecuta solo después de que el elemento está en el documento.
El registro es permanente
Un nombre de elemento solo puede registrarse una vez por página. Volver a definir el mismo nombre provoca un error NotSupportedError. Recargue la página para probar cambios durante el desarrollo; en producción, registre cada componente una vez al iniciar.
Polyfills
Los elementos personalizados están disponibles en todos los navegadores modernos. Para navegadores muy antiguos (en su mayoría obsoletos), el polyfill webcomponents.js proporciona una alternativa. Los proyectos nuevos pueden usar la implementación nativa y omitir por completo el polyfill.
Detección del estado de definición
customElements.get("my-card") devuelve la clase si está definida y undefined en caso contrario. customElements.whenDefined("my-card") devuelve una promesa que se resuelve cuando el elemento se registra, lo que resulta útil para el código que necesita esperar a que se definan elementos cargados posteriormente.
customElements.whenDefined("my-card").then((Class) => {
console.log("MyCard is ready");
});Uso del elemento
Una vez definido, use el elemento exactamente como una etiqueta integrada: escríbalo en HTML (<my-card></my-card>), créelo mediante document.createElement("my-card") o instáncielo mediante new MyCard() e insértelo. Las tres rutas producen la misma instancia actualizada.
Convenciones de nomenclatura
Anteceda los elementos personalizados con el nombre del proyecto o de la empresa (cd-card, app-modal) para evitar colisiones con otras bibliotecas de la misma página. El ecosistema de web components no está agrupado: cualquiera que esté en su página puede registrar cualquier nombre y la primera definición es la que prevalece.
Comprobación de conocimientos
¿Por qué debe contener un guion todo nombre de elemento personalizado?
Resumen
Los elementos personalizados son clases JavaScript que extienden HTMLElement y se registran mediante customElements.define("name", Class), donde el nombre debe contener un guion. El constructor debe llamar primero a super() y no debe leer el DOM; posponga el trabajo con el DOM hasta connectedCallback. Los elementos definidos se comportan exactamente como las etiquetas integradas en cualquier contexto.
Preguntas frecuentes
¿La lección «Definir elementos con customElements.define» es gratis?
Sí — el texto completo de «Definir elementos con customElements.define» 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 HTML Academy, actualiza a CoddyKit PRO. El curso de HTML Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Definir elementos con customElements.define»?
Registre una clase de elemento personalizado en el navegador Practicas HTML 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 HTML Academy?
No se requiere experiencia previa. HTML 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 «Definir elementos con customElements.define»?
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 HTML Academy?
Sí. Cada lección de HTML 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
- Definir elementos con customElements.define
- Los callbacks connectedCallback y disconnectedCallback
- Atributos observados y attributeChangedCallback
- Extender elementos integrados