HTML Academy · 课时

使用 customElements.define 定义元素

Q: 「使用 customElements.define 定义元素」这节课中我会学到什么？

向浏览器注册自定义元素类 你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

向浏览器注册自定义元素类

使用 customElements.define 定义元素 是 CoddyKit 上的免费 HTML Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 HTML Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 HTML Academy 课程共包含 4 节课。

什么是自定义元素？

自定义元素允许您创建由 JavaScript 类支持的自定义 HTML 标签。定义后，<my-card> 的行为就像任何内置元素一样：可以在 HTML 中书写、查询、设置样式、编写脚本，也可以原样用于各种框架中。

连字符要求

每个自定义元素名称都必须至少包含一个连字符，例如 user-avatar、app-button、my-card。连字符可以将自定义元素与当前及未来的内置 HTML 标签区分开来，并且这是规范强制要求的。

定义类

自定义元素是继承自 HTMLElement（或某个内置子类）的类。该类可以声明构造函数和生命周期回调。类上的公共属性和方法会成为元素的脚本接口。

class MyCard extends HTMLElement {
  constructor() {
    super();
    this.textContent = "Hello from MyCard";
  }
}

使用 define 注册

customElements.define("my-card", MyCard) 会将该类注册到这个标签名称下。注册后，文档中所有现有及未来的 <my-card> 都会升级为该类的实例。

必须调用 super()

构造函数必须在执行其他操作、使用 this 之前，将 super() 作为第一条语句调用。跳过 super() 会抛出错误“Failed to construct 'HTMLElement'”。请将其视为标准 JavaScript 类构造函数规则。

构造函数中不能读取 DOM

构造函数不能读取元素的属性或子元素，因为在构造时它们可能尚未完成解析。请将操作 DOM 的初始化移到 connectedCallback 中，该回调只会在元素位于文档中之后触发。

注册是永久性的

每个页面中只能注册一次元素名称。重新定义同一个名称会抛出 NotSupportedError。开发过程中请重新加载页面来测试更改；在生产环境中，请在启动时为每个组件注册一次。

填充程序

所有现代浏览器都内置支持自定义元素。对于非常旧的浏览器（大多已经停用），webcomponents.js 填充程序可以提供后备支持。新项目可以直接使用原生支持，完全跳过填充程序。

检测定义状态

customElements.get("my-card") 如果已定义，会返回该类；否则返回未定义值。customElements.whenDefined("my-card") 会返回一个承诺对象，在元素注册完成后解析——这对于需要等待延迟加载定义的代码很有用。

customElements.whenDefined("my-card").then((Class) => {
  console.log("MyCard is ready");
});

使用元素

定义后，可以像使用内置标签一样使用该元素：在 HTML 中书写（<my-card></my-card>）、通过 document.createElement("my-card") 创建，或通过 new MyCard() 实例化后插入。三种方式都会生成相同的已升级实例。

命名约定

请使用项目或公司名称作为自定义元素的前缀（cd-card、app-modal），以避免与同一页面上的其他库发生冲突。网页组件生态系统没有统一打包机制——页面上的任何人都可以注册任意名称，而首次注册会获胜。

知识检查

为什么每个自定义元素名称都必须包含连字符？

总结

自定义元素是继承 HTMLElement 的 JavaScript 类，通过 customElements.define("name", Class) 注册，并且名称必须包含连字符。构造函数必须首先调用 super()，且不能读取 DOM；请将 DOM 操作延迟到 connectedCallback。定义后的元素在任何地方都与内置标签完全一样。

常见问题解答

「使用 customElements.define 定义元素」课时是免费的吗？

是的 — 「使用 customElements.define 定义元素」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 HTML Academy 课程的其余内容，请升级到 CoddyKit PRO。 HTML Academy 课程共包含 4 节课。

「使用 customElements.define 定义元素」这节课中我会学到什么？

向浏览器注册自定义元素类你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 HTML Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 HTML Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「使用 customElements.define 定义元素」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 HTML Academy 课中编写并运行代码吗？

能。每节 HTML Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

使用 customElements.define 定义元素
connectedCallback 和 disconnectedCallback
观测属性与 attributeChangedCallback
扩展内置元素

← 返回 HTML Academy