JavaScript Web Components 实战:使用 Custom Elements 与 Shadow DOM 开发可复用组件

现代前端开发中,组件化已经成为构建复杂界面的常见方式。

React、Vue 和其他框架都提供了组件抽象,但浏览器本身也具备一套原生组件标准,即 Web Components。

通过 Custom Elements、Shadow DOM 和 HTML Template,可以创建不依赖特定前端框架的自定义组件,并在不同页面中复用。

本文以一个可折叠信息面板为例,介绍如何使用浏览器原生 API 实现组件封装、属性同步、事件通信、插槽和样式隔离。

一、Web Components 包含哪些核心技术?

Web Components 并不是单独的 JavaScript 框架,而是多项浏览器标准的组合。

其中最常用的三个部分是:

  • Custom Elements:允许开发者注册自定义 HTML 元素,并定义生命周期行为。
  • Shadow DOM:允许组件拥有独立的 DOM 子树,并提供一定程度的样式隔离。
  • HTML Template:使用模板保存尚未渲染的 HTML 结构,在需要时进行实例化。

这些技术可以配合使用,也可以根据需要独立采用其中某一部分。

例如,一个简单的自定义元素可以只使用 Custom Elements,而复杂的 UI 组件通常还需要 Shadow DOM。

二、定义自定义元素

首先,在页面中准备组件使用位置。

这里使用 info-panel 作为自定义元素名称。

<section class="demo-layout">
  <h1>原生组件演示</h1>

  <info-panel heading="系统通知">
    <p>当前系统运行正常。</p>
  </info-panel>
</section>

<a href="https://www.yxtiktok.com/blog/guides/">

自定义元素名称必须包含连字符,这是 Custom Elements 的命名要求之一。

在 JavaScript 中,可以通过继承 HTMLElement 定义元素行为。

class InfoPanel extends HTMLElement {
  constructor() {
    super();

    this.attachShadow({ mode: "open" });
  }

  connectedCallback() {
    this.render();
  }

  render() {
    const heading = this.getAttribute("heading") ?? "";

    const container = document.createElement("section");
    const title = document.createElement("h2");

    title.textContent = heading;
    container.appendChild(title);

    this.shadowRoot.replaceChildren(container);
  }
}

customElements.define("info-panel", InfoPanel);

注册完成后,浏览器就会识别页面中的 <info-panel> 元素。

connectedCallback() 会在元素被连接到文档时执行。

需要注意,如果元素被反复移除并重新插入,connectedCallback() 可能执行多次,因此初始化逻辑应该具有幂等性。

三、使用 Template 管理复杂组件结构

当组件包含多个按钮、文本区域和状态提示时,直接在 JavaScript 中创建所有 DOM 节点会使代码变得冗长。

HTML Template 可以将组件结构集中管理。

<template id="info-panel-template">
  <style>
    .panel {
      border: 1px solid #d0d7de;
      border-radius: 8px;
      padding: 16px;
    }

    .panel-header {
      display: flex;
      justify-content: space-between;
    }
  </style>

  <section class="panel">
    <header class="panel-header">
      <h2 data-heading></h2>

      <button
        type="button"
        data-toggle
        aria-expanded="true"
      >
        收起
      </button>
    </header>

    <div data-content>
      <slot></slot>
    </div>
  </section>
</template>

<a href="https://www.yxtiktok.com/blog/guides/">

模板内部定义了组件结构和局部样式。

<slot> 用于显示组件使用者提供的内容。

与直接生成整段字符串不同,使用模板可以减少重复的 HTML 创建逻辑。

在生产环境中,通常会在组件模块中统一声明模板,再由各个组件实例克隆使用。

四、实现展开和收起功能

接下来完善组件类,为模板绑定交互逻辑。

class InfoPanel extends HTMLElement {
  constructor() {
    super();

    const template = document.querySelector(
      "#info-panel-template"
    );

    const shadow = this.attachShadow({
      mode: "open"
    });

    shadow.appendChild(
      template.content.cloneNode(true)
    );

    this.button = shadow.querySelector(
      "[data-toggle]"
    );

    this.content = shadow.querySelector(
      "[data-content]"
    );

    this.headingElement = shadow.querySelector(
      "[data-heading]"
    );

    this.handleToggle = () => {
      this.expanded = !this.expanded;
    };
  }

  connectedCallback() {
    this.button.addEventListener(
      "click",
      this.handleToggle
    );

    this.syncHeading();
    this.syncExpanded();
  }

  disconnectedCallback() {
    this.button.removeEventListener(
      "click",
      this.handleToggle
    );
  }

  get expanded() {
    return !this.hasAttribute("collapsed");
  }

  set expanded(value) {
    this.toggleAttribute("collapsed", !value);
  }

  syncExpanded() {
    const expanded = this.expanded;

    this.content.hidden = !expanded;

    this.button.setAttribute(
      "aria-expanded",
      String(expanded)
    );

    this.button.textContent = expanded
      ? "收起"
      : "展开";
  }

  syncHeading() {
    this.headingElement.textContent =
      this.getAttribute("heading") ?? "";
  }
}

这里将展开状态映射到 collapsed 属性。

这种设计的优点是,组件状态不仅可以通过 JavaScript 属性控制,也能通过 HTML 属性进行声明。

组件断开连接时移除事件监听器,避免反复挂载过程中重复绑定事件。

完整注册时,应确保同一个元素名称只注册一次。

五、响应外部属性变化

Web Components 可以通过 observedAttributes 监听属性变化。

例如,父页面更新组件标题时,组件内部的标题也应同步更新。

先准备一个支持动态标题的使用示例:

<section class="panel-controls">
  <button
    type="button"
    data-change-heading
  >
    更新面板标题
  </button>

  <info-panel
    id="dynamic-panel"
    heading="初始标题"
  >
    <p>这里展示动态面板内容。</p>
  </info-panel>
</section>

<a href="https://www.yxtiktok.com/blog/guides/">

在组件类中补充属性观察逻辑:

static get observedAttributes() {
  return ["heading", "collapsed"];
}

attributeChangedCallback(name, oldValue, newValue) {
  if (oldValue === newValue) {
    return;
  }

  if (name === "heading") {
    this.syncHeading();
  }

  if (name === "collapsed") {
    this.syncExpanded();
  }
}

当外部调用 setAttribute() 修改标题时,组件可以立即同步显示内容。

例如:

const panel = document.querySelector(
  "#dynamic-panel"
);

panel.setAttribute(
  "heading",
  "最新系统通知"
);

与框架中的 Props 类似,属性可以承担组件对外暴露的配置接口。

不过,HTML 属性本质上是字符串,因此复杂对象、数组或函数通常更适合通过 JavaScript 属性传递。

六、通过 CustomEvent 与外部页面通信

组件内部的操作有时需要通知外部页面。

例如,信息面板展开或收起后,父页面需要更新统计数据。

使用 CustomEvent 可以定义组件自己的事件。

先创建一个状态展示区域:

<section class="panel-event-demo">
  <h2>组件交互状态</h2>

  <info-panel heading="事件通知测试">
    <p>点击组件按钮可以改变展开状态。</p>
  </info-panel>

  <output data-panel-state>
    等待操作
  </output>
</section>

<a href="https://www.yxtiktok.com/blog/guides/">

在组件的状态更新逻辑中,可以派发事件:

this.dispatchEvent(
  new CustomEvent("panel-toggle", {
    detail: {
      expanded: this.expanded
    },
    bubbles: true,
    composed: true
  })
);

外部页面监听:

document.addEventListener(
  "panel-toggle",
  event => {
    const output = document.querySelector(
      "[data-panel-state]"
    );

    output.textContent = event.detail.expanded
      ? "面板已展开"
      : "面板已收起";
  }
);

bubbles: true 允许事件沿 DOM 向上冒泡。

composed: true 允许事件跨越 Shadow DOM 边界传播。

对于组件库来说,定义稳定的自定义事件接口,比让外部代码直接操作组件内部 DOM 更容易维护。

七、使用 CSS 自定义属性实现主题配置

Shadow DOM 提供样式隔离,但组件仍然需要支持外部主题配置。

CSS 自定义属性是一种常见方式。

例如,在组件内部使用:

.panel {
  color: var(--panel-text-color, #1f2937);
  background: var(--panel-background, #ffffff);
  border-color: var(--panel-border-color, #d0d7de);
}

在页面外部定义:

info-panel {
  --panel-text-color: #e5e7eb;
  --panel-background: #111827;
  --panel-border-color: #374151;
}

这种方式允许外部页面控制组件主题,同时不需要直接访问 Shadow DOM 内部节点。

需要注意,CSS 自定义属性具有继承行为,因此它们可以成为组件公开的样式配置接口。

八、插槽与动态内容

slot 允许自定义元素接收来自外部页面的内容。

例如,可以给组件增加命名插槽,用于展示操作按钮或辅助说明。

<info-panel heading="用户资料">
  <p>用户基础信息</p>

  <button
    slot="actions"
    type="button"
  >
    编辑资料
  </button>
</info-panel>

<a href="https://www.yxtiktok.com/blog/guides/">

相应地,组件模板中需要提供:

<slot name="actions"></slot>

使用命名插槽后,组件结构更加灵活,不需要将所有可变内容都定义为 HTML 属性。

不过,插槽内容仍然属于组件使用者提供的 DOM,不能简单地将 Shadow DOM 样式隔离理解为完全的安全隔离。

九、Web Components 的适用场景

Web Components 特别适合以下需求:

1. 多框架复用

同一个组件需要在原生 JavaScript、Vue、React 或其他项目中使用。

2. 独立业务控件

例如日期选择器、状态标签、数据卡片和轻量级弹窗。

3. 长期维护的组件库

当产品跨多个系统运行时,使用浏览器原生标准有利于降低对单一框架版本的依赖。

4. 微前端集成

不同业务模块可以使用不同技术栈,而公共 UI 控件通过标准自定义元素进行集成。

但是,Web Components 也有需要注意的地方。

Shadow DOM 会影响选择器作用范围;表单关联、服务端渲染、无障碍支持和组件间数据传递都需要按实际业务需求设计。

不能因为采用原生组件标准,就认为这些问题会自动得到解决。

十、总结

Web Components 提供了浏览器原生的组件化能力。

通过 Custom Elements 定义生命周期、Shadow DOM 管理内部结构、Template 复用组件布局,以及 CustomEvent 实现事件通信,可以构建具有较好独立性和可复用性的前端组件。

对于希望降低框架耦合、维护统一 UI 组件库或者构建跨项目业务控件的团队,Web Components 是一种值得考虑的技术方案。

实际开发时,应重点关注属性与状态同步、组件生命周期、样式配置以及无障碍交互,而不是仅仅把普通 HTML 包装成自定义标签。

posted @ 2026-11-16 07:43  YXTK招募助手  阅读(7)  评论(0)    收藏  举报