当前位置：首页 > 文章列表 > 文章 > 前端 > JavaScript自定义元素API详解

JavaScript自定义元素API详解

2026-03-16 23:26:40 0浏览收藏

Custom Elements API 是 Web Components 的核心支柱，它赋予开发者用纯 JavaScript 定义原生级自定义 HTML 标签的能力——无论是完全独立的 `` 还是增强功能的 `

JavaScriptWeb组件_CustomElementsAPI

Custom Elements API 是 Web Components 的核心部分之一，它允许开发者定义自己的 HTML 标签，并赋予这些标签自定义的行为和结构。通过 JavaScript 来注册新的元素类型，你可以创建可复用、封装良好的组件，直接在 HTML 中使用，无需依赖框架。

什么是 Custom Elements

Custom Elements 让你能够创建全新的 HTML 元素，比如或。这些元素可以像原生标签一样被使用，同时拥有自己的逻辑、样式和生命周期。

浏览器通过 customElements.define() 方法来注册一个自定义元素，该方法接收两个参数：元素名称（必须包含短横线）和一个继承自 HTMLElement 的类。

示例：

class MyButton extends HTMLElement {
  constructor() {
    super();
    this.textContent = '点击我';
    this.style.padding = '10px';
    this.style.background = '#007bff';
    this.style.color = 'white';
    this.style.borderRadius = '4px';
    this.addEventListener('click', () => {
      alert('按钮被点击！');
    });
  }
}

customElements.define('my-button', MyButton);

之后就可以在 HTML 中使用：

<my-button></my-button>

自定义元素的类型

Custom Elements 分为两种类型：自主自定义元素（Autonomous Custom Elements）和自定义内置元素（Customized Built-in Elements）。

自主自定义元素：完全独立的新标签，不继承任何现有 HTML 元素行为。如上面的。元素名必须包含短横线（-），避免与未来 HTML 标签冲突。
自定义内置元素：基于现有 HTML 元素扩展功能。例如让一个按钮表现得像

示例：扩展原生 button

class FancyButton extends HTMLButtonElement {
  connectedCallback() {
    this.style.fontSize = '18px';
    this.style.background = 'linear-gradient(to right, #ff7e5f, #feb47b)';
  }
}

customElements.define('fancy-button', FancyButton, { extends: 'button' });

使用时需写成：

<button is="fancy-button">渐变按钮</button>

生命周期回调

自定义元素类中可以定义多个生命周期钩子，用于控制组件在不同阶段的行为：

connectedCallback：元素插入 DOM 时调用，适合绑定事件或渲染内容。
disconnectedCallback：元素从 DOM 移除时调用，可用于清理定时器或事件监听。
attributeChangedCallback：当观察的属性发生变化时触发，需配合 observedAttributes 静态属性使用。
adoptedCallback：元素被移动到新文档时调用（较少使用）。

示例：响应属性变化

class UserCard extends HTMLElement {
  static get observedAttributes() {
    return ['name', 'role'];
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'name') {
      this.innerHTML = `姓名：${newValue}`;
    }
  }
}

customElements.define('user-card', UserCard);

此时修改 name 属性会触发更新：